Merge branch 'search_functions' into 'master'

add search functions for licenses, grants, funders, communities and records

Closes #42

See merge request !108

docs/funder_codemeta.rst

+=======================
+Add funding to metadata
+=======================
+
+
+Find your funding
+#################
+
+
+To add your fundings to your ``codemeta.json`` file, you will need to find its DOI first.
+
+Too find your funding DOI, you may use search engines such as:
+
+- https://search.crossref.org/funding
+- https://ecrcentral.org/funders/
+
+
+Zenodo services
+---------------
+
+1. Through the web portal, when preparing a new upload or editing a record metadata, you can look for funding:
+
+.. image:: images/zenodo_funding.png
+    :width: 600px
+    :align: center
+
+2. Or you may use Zenodo API:
+
+* Online:
+    * funders: https://zenodo.org/api/funders/?q=
+    * grants: https://zenodo.org/api/grants/?q=
+
+* Or using the eOSSR:
+
+.. code-block::
+
+    from eossr.api.zenodo import search_grants
+    search_grants('ESCAPE European Science Cluster of Astronomy & Particle physics ESFRI research infrastructures')
+
+Note Zenodo's search guide to help you refine your search: https://help.zenodo.org/guides/search/
+
+
+Add funding to ``codemeta.json``
+################################
+
+See terms definition on CodeMeta's page.
+
+In codemeta v2.0, funders are provided as a list of organizations and funding is a text entry.
+There is work in progress in schema.org and in codemeta to refine that schema.
+
+However, here is the current suggestion to provide funders in codemeta:
+
+
+.. code-block::
+
+    "funder":[
+        {
+          "@type": "Organization",
+          "name": "European Commission",
+          "@id": "https://doi.org/10.13039/501100000780"
+        }
+      ],
+      "funding": "ESCAPE: European Science Cluster of Astronomy & Particle physics ESFRI research infrastructures; Another funding"

docs/index.rst

@@ -17,6 +17,7 @@ Welcome to eOSSR's documentation!
    notebooks/ossr_statistics.ipynb
    examples
    snippets
+   funder_codemeta
 
 
 Indices and tables

eossr/api/__init__.py

@@ -48,7 +48,7 @@ def get_ossr_records(search='', sandbox=False, **kwargs):
     number_of_ossr_entries = r.json()['aggregations']['access_right']['buckets'][0]['doc_count']
     kwargs['size'] = number_of_ossr_entries
 
-    # if another community is specified, a logical OR is apply be zenodo API,
+    # if another community is specified, a logical OR is apply by zenodo API,
     # thus potentially finding entries that are not part of escape2020
     # ruling out that possibility at the moment
     if 'communities' in kwargs and kwargs['communities'] != escape_community:
@@ -75,5 +75,3 @@ def get_ossr_pending_requests(**params):
     """
     zen = ZenodoAPI()
     return zen.get_community_pending_requests(escape_community, params)
-    
-

eossr/api/zenodo/__init__.py

@@ -26,7 +26,12 @@ __all__ = [
     'get_zenodo_records',
     'http_status',
     'Record',
-    'SimilarRecordError'
+    'SimilarRecordError',
+    'search_records',
+    'search_communities',
+    'search_funders',
+    'search_grants',
+    'search_licenses',
 ]
 
 
@@ -824,30 +829,8 @@ def get_zenodo_records(search='', sandbox=False, **kwargs):
     :return: [Record]
         list of records
     """
-    search = search.replace("/", " ")  # zenodo can't handle '/' in search query
-
-    params = {
-        'q': search,
-        **kwargs
-    }
-
-    params.setdefault('size', 100)
-
-    def lowercase(param):
-        if isinstance(param, str):
-            param = param.lower()
-        if isinstance(param, list):
-            param = [char.lower() for char in param]
-        return param
-
-    for param_name in ['communities', 'type', 'file_type']:
-        if param_name in kwargs:
-            params[param_name] = lowercase(kwargs[param_name])
-
-    api_url = zenodo_sandbox_api_url if sandbox else zenodo_api_url
-    url = api_url + "/records?" + urlencode(params, doseq=True)
-
-    recs = [Record(hit) for hit in requests.get(url).json()["hits"]["hits"]]
+    hits = search_records(search=search, sandbox=sandbox, **kwargs)
+    recs = [Record(hit) for hit in hits]
 
     if not recs:
         raise LookupError(f"No records found for search {search}")
@@ -875,3 +858,212 @@ def get_record(record_id, sandbox=False):
         return Record(answer)
 
 
