added/fixed some tests, changed all use of start to offset in params

updated changelog
bumped to v0.2

Changelog.rst

@@ -8,10 +8,18 @@ Changelog
 - Fixed docs for `occurrences.get`, and `occurrences.get_verbatim`,
 `occurrences.get_fragment` and demo that used occurrence keys that no longer
 exist in GBIF (#39)
-- xxx (#xx)
-- xxx (#xx)
-- xxx (#xx)
-- xxx (#xx)
+- Added `organizations` method to `registry` module (#12)
+- Added remainder of datasets methods: `registry.dataset_search` (including faceting support (#37))
+and `registry.dataset_suggest`, for the `/dataset/search` and `/dataset/suggest` routes, respectively (#40)
+- Added remainder of species methods: `species.name_lookup` (including faceting support (#38)) and
+`species.name_usage`, for the `/species/search` and `/species` routes, respectively (#18)
+- Added more tests to cover new methods
+- Changed `species.name_suggest` to give back data stucture as received from GBIF.
+We used to parse out the classification data, but for simplicity and speed, that is
+left up to the user now.
+- `start` parameter in `species.name_suggest`, `occurrences.download_list`, `registry.organizations`,
+`registry.nodes`, `registry.networks`, and `registry.installations`, changed to `offset` to match
+GBIF API and match usage throughout remainder of `pygbif`
 
 0.1.5.4 (2016-10-01)
 --------------------

pygbif/__init__.py

@@ -36,12 +36,12 @@
 		occurrences.search(geometry='POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))', limit=20)
 '''
 
-__version__ = '0.1.6.0'
+__version__ = '0.2.0'
 __title__ = 'pygbif'
 __author__ = 'Scott Chamberlain'
 __license__ = 'MIT'
 
 from .occurrences import search, get, count, download
-from .species import name_parser, name_suggest, name_backbone, name_lookup
+from .species import name_parser, name_suggest, name_backbone, name_lookup, name_usage
 from .registry import datasets, nodes, networks, organizations, installations
 from .gbifissues import occ_issues_lookup

pygbif/occurrences/download.py

@@ -323,28 +323,28 @@ def download_meta(key, **kwargs):
     return gbif_GET(url, {}, **kwargs)
 
 
-def download_list(user=None, pwd=None, limit=20, start=0):
+def download_list(user=None, pwd=None, limit=20, offset=0):
     """
     Lists the downloads created by a user.
 
     :param user: [str] A user name, look at env var ``GBIF_USER`` first
     :param pwd: [str] Your password, look at env var ``GBIF_PWD`` first
     :param limit: [int] Number of records to return. Default: ``20``
-    :param start: [int] Record number to start at. Default: ``0``
+    :param offset: [int] Record number to start at. Default: ``0``
 
     Usage::
 
       from pygbif import occurrences as occ
       occ.download_list(user = "sckott")
       occ.download_list(user = "sckott", limit = 5)
-      occ.download_list(user = "sckott", start = 21)
+      occ.download_list(user = "sckott", offset = 21)
     """
 
     user = _check_environ('GBIF_USER', user)
     pwd = _check_environ('GBIF_PWD', pwd)
 
     url = 'http://api.gbif.org/v1/occurrence/download/user/' + user
-    args = {'limit': limit, 'offset': start}
+    args = {'limit': limit, 'offset': offset}
     res = gbif_GET(url, args, auth=(user, pwd))
     return {'meta': {'offset': res['offset'],
                      'limit': res['limit'],

pygbif/occurrences/search.py

@@ -127,7 +127,7 @@ def search(taxonKey=None, repatriated=None,
         occurrences.search(catalogNumber="49366", limit=20)
         # occurrences.search(catalogNumber=["49366","Bird.27847588"], limit=20)
 
-        # Use paging parameters (limit and start) to page. Note the different results
+        # Use paging parameters (limit and offset) to page. Note the different results
         # for the two queries below.
         occurrences.search(datasetKey='7b5d6a48-f762-11e1-a439-00145eb45e9a', offset=10, limit=5)
         occurrences.search(datasetKey='7b5d6a48-f762-11e1-a439-00145eb45e9a', offset=20, limit=5)

pygbif/registry/installations.py

@@ -1,23 +1,32 @@
 from ..gbifutils import *
 
-def installations(data = 'all', uuid = None, query = None, identifier = None,
-  identifierType = None, limit = 100, start = None, **kwargs):
+def installations(data = 'all', uuid = None, q = None, identifier = None,
+  identifierType = None, limit = 100, offset = None, **kwargs):
   '''
   Installations metadata.
 
   :param data: [str] The type of data to get. Default is all data. If not ``all``, then one
      or more of ``contact``, ``endpoint``, ``dataset``, ``comment``, ``deleted``, ``nonPublishing``.
   :param uuid: [str] UUID of the data node provider. This must be specified if data
      is anything other than ``all``.
-  :param query: [str] Query nodes. Only used when ``data='all'``. Ignored otherwise.
+  :param q: [str] Query nodes. Only used when ``data='all'``. Ignored otherwise.
+  :param identifier: [fixnum] The value for this parameter can be a simple string or integer,
+      e.g. identifier=120
+  :param identifierType: [str] Used in combination with the identifier parameter to filter
+      identifiers by identifier type: ``DOI``, ``FTP``, ``GBIF_NODE``, ``GBIF_PARTICIPANT``,
+      ``GBIF_PORTAL``, ``HANDLER``, ``LSID``, ``UNKNOWN``, ``URI``, ``URL``, ``UUID``
+  :param limit: [int] Number of results to return. Default: ``100``
+  :param offset: [int] Record to start at. Default: ``0``
+
+  :return: A dictionary
 
   References: http://www.gbif.org/developer/registry#installations
 
   Usage::
 
       from pygbif import registry
       registry.installations(limit=5)
-      registry.installations(query="france")
+      registry.installations(q="france")
       registry.installations(uuid="b77901f9-d9b0-47fa-94e0-dd96450aa2b4")
       registry.installations(data='contact', uuid="b77901f9-d9b0-47fa-94e0-dd96450aa2b4")
       registry.installations(data='contact', uuid="2e029a0c-87af-42e6-87d7-f38a50b78201")
@@ -28,7 +37,8 @@ def installations(data = 'all', uuid = None, query = None, identifier = None,
       registry.installations(data=['deleted','nonPublishing'], limit=2)
       registry.installations(identifierType='DOI', limit=2)
   '''
-  args = {'q': query, 'limit': limit, 'offset': start}
+  args = {'q': q, 'limit': limit, 'offset': offset, 'identifier': identifier,
+    'identifierType': identifierTyp}
   data_choices = ['all', 'contact', 'endpoint', 'dataset',
    'identifier', 'tag', 'machineTag', 'comment',
    'deleted', 'nonPublishing']

pygbif/registry/networks.py

@@ -1,18 +1,25 @@
 from ..gbifutils import *
 
-def networks(data = 'all', uuid = None, query = None, identifier = None,
-  identifierType = None, limit = 100, start = None, **kwargs):
+def networks(data = 'all', uuid = None, q = None, identifier = None,
+  identifierType = None, limit = 100, offset = None, **kwargs):
   '''
   Networks metadata.
 
   :param data: [str] The type of data to get. Default: ``all``
   :param uuid: [str] UUID of the data network provider. This must be specified if data
      is anything other than ``all``.
-  :param query: [str] Query networks. Only used when ``data = 'all'``. Ignored otherwise.
+  :param q: [str] Query networks. Only used when ``data = 'all'``. Ignored otherwise.
+  :param identifier: [fixnum] The value for this parameter can be a simple string or integer,
+      e.g. identifier=120
+  :param identifierType: [str] Used in combination with the identifier parameter to filter
+      identifiers by identifier type: ``DOI``, ``FTP``, ``GBIF_NODE``, ``GBIF_PARTICIPANT``,
+      ``GBIF_PORTAL``, ``HANDLER``, ``LSID``, ``UNKNOWN``, ``URI``, ``URL``, ``UUID``
+  :param limit: [int] Number of results to return. Default: ``100``
+  :param offset: [int] Record to start at. Default: ``0``
 
-  References: http://www.gbif.org/developer/registry#networks
+  :return: A dictionary
 
-  :return: A dict
+  References: http://www.gbif.org/developer/registry#networks
 
   Usage::
 
@@ -21,7 +28,8 @@ def networks(data = 'all', uuid = None, query = None, identifier = None,
       registry.networks(uuid='16ab5405-6c94-4189-ac71-16ca3b753df7')
       registry.networks(data='endpoint', uuid='16ab5405-6c94-4189-ac71-16ca3b753df7')
   '''
-  args = {'q': query, 'limit': limit, 'offset': start}
+  args = {'q': q, 'limit': limit, 'offset': offset, 'identifier': identifier,
+    'identifierType': identifierType}
   data_choices = ['all', 'contact', 'endpoint', 'identifier',
     'tag', 'machineTag', 'comment', 'constituents']
   check_data(data, data_choices)

pygbif/registry/nodes.py

@@ -1,22 +1,32 @@
 from ..gbifutils import *
 
-def nodes(data = 'all', uuid = None, query = None, identifier = None,
-  identifierType = None, limit = 100, start = None, isocode = None, **kwargs):
+def nodes(data = 'all', uuid = None, q = None, identifier = None,
+  identifierType = None, limit = 100, offset = None, isocode = None, **kwargs):
   '''
   Nodes metadata.
 
   :param data: [str] The type of data to get. Default: ``all``
   :param uuid: [str] UUID of the data node provider. This must be specified if data
      is anything other than ``all``.
-  :param query: [str] Query nodes. Only used when ``data = 'all'``
+  :param q: [str] Query nodes. Only used when ``data = 'all'``
+  :param identifier: [fixnum] The value for this parameter can be a simple string or integer,
+      e.g. identifier=120
+  :param identifierType: [str] Used in combination with the identifier parameter to filter
+      identifiers by identifier type: ``DOI``, ``FTP``, ``GBIF_NODE``, ``GBIF_PARTICIPANT``,
+      ``GBIF_PORTAL``, ``HANDLER``, ``LSID``, ``UNKNOWN``, ``URI``, ``URL``, ``UUID``
+  :param limit: [int] Number of results to return. Default: ``100``
+  :param offset: [int] Record to start at. Default: ``0``
   :param isocode: [str] A 2 letter country code. Only used if ``data = 'country'``.
 
+  :return: A dictionary
+
   References http://www.gbif.org/developer/registry#nodes
 
   Usage::
 
       from pygbif import registry
       registry.nodes(limit=5)
+      registry.nodes(identifier=120)
       registry.nodes(uuid="1193638d-32d1-43f0-a855-8727c94299d8")
       registry.nodes(data='identifier', uuid="03e816b3-8f58-49ae-bc12-4e18b358d6d9")
       registry.nodes(data=['identifier','organization','comment'], uuid="03e816b3-8f58-49ae-bc12-4e18b358d6d9")
@@ -34,7 +44,8 @@ def nodes(data = 'all', uuid = None, query = None, identifier = None,
 
       [ registry.nodes(data='identifier', uuid=x) for x in uuids ]
   '''
-  args = {'q': query, 'limit': limit, 'offset': start}
+  args = {'q': q, 'limit': limit, 'offset': offset, 'identifier': identifier,
+    'identifierType': identifierType }
   data_choices = ['all', 'organization', 'endpoint',
      'identifier', 'tag', 'machineTag', 'comment',
      'pendingEndorsement', 'country', 'dataset', 'installation']

pygbif/registry/organizations.py

@@ -1,7 +1,7 @@
 from ..gbifutils import *
 
-def organizations(data = 'all', uuid = None, query = None, identifier = None,
-  identifierType = None, limit = 100, start = None, **kwargs):
+def organizations(data = 'all', uuid = None, q = None, identifier = None,
+  identifierType = None, limit = 100, offset = None, **kwargs):
   '''
   organizations metadata.
 
@@ -11,15 +11,25 @@ def organizations(data = 'all', uuid = None, query = None, identifier = None,
      ``nonPublishing``.
   :param uuid: [str] UUID of the data node provider. This must be specified if data
      is anything other than ``all``.
-  :param query: [str] Query nodes. Only used when ``data='all'``. Ignored otherwise.
+  :param q: [str] Query nodes. Only used when ``data='all'``. Ignored otherwise.
+  :param identifier: [fixnum] The value for this parameter can be a simple string or integer,
+      e.g. identifier=120
+  :param identifierType: [str] Used in combination with the identifier parameter to filter
+      identifiers by identifier type: ``DOI``, ``FTP``, ``GBIF_NODE``, ``GBIF_PARTICIPANT``,
+      ``GBIF_PORTAL``, ``HANDLER``, ``LSID``, ``UNKNOWN``, ``URI``, ``URL``, ``UUID``
+  :param limit: [int] Number of results to return. Default: ``100``
+  :param offset: [int] Record to start at. Default: ``0``
+
+  :return: A dictionary
 
   References: http://www.gbif.org/developer/registry#organizations
 
   Usage::
 
       from pygbif import registry
       registry.organizations(limit=5)
-      registry.organizations(query="france")
+      registry.organizations(q="france")
+      registry.organizations(identifier=120)
       registry.organizations(uuid="e2e717bf-551a-4917-bdc9-4fa0f342c530")
       registry.organizations(data='contact', uuid="e2e717bf-551a-4917-bdc9-4fa0f342c530")
       registry.organizations(data='endpoint', uuid="e2e717bf-551a-4917-bdc9-4fa0f342c530")
@@ -28,7 +38,8 @@ def organizations(data = 'all', uuid = None, query = None, identifier = None,
       registry.organizations(data=['deleted','nonPublishing'], limit=2)
       registry.organizations(identifierType='DOI', limit=2)
   '''
-  args = {'q': query, 'limit': limit, 'offset': start}
+  args = {'q': q, 'limit': limit, 'offset': offset, 'identifier': identifier,
+    'identifierType': identifierType}
   data_choices = ['all', 'contact', 'endpoint',
     'identifier', 'tag', 'machineTag', 'comment', 'hostedDataset',
     'ownedDataset', 'deleted', 'pending', 'nonPublishing']

pygbif/species/name_backbone.py

@@ -2,7 +2,7 @@
 
 def name_backbone(name, rank=None, kingdom=None, phylum=None, clazz=None,
   order=None, family=None, genus=None, strict=False, verbose=False,
-  start=None, limit=100, **kwargs):
+  offset=None, limit=100, **kwargs):
   '''
   Lookup names in the GBIF backbone taxonomy.
 
@@ -23,6 +23,8 @@ def name_backbone(name, rank=None, kingdom=None, phylum=None, clazz=None,
   :param strict: [bool] If True it (fuzzy) matches only the given name, but never a
      taxon in the upper classification (optional)
   :param verbose: [bool] If True show alternative matches considered which had been rejected.
+  :param offset: [int] Record to start at. Default: ``0``
+  :param limit: [int] Number of results to return. Default: ``100``
 
   A list for a single taxon with many slots (with ``verbose=False`` - default), or a
   list of length two, first element for the suggested taxon match, and a data.frame
@@ -56,6 +58,6 @@ def name_backbone(name, rank=None, kingdom=None, phylum=None, clazz=None,
   url = gbif_baseurl + 'species/match'
   args = {'name': name, 'rank': rank, 'kingdom': kingdom, 'phylum': phylum,
          'class': clazz, 'order': order, 'family': family, 'genus': genus,
-         'strict': strict, 'verbose': verbose, 'offset': start, 'limit': limit}
+         'strict': strict, 'verbose': verbose, 'offset': offset, 'limit': limit}
   tt = gbif_GET(url, args, **kwargs)
   return tt

pygbif/species/name_lookup.py

@@ -138,5 +138,4 @@ def name_lookup(q=None, rank=None, higherTaxonKey=None, status=None, isExtinct=N
 			xx = dict(zip( [ re.sub('_', '.', x) for x in gbif_kwargs.keys() ], gbif_kwargs.values() ))
 			args.update(xx)
 	kwargs = {key: kwargs[key] for key in kwargs if key in requests_argset}
-	tt = gbif_GET(gbif_baseurl + 'species/search', args, **kwargs)
-	return tt
+	return gbif_GET(gbif_baseurl + 'species/search', args, **kwargs)

pygbif/species/name_suggest.py

@@ -1,12 +1,10 @@
 from ..gbifutils import *
 
-def name_suggest(q=None, datasetKey=None, rank=None, fields=None, start=None, limit=100, **kwargs):
+def name_suggest(q=None, datasetKey=None, rank=None, limit=100, offset=None, **kwargs):
   '''
   A quick and simple autocomplete service that returns up to 20 name usages by
   doing prefix matching against the scientific name. Results are ordered by relevance.
 
-  References: http://www.gbif.org/developer/species#searching
-
   :param q: [str] Simple search parameter. The value for this parameter can be a
      simple word or a phrase. Wildcards can be added to the simple word parameters only,
      e.g. ``q=*puma*`` (Required)
@@ -17,28 +15,28 @@ def name_suggest(q=None, datasetKey=None, rank=None, fields=None, start=None, li
      ``subfamily``, ``subform``, ``subgenus``, ``subkingdom``, ``suborder``, ``subphylum``, ``subsection``, ``subseries``,
      ``subspecies``, ``subtribe``, ``subvariety``, ``superclass``, ``superfamily``, ``superorder``, ``superphylum``,
      ``suprageneric_name``, ``tribe``, ``unranked``, or ``variety``.
+  :param limit: [fixnum] Number of records to return. Maximum: ``1000``. (optional)
+  :param offset: [fixnum] Record number to start at. (optional)
 
-  :return: A dictionary, of results
+  :return: A dictionary
+
+  References: http://www.gbif.org/developer/species#searching
 
   Usage::
 
       from pygbif import species
+
       species.name_suggest(q='Puma concolor')
       x = species.name_suggest(q='Puma')
-      x['data']
-      x['hierarchy']
       species.name_suggest(q='Puma', rank="genus")
       species.name_suggest(q='Puma', rank="subspecies")
       species.name_suggest(q='Puma', rank="species")
       species.name_suggest(q='Puma', rank="infraspecific_name")
       species.name_suggest(q='Puma', limit=2)
   '''
   url = gbif_baseurl + 'species/suggest'
-  args = {'q':q, 'rank':rank, 'offset':start, 'limit':limit}
-  tt = gbif_GET(url, args, **kwargs)
-  hier = [ x['higherClassificationMap'] for x in tt ]
-  [ x.pop('higherClassificationMap') for x in tt ]
-  return {'data': tt, 'hierarchy': hier}
+  args = {'q':q, 'rank':rank, 'offset':offset, 'limit':limit}
+  return gbif_GET(url, args, **kwargs)
 
 
 def suggestfields():

test/test-registry-dataset_metrics.py

@@ -0,0 +1,16 @@
+"""Tests for registry module - dataset_metrics method"""
+import os
+from pygbif import registry
+
+def test_dataset_metrics():
+    "registry.dataset_metrics - basic test"
+    res = registry.dataset_metrics(uuid='3f8a1297-3259-4700-91fc-acc4170b27ce')
+    assert dict == res.__class__
+    assert 19 == len(res)
+
+def test_dataset_metrics_multiple_uuids():
+    "registry.dataset_metrics - multiple uuids"
+    uuids = ['3f8a1297-3259-4700-91fc-acc4170b27ce', '66dd0960-2d7d-46ee-a491-87b9adcfe7b1']
+    res = registry.dataset_metrics(uuids)
+    assert list == res.__class__
+    assert 2 == len(res)

test/test-registry-datasets.py

@@ -1,4 +1,4 @@
-"""Tests for registry module - datasets methods"""
+"""Tests for registry module - datasets method"""
 import os
 from pygbif import registry
 
@@ -25,15 +25,3 @@ def test_datasets_type():
     assert 100 == len(res['results'])
     assert 'OCCURRENCE' == list(set(vv))[0]
 
-def test_dataset_metrics():
-    "registry.dataset_metrics - basic test"
-    res = registry.dataset_metrics(uuid='3f8a1297-3259-4700-91fc-acc4170b27ce')
-    assert dict == res.__class__
-    assert 19 == len(res)
-
-def test_dataset_metrics_multiple_uuids():
-    "registry.dataset_metrics - multiple uuids"
-    uuids = ['3f8a1297-3259-4700-91fc-acc4170b27ce', '66dd0960-2d7d-46ee-a491-87b9adcfe7b1']
-    res = registry.dataset_metrics(uuids)
-    assert list == res.__class__
-    assert 2 == len(res)