Fixing query, updating doc

Author: villanueval

README.md

@@ -2,7 +2,7 @@
 
 # EDAN python
 
-Basic python3 module to query the Smithsonian's Enterprise Digital Asset Network (EDAN).
+Basic python3 module to query the Smithsonian's Enterprise Digital Asset Network (EDAN). Requires Python 3.11 or higher.
 
 ## Installation
 
@@ -12,25 +12,23 @@ Install using pip:
 pip install edan
 ```
 
-## Load the module
-
-Save the file `edan.py` and load it as a module:
+Then, load the module:
 
 ```python
 import edan
 ```
 
 ## Search EDAN
 
-Set your credentials and use `edan.searchEDAN()`:
+Set your credentials and use `edan.edan_metadata_search()`:
 
 ```python
 #EDAN creds
 AppID = "APP_ID"
 AppKey = "verylong_key"
 
 #Search for images of orchids from Smithsonian Gardens
-results = edan.edan_metadata_search("orchids smithsonian gardens images", AppID, AppKey)
+results = edan.edan_metadata_search("orchids smithsonian gardens images", AppID=AppID, AppKey=AppKey)
 
 #Number of results available for this search
 results['rowCount']
@@ -42,6 +40,7 @@ results_rows = results['rows']
 The function `edan_metadata_search()` takes these arguments:
 
  * edan_query = Search items
+ * fqs = JSON array of filter query parameters
  * AppID = Your AppID
  * AppKey = Your AppKey
  * rows = How many rows to return, max is 100, default is 10
@@ -52,7 +51,7 @@ The function `edan_metadata_search()` takes these arguments:
 ```python
 import json
 
-item = edan.edan_content_getcontent(results['rows'][0]['url'], AppID, AppKey)
+item = edan.edan_content_getcontent(results['rows'][0]['url'], AppID=AppID, AppKey=AppKey)
 ```
 
 The function `edan_content_getcontent()` takes these arguments (must provide `id` or `url`):

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "edan"
-version = "0.3"
+version = "0.4"
 authors = [
   { name="Luis J. Villanueva", email="villanueval@si.edu" },
 ]

src/edan/edan.py

@@ -1,13 +1,12 @@
 #!/usr/bin/env python3
 #
 # Search metadata in the EDAN API
-# v 0.3
+# v 0.4
 # 
 
 import urllib.parse
 import urllib.request
-import datetime
-import email.utils
+import time
 import uuid
 import hashlib
 import json
@@ -24,13 +23,13 @@ def query_edan(edan_q, url, AppID=None, AppKey=None):
     Execute the query
     """
     # Date of request
-    dt = datetime.datetime.now()
-    RequestDate = email.utils.format_datetime(dt)
-    # Generated uniquely for this request
-    Nonce = str(uuid.uuid4()).replace('-', '')
+    RequestDate = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
+    # Nonce generated uniquely for this request
+    #   using UUIDv4
+    Nonce = uuid.uuid4().hex
     # This will be the value of X-AuthContent, each element is joined by a single newline
     StringToSign = "{}\n{}\n{}\n{}".format(Nonce, edan_q, RequestDate, AppKey)
-    # First hash using SHA1
+    # Hash using SHA1
     HashedString = hashlib.sha1(StringToSign.encode('utf-8')).hexdigest()
     # Base64 encode
     EncodedString = b64encode(HashedString.encode('utf-8')).decode('utf-8')
@@ -53,75 +52,85 @@ def query_edan(edan_q, url, AppID=None, AppKey=None):
         return json.loads(data)
 
 
-def edan_metadata_search(edan_query, AppID=None, AppKey=None, rows=10, start=0):
+def edan_content_getcontent(id=None, url=None, AppID=None, AppKey=None):
     """
