Merge pull request #36 from stac-utils/mah/change_api_to_client

Rename API to Client, update CLI

Author: matthewhanson

CHANGELOG.md

@@ -8,18 +8,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
-- #33: Simple date string search for items
-
 ### Fixed
 
 ### Changed
 
 ### Removed
 
-## [v0.1.0] - 2021-04-02
+## [v0.1.0] - 2021-04-14
 
 Initial release.
 
-[Unreleased]: <https://github.com/stac-utils/pystac-api-client/compare/v0.1.0...main>
-[v0.1.0]: <https://github.com/stac-utils/pystac-api-client/tree/v0.1.0>
+[Unreleased]: <https://github.com/stac-utils/pystac-client/compare/v0.1.0...main>
+[v0.1.0]: <https://github.com/stac-utils/pystac-client/tree/v0.1.0>
 

README.md

@@ -30,10 +30,10 @@ $ stac-client search --url https://earth-search.aws.element84.com/v0 -c sentinel
 1999 items matched
 ```
 
-The environment variable `STAC API URL` can be set instead of having to explicitly set the URL with every call:
+The environment variable `STAC_URL` can be set instead of having to explicitly set the Catalog URL with every call:
 
 ```
-$ export STAC_API_URL=https://earth-search.aws.element84.com/v0 
+$ export STAC_URL=https://earth-search.aws.element84.com/v0 
 $ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31
 48 items matched
 ```
@@ -54,7 +54,7 @@ The `--save` switch will save all fetched items (as with `--stdout`) to a file.
 $ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31 --save items.json
 ```
 