+def _query(field, search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param field: str
+        where to search: 'records', 'funders', 'grants', 'communities', 'licenses'
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 100
+            - all_versions: int
+                Show (1) or hide (0) all versions of records
+            - type: string or list[string]
+                Records of the specified type (Publication, Poster, Presentation, Software, ...)
+                A logical OR is applied in case of a list
+            - keywords: string or list[string]
+                Records with the specified keywords
+                 A logical OR is applied in case of a list
+            - communities: string or list[string]
+                Records from the specified keywords
+                A logical OR is applied in case of a list
+            - file_type: string or list[string]
+                Records from the specified keywords
+                A logical OR is applied in case of a list
+    :return: `requests.response`
+    """
+
+    def lowercase(param):
+        if isinstance(param, str):
+            param = param.lower()
+        if isinstance(param, list):
+            param = [char.lower() for char in param]
+        return param
+
+    search = search.replace("/", " ")  # zenodo can't handle '/' in search query
+
+    params = {
+        'q': search,
+        **kwargs
+    }
+
+    params.setdefault('size', 100)
+
+    for param_name in ['communities', 'type', 'file_type']:
+        if param_name in kwargs:
+            params[param_name] = lowercase(kwargs[param_name])
+
+    api_url = zenodo_api_url if not sandbox else zenodo_sandbox_api_url
+    url = api_url + f"/{field}?" + urlencode(params, doseq=True)
+
+    response = requests.get(url)
+    return response
+
+
+def _search(field, search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param field: str
+        where to search: 'records', 'funders', 'grants', 'communities', 'licenses'
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 100
+            - all_versions: int
+                Show (1) or hide (0) all versions of records
+            - type: string or list[string]
+                Records of the specified type (Publication, Poster, Presentation, Software, ...)
+                A logical OR is applied in case of a list
+            - keywords: string or list[string]
+                Records with the specified keywords
+                 A logical OR is applied in case of a list
+            - communities: string or list[string]
+                Records from the specified keywords
+                A logical OR is applied in case of a list
+            - file_type: string or list[string]
+                Records from the specified keywords
+                A logical OR is applied in case of a list
+    :return: [dict]
+    """
+
+    query = _query(field, search=search, sandbox=sandbox, **kwargs)
+    http_status.ZenodoHTTPStatus(query.status_code, query.json())
+
+    hits = [hit for hit in query.json()["hits"]["hits"]]
+    return hits
+
+
+def search_records(search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 100
+            - all_versions: int
+                Show (1) or hide (0) all versions of records
+            - type: string or list[string]
+                Records of the specified type (Publication, Poster, Presentation, Software, ...)
+                A logical OR is applied in case of a list
+            - keywords: string or list[string]
+                Records with the specified keywords
+                 A logical OR is applied in case of a list
+            - communities: string or list[string]
+                Records from the specified keywords
+                A logical OR is applied in case of a list
+            - file_type: string or list[string]
+                Records from the specified keywords
+                A logical OR is applied in case of a list
+    :return: [dict]
+    """
+    hits = _search('records', search=search, sandbox=sandbox, **kwargs)
+    return hits
+
+
+def search_funders(search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 5
+    :return: [dict]
+    """
+    kwargs.setdefault('size', 5)
+    hits = _search('funders', search=search, sandbox=sandbox, **kwargs)
+    return hits
+
+
+def search_grants(search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 5
+    :return: [dict]
+    """
+    kwargs.setdefault('size', 5)
+    hits = _search('grants', search=search, sandbox=sandbox, **kwargs)
+    return hits
+
+
+def search_communities(search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 5
+    :return: [dict]
+    """
+    kwargs.setdefault('size', 5)
+    hits = _search('communities', search=search, sandbox=sandbox, **kwargs)
+    return hits
+
+
+def search_licenses(search='', sandbox=False, **kwargs):
+    """
+    https://help.zenodo.org/guides/search/
+
+    :param search: str
+    :param sandbox: boolean
+        True to search in the sandbox
+    :param kwargs: Zenodo query arguments.
+        For an exhaustive list, see the query arguments at https://developers.zenodo.org/#list36
+        Common arguments are:
+            - size: int
+                Number of results to return
+                Default = 5
+    :return: [dict]
+    """
+    kwargs.setdefault('size', 5)
+    hits = _search('licenses', search=search, sandbox=sandbox, **kwargs)
+    return hits

eossr/api/zenodo/tests/test_zenodo.py

@@ -10,6 +10,7 @@ import time
 from pathlib import Path
 from eossr import ROOT_DIR
 from eossr.api.zenodo import ZenodoAPI, get_zenodo_records, get_record, Record
+from eossr.api import zenodo
 
 
 eossr_test_lib_id = 930570  # test library in sandbox (owner: T. Vuillaume)
@@ -154,7 +155,6 @@ class TestZenodoAPIToken(unittest.TestCase):
         assert record_id not in [rec.id for rec in records]
 
 
-
 def test_get_zenodo_records():
     l = get_zenodo_records('ESCAPE template project')
     assert len(l) > 1
@@ -195,3 +195,29 @@ def test_write_record_zenodo(test_get_record_4923992, tmpdir):
         json_dict = json.load(file)
     assert json_dict['conceptdoi'] == '10.5281/zenodo.3572654'
 
+
+def test_search_records():
+    records = zenodo.search_records('conceptrecid:5524912')
+    assert records[0]['metadata']['title'] == 'eossr'
+
+
+def test_search_funders():
+    funders = zenodo.search_funders('name:European+Commission')
+    assert len(funders) > 1
+
+
+def test_search_grants():
+    grants = zenodo.search_grants('code:824064')
+    assert len(grants) == 1
+    assert grants[0]['metadata']['acronym'] == 'ESCAPE'
+
+
+def test_search_license():
+    licenses = zenodo.search_licenses('id:MIT')
+    assert licenses[0]['metadata']['title'] == 'MIT License'
+
+
+def test_search_communities():
+    communities = zenodo.search_communities('escape2020')
+    assert communities[0]['title'] == 'ESCAPE 2020'
+