-    Returns structured data rows about the piece of content addressed.
+    Get details from an item using an EDAN ID
     """
     if AppID is None:
         raise ValueError("Missing AppID")
     if AppKey is None:
         raise ValueError("Missing AppKey")
     # Request
-    edan_query = urllib.parse.quote_plus(edan_query)
-    edan_q = "q={}&rows={}&start={}&facet=true".format(edan_query, rows, start)
+    if id != None:
+        edan_q = "id={}".format(id)
+    elif url != None:
+        edan_q = "url={}".format(url)
     # Put whole thing together
-    url = 'https://edan.si.edu/metadata/v2.0/metadata/search.htm?{}'.format(edan_q)
+    url = 'https://edan.si.edu/content/v2.0/content/getContent.htm?{}'.format(edan_q)
     # Execute query
     result = query_edan(edan_q, url, AppID, AppKey)
     return result
 
 
-def edan_metadata_suggestions(edan_query, AppID=None, AppKey=None, rows=10, start=0):
+def edan_metadata_search(edan_query=None, fqs=None, AppID=None, AppKey=None, rows=10, start=0):
     """
-    Returns suggested content for a given search term.
+    Returns structured data rows about the piece of content addressed.
     """
     if AppID is None:
         raise ValueError("Missing AppID")
     if AppKey is None:
         raise ValueError("Missing AppKey")
     # Request
-    edan_query = urllib.parse.quote_plus(edan_query)
-    edan_q = "suggest={}".format(edan_query)
+    if edan_query is None and fqs is None:
+        raise ValueError("Missing edan_query or fqs")
+    if edan_query is not None:
+        edan_query = urllib.parse.quote_plus(edan_query)
+    else:
+        edan_query = ""
+    if fqs is not None:
+        fqs_query = urllib.parse.quote_plus(fqs)
+    else:
+        fqs_query = ""
+    edan_q = "q={}&fqs={}rows={}&start={}&facet=true".format(edan_query, fqs_query, rows, start)
     # Put whole thing together
-    url = 'https://edan.si.edu/metadata/v2.0/metadata/getSuggestions.htm?{}'.format(edan_q)
+    url = 'https://edan.si.edu/metadata/v2.0/metadata/search.htm?{}'.format(edan_q)
     # Execute query
     result = query_edan(edan_q, url, AppID, AppKey)
     return result
 
 
-def edan_metadata_getFacets(edan_query, AppID=None, AppKey=None, limit=100, mincount=1, offset=0, sort="index"):
+def edan_metadata_suggestions(edan_query, AppID=None, AppKey=None):
     """
-    Returns facets found for a given search term. All requests will timeout after 30 seconds and may return incomplete results; measuring performance is required before implementing in a production environment.
+    Returns suggested content for a given search term.
     """
     if AppID is None:
         raise ValueError("Missing AppID")
     if AppKey is None:
         raise ValueError("Missing AppKey")
     # Request
     edan_query = urllib.parse.quote_plus(edan_query)
-    edan_q = "q={}&limit={}&mincount={}&offset={}&sort={}".format(edan_query, limit, mincount, offset, sort)
+    edan_q = "suggest={}".format(edan_query)
     # Put whole thing together
-    url = 'https://edan.si.edu/metadata/v2.0/metadata/getFacets.htm?{}'.format(edan_q)
+    url = 'https://edan.si.edu/metadata/v2.0/metadata/getSuggestions.htm?{}'.format(edan_q)
     # Execute query
     result = query_edan(edan_q, url, AppID, AppKey)
     return result
 
 
-def edan_content_getcontent(id=None, url=None, AppID=None, AppKey=None):
+def edan_metadata_getFacets(edan_query, AppID=None, AppKey=None, limit=100, mincount=1, offset=0, sort="index"):
     """
-    Get details from an item using an EDAN ID
+    Returns facets found for a given search term. All requests will timeout after 30 seconds and may return incomplete results; measuring performance is required before implementing in a production environment.
     """
     if AppID is None:
         raise ValueError("Missing AppID")
     if AppKey is None:
         raise ValueError("Missing AppKey")
     # Request
-    if id != None:
-        edan_q = "id={}".format(id)
-    elif url != None:
-        edan_q = "url={}".format(url)
+    edan_query = urllib.parse.quote_plus(edan_query)
+    edan_q = "q={}&limit={}&mincount={}&offset={}&sort={}".format(edan_query, limit, mincount, offset, sort)
     # Put whole thing together
-    url = 'https://edan.si.edu/content/v2.0/content/getContent.htm?{}'.format(edan_q)
+    url = 'https://edan.si.edu/metadata/v2.0/metadata/getFacets.htm?{}'.format(edan_q)
     # Execute query
     result = query_edan(edan_q, url, AppID, AppKey)
     return result
+