-If the API supports the [Query extension](https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query), any Item property can also be included in the search. Rather than requiring the JSON syntax the Query extension uses, pystac-client uses a simpler syntax that it will translate to the JSON equivalent. 
+If the Catalog supports the [Query extension](https://github.com/radiantearth/stac-api-spec/tree/master/fragments/query), any Item property can also be included in the search. Rather than requiring the JSON syntax the Query extension uses, pystac-client uses a simpler syntax that it will translate to the JSON equivalent. 
 
 ```
 <property><operator><value>
@@ -80,14 +80,14 @@ $ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime
 To use the Python library, first an API instance is created for a specific STAC API (use the root URL)
 
 ```
-import pystac_client as client
+from pystac_client import Client
 
-api = client.API.open("https://earth-search.aws.element84.com/v0")
+catalog = Client.open("https://earth-search.aws.element84.com/v0")
 ```
 
 Create a search
 ```
-mysearch = api.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
+mysearch = catalog.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
 print(f"{mysearch.matched()} items found")
 ```
 

docs/source/api.rst docs/source/client.rstdocs/source/api.rst renamed to docs/source/client.rst

@@ -1,12 +1,12 @@
-API Reference
+Client Reference
 =============
 
 .. module:: pystac_client
 
 Main Package
 ------------
 
-.. autoclass:: pystac_client.API
+.. autoclass:: pystac_client.Client
     :members:
     :undoc-members:
     :show-inheritance:

pystac_client/__init__.py

@@ -7,7 +7,7 @@
 from pystac_client.item_collection import ItemCollection
 from pystac_client.extensions import APIExtensions
 from pystac_client.item_search import ItemSearch
-from pystac_client.api import API
+from pystac_client.client import Client
 from pystac_client.conformance import ConformanceClasses
 
 from pystac_client.stac_io import read_text_method

pystac_client/cli.py

@@ -6,35 +6,39 @@
 
 from .item_collection import ItemCollection
 
-from .api import API
+from .client import Client
 from .version import __version__
 
-API_URL = os.getenv('STAC_API_URL', None)
+STAC_URL = os.getenv('STAC_URL', None)
 
+logger = logging.getLogger(__name__)
 
-def search(url=API_URL, save=None, stdout=False, **kwargs):
+
+def search(url=STAC_URL, matched=False, save=None, **kwargs):
     """ Main function for performing a search """
 
     try:
-        api = API.open(url)
-        search = api.search(**kwargs)
+        catalog = Client.open(url)
+        search = catalog.search(**kwargs)
 
-        if stdout or save:
+        if matched:
+            matched = search.matched()
+            print('%s items matched' % matched)
+        else:
             items = ItemCollection(search.items())
             if save:
                 with open(save, 'w') as f:
                     f.write(json.dumps(items.to_dict()))
             else:
                 print(json.dumps(items.to_dict()))
-        else:
-            matched = search.matched()
-            print('%s items matched' % matched)
+
     except Exception as e:
+        logger.error(e, exc_info=True)
         print(e)
 
 
 def parse_args(args):
-    desc = 'STAC API Client'
+    desc = 'STAC Client'
     dhf = argparse.ArgumentDefaultsHelpFormatter
     parser0 = argparse.ArgumentParser(description=desc)
 
@@ -44,7 +48,7 @@ def parse_args(args):
                         action='version',
                         version=__version__)
     parent.add_argument('--logging', default='INFO', help='DEBUG, INFO, WARN, ERROR, CRITICAL')
-    parent.add_argument('--url', help='Root API URL', default=os.getenv('STAC_API_URL', None))
+    parent.add_argument('--url', help='Root Catalog URL', default=os.getenv('STAC_URL', None))
     parent.add_argument('--limit', help='Page size limit', type=int, default=500)
     parent.add_argument('--headers',
                         help='Additional request headers (JSON file or string)',
@@ -82,8 +86,8 @@ def parse_args(args):
                               type=int)
 
     output_group = parser.add_argument_group('output options')
-    output_group.add_argument('--stdout',
-                              help='Print results to stdout (also disables logging)',
+    output_group.add_argument('--matched',
+                              help='Print number matched',
                               default=False,
                               action='store_true')
     output_group.add_argument('--save', help='Filename to save Item collection to', default=None)
@@ -109,12 +113,16 @@ def cli():
     args = parse_args(sys.argv[1:])
 
     loglevel = args.pop('logging')
-    if not args.get('stdout', False):
+    # don't enable logging if print to stdout
+    if args.get('save', False) or args.get('matched', False):
         logging.basicConfig(stream=sys.stdout, level=loglevel)
         # quiet loggers
         for lg in ['urllib3']:
             logging.getLogger(lg).propagate = False
 
+    if args.get('url', None) is None:
+        raise RuntimeError('No STAC URL provided')
+
     cmd = args.pop('command')
     if cmd == 'search':
         search(**args)

pystac_client/api.py pystac_client/client.pypystac_client/api.py renamed to pystac_client/client.py

@@ -19,14 +19,14 @@
 from pystac_client.stac_api_object import STACAPIObjectMixin
 
 
-class API(pystac.Catalog, STACAPIObjectMixin):
-    """Instances of the ``API`` class inherit from :class:`pystac.Catalog` and provide a convenient way of interacting
-    with APIs that conform to the `STAC API spec <https://github.com/radiantearth/stac-api-spec>`_. In addition to being
-    a valid `STAC Catalog <https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md>`_ the
+class Client(pystac.Catalog, STACAPIObjectMixin):
+    """Instances of the ``Client`` class inherit from :class:`pystac.Catalog` and provide a convenient way of interacting
+    with Catalogs OR APIs that conform to the `STAC API spec <https://github.com/radiantearth/stac-api-spec>`_. In addition
+    to being a valid `STAC Catalog <https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md>`_ the
     API must have a ``"conformsTo"`` property that lists the conformance URIs.
 
-    All :class:`~pystac_client.API` instances must be given a ``conformance`` argument at instantiation, and when calling
-    the :meth:`~pystac_client.API.from_dict` method the dictionary must contain a ``"conformsTo"`` attribute. If this is
+    All :class:`~pystac_client.Client` instances must be given a ``conformance`` argument at instantiation, and when calling
+    the :meth:`~pystac_client.Client.from_dict` method the dictionary must contain a ``"conformsTo"`` attribute. If this is
     not true then a :exc:`KeyError` is raised.
 
     In addition to the methods and attributes inherited from :class:`pystac.Catalog`, this class offers some convenience
@@ -69,24 +69,24 @@ def __init__(self,
         self.headers = {}
 
     def __repr__(self):
-        return '<API id={}>'.format(self.id)
+        return '<Catalog id={}>'.format(self.id)
 
     @classmethod
     def open(cls, url, headers={}):
-        """Alias for PySTAC's STAC Obkect `from_file` method
+        """Alias for PySTAC's STAC Object `from_file` method
 
         Parameters
         ----------
         url : str
-            The URL of a STAC API Catalog
+            The URL of a STAC Catalog
 
         Returns
         -------
-        api : API
+        catalog : Client
         """
-        api = cls.from_file(url)
-        api.headers = headers
-        return api
+        catalog = cls.from_file(url)
+        catalog.headers = headers
+        return catalog
 
     @classmethod
     def from_dict(
@@ -101,7 +101,7 @@ def from_dict(
         Raises
         ------
         pystac_client.exceptions.ConformanceError
-            If the API does not publish conformance URIs in either a ``"conformsTo"`` attribute in the landing page
+            If the Catalog does not publish conformance URIs in either a ``"conformsTo"`` attribute in the landing page
             response or in a ``/conformance``. According to the STAC API - Core spec, services must publish this as
             part of a ``"conformsTo"`` attribute, but some legacy APIs fail to do so.
         """
@@ -119,7 +119,7 @@ def from_dict(
 
         d.pop('stac_version')
 
-        api = cls(
+        catalog = cls(
             id=id,
             description=description,
             title=title,
@@ -133,16 +133,16 @@ def from_dict(
         for link in links:
             if link['rel'] == 'root':
                 # Remove the link that's generated in Catalog's constructor.
-                api.remove_links('root')
+                catalog.remove_links('root')
 
             if link['rel'] != 'self' or href is None:
-                api.add_link(pystac.Link.from_dict(link))
+                catalog.add_link(pystac.Link.from_dict(link))
 
-        return api
+        return catalog
 
     @classmethod
     def get_collections_list(self):
-        """Gets list of available collections from this API. Alias for get_child_links since children
+        """Gets list of available collections from this Catalog. Alias for get_child_links since children
             of an API are always and only ever collections
         """
         return self.get_child_links()

pystac_client/extensions/base.py

@@ -5,7 +5,7 @@
 from pystac.extensions import ExtensionError
 from pystac.extensions.base import CatalogExtension, CollectionExtension, ItemExtension
 
-from pystac_client.api import API
+from pystac_client.client import Client
 from pystac_client.item_collection import ItemCollection
 from pystac_client.item_search import ItemSearch
 
@@ -28,7 +28,7 @@ class ExtendedObject:
         The class of the extension (e.g. :class:`~pystac_client.extensions.context.ContextAPIExtension`)
     """
     def __init__(self, stac_object_class, extension_class):
-        if stac_object_class is API:
+        if stac_object_class is Client:
             if not issubclass(extension_class, APIExtension):
                 raise ExtensionError(
                     "Classes extending API instances must inherit from APIExtension")
@@ -111,13 +111,13 @@ def __init_subclass__(cls):
 
 class APIExtension(ABC):
     @classmethod
-    def _from_object(cls, stac_object: API):
+    def _from_object(cls, stac_object: Client):
         return cls.from_api(stac_object)
 
     @classmethod
     @abstractmethod
-    def from_api(cls, api: API):
-        """Creates an instance of the extension from an :class:`~pystac_client.API` instance."""
+    def from_api(cls, api: Client):
+        """Creates an instance of the extension from an :class:`~pystac_client.Client` instance."""
 
     @classmethod
     @abstractmethod

pystac_client/extensions/context.py

@@ -4,7 +4,7 @@
 
 from pystac.extensions.base import ExtensionDefinition
 
-from pystac_client import API, APIExtensions, ConformanceClasses
+from pystac_client import Client, APIExtensions, ConformanceClasses
 from pystac_client.extensions import base
 from pystac_client.item_collection import ItemCollection
 
@@ -20,9 +20,9 @@ class ContextItemCollectionExtension(base.ItemCollectionFragment):
     Examples
     --------
 
-    >>> from pystac_client import API
-    >>> api = API.from_file(...)
-    >>> results = api.search(bbox=..., datetime=..., ...)
+    >>> from pystac_client import Client
+    >>> catalog = Client.from_file(...)
+    >>> results = catalog.search(bbox=..., datetime=..., ...)
     >>> for i, page in enumerate(results.item_collections()):
     ...     print(f'Page {i + 1}:')
     ...     print(f'\tMatched: {page.api_ext.context.matched}')
@@ -87,19 +87,19 @@ class ContextAPIExtension(base.APIExtension):
     :class:`~pystac_client.conformance.STAC_API_ITEM_SEARCH_CONTEXT_EXT` conformance URIs in its ``"conformsTo"``
     attribute.
 
-    >>> from pystac_client import API, ConformanceClasses
-    >>> api = API.from_file(...)
+    >>> from pystac_client import Client, ConformanceClasses
+    >>> api = Client.from_file(...)
     >>> api.api_ext.implements(ConformanceClasses.STAC_API_ITEM_SEARCH_CONTEXT_EXT)
     True
     """
 
     conformance = ConformanceClasses.STAC_API_ITEM_SEARCH_CONTEXT_EXT
     """See the :class:`~pystac_client.conformance.STAC_API_ITEM_SEARCH_CONTEXT_EXT` for valid conformance URIs."""
-    def __init__(self, api: API):
+    def __init__(self, api: Client):
         self.api = api
 
     @classmethod
-    def from_api(cls, api: API):
+    def from_api(cls, api: Client):
         return cls(api)
 
     @classmethod
@@ -108,6 +108,6 @@ def _object_links(cls):
 
 
 CONTEXT_EXTENSION_DEFINITION = ExtensionDefinition(APIExtensions.CONTEXT, [
-    base.ExtendedObject(API, ContextAPIExtension),
+    base.ExtendedObject(Client, ContextAPIExtension),
     base.ExtendedObject(ItemCollection, ContextItemCollectionExtension)
 ])

pystac_client/stac_api_object.py

@@ -15,8 +15,8 @@ class APIExtensionIndex:
     To access a specific extension, use the __getitem__ on this class with the
     extension ID:
 
-    >>> from pystac_client import API
-    >>> api = API.from_file(...)
+    >>> from pystac_client import Client
+    >>> api = Client.from_file(...)
     >>> api.api_ext.context
     <pystac_client.extensions.context.ContextAPIExtension object at 0x1035669d0>
     """