Skip to content

Commit f92b65a

Browse files
Merge pull request #36 from stac-utils/mah/change_api_to_client
Rename API to Client, update CLI
2 parents a373a8f + 48fb534 commit f92b65a

File tree

15 files changed

+86
-80
lines changed

15 files changed

+86
-80
lines changed

CHANGELOG.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
88

99
### Added
1010

11-
- #33: Simple date string search for items
12-
1311
### Fixed
1412

1513
### Changed
1614

1715
### Removed
1816

19-
## [v0.1.0] - 2021-04-02
17+
## [v0.1.0] - 2021-04-14
2018

2119
Initial release.
2220

23-
[Unreleased]: <https://github.com/stac-utils/pystac-api-client/compare/v0.1.0...main>
24-
[v0.1.0]: <https://github.com/stac-utils/pystac-api-client/tree/v0.1.0>
21+
[Unreleased]: <https://github.com/stac-utils/pystac-client/compare/v0.1.0...main>
22+
[v0.1.0]: <https://github.com/stac-utils/pystac-client/tree/v0.1.0>
2523

README.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,10 @@ $ stac-client search --url https://earth-search.aws.element84.com/v0 -c sentinel
3030
1999 items matched
3131
```
3232

33-
The environment variable `STAC API URL` can be set instead of having to explicitly set the URL with every call:
33+
The environment variable `STAC_URL` can be set instead of having to explicitly set the Catalog URL with every call:
3434

3535
```
36-
$ export STAC_API_URL=https://earth-search.aws.element84.com/v0
36+
$ export STAC_URL=https://earth-search.aws.element84.com/v0
3737
$ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime 2020-01-01/2020-01-31
3838
48 items matched
3939
```
@@ -54,7 +54,7 @@ The `--save` switch will save all fetched items (as with `--stdout`) to a file.
5454
$ 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
5555
```
5656

57-
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.
57+
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.
5858

5959
```
6060
<property><operator><value>
@@ -80,14 +80,14 @@ $ stac-client search -c sentinel-s2-l2a-cogs --bbox -72.5 40.5 -72 41 --datetime
8080
To use the Python library, first an API instance is created for a specific STAC API (use the root URL)
8181

8282
```
83-
import pystac_client as client
83+
from pystac_client import Client
8484
85-
api = client.API.open("https://earth-search.aws.element84.com/v0")
85+
catalog = Client.open("https://earth-search.aws.element84.com/v0")
8686
```
8787

8888
Create a search
8989
```
90-
mysearch = api.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
90+
mysearch = catalog.search(collections=['sentinel-s2-l2a-cogs'], bbox=[-72.5,40.5,-72,41], max_items=10)
9191
print(f"{mysearch.matched()} items found")
9292
```
9393

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
API Reference
1+
Client Reference
22
=============
33

44
.. module:: pystac_client
55

66
Main Package
77
------------
88

9-
.. autoclass:: pystac_client.API
9+
.. autoclass:: pystac_client.Client
1010
:members:
1111
:undoc-members:
1212
:show-inheritance:

pystac_client/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
from pystac_client.item_collection import ItemCollection
88
from pystac_client.extensions import APIExtensions
99
from pystac_client.item_search import ItemSearch
10-
from pystac_client.api import API
10+
from pystac_client.client import Client
1111
from pystac_client.conformance import ConformanceClasses
1212

1313
from pystac_client.stac_io import read_text_method

pystac_client/cli.py

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,35 +6,39 @@
66

77
from .item_collection import ItemCollection
88

9-
from .api import API
9+
from .client import Client
1010
from .version import __version__
1111

12-
API_URL = os.getenv('STAC_API_URL', None)
12+
STAC_URL = os.getenv('STAC_URL', None)
1313

14+
logger = logging.getLogger(__name__)
1415

15-
def search(url=API_URL, save=None, stdout=False, **kwargs):
16+
17+
def search(url=STAC_URL, matched=False, save=None, **kwargs):
1618
""" Main function for performing a search """
1719

1820
try:
19-
api = API.open(url)
20-
search = api.search(**kwargs)
21+
catalog = Client.open(url)
22+
search = catalog.search(**kwargs)
2123

22-
if stdout or save:
24+
if matched:
25+
matched = search.matched()
26+
print('%s items matched' % matched)
27+
else:
2328
items = ItemCollection(search.items())
2429
if save:
2530
with open(save, 'w') as f:
2631
f.write(json.dumps(items.to_dict()))
2732
else:
2833
print(json.dumps(items.to_dict()))
29-
else:
30-
matched = search.matched()
31-
print('%s items matched' % matched)
34+
3235
except Exception as e:
36+
logger.error(e, exc_info=True)
3337
print(e)
3438

3539

3640
def parse_args(args):
37-
desc = 'STAC API Client'
41+
desc = 'STAC Client'
3842
dhf = argparse.ArgumentDefaultsHelpFormatter
3943
parser0 = argparse.ArgumentParser(description=desc)
4044

@@ -44,7 +48,7 @@ def parse_args(args):
4448
action='version',
4549
version=__version__)
4650
parent.add_argument('--logging', default='INFO', help='DEBUG, INFO, WARN, ERROR, CRITICAL')
47-
parent.add_argument('--url', help='Root API URL', default=os.getenv('STAC_API_URL', None))
51+
parent.add_argument('--url', help='Root Catalog URL', default=os.getenv('STAC_URL', None))
4852
parent.add_argument('--limit', help='Page size limit', type=int, default=500)
4953
parent.add_argument('--headers',
5054
help='Additional request headers (JSON file or string)',
@@ -82,8 +86,8 @@ def parse_args(args):
8286
type=int)
8387

8488
output_group = parser.add_argument_group('output options')
85-
output_group.add_argument('--stdout',
86-
help='Print results to stdout (also disables logging)',
89+
output_group.add_argument('--matched',
90+
help='Print number matched',
8791
default=False,
8892
action='store_true')
8993
output_group.add_argument('--save', help='Filename to save Item collection to', default=None)
@@ -109,12 +113,16 @@ def cli():
109113
args = parse_args(sys.argv[1:])
110114

111115
loglevel = args.pop('logging')
112-
if not args.get('stdout', False):
116+
# don't enable logging if print to stdout
117+
if args.get('save', False) or args.get('matched', False):
113118
logging.basicConfig(stream=sys.stdout, level=loglevel)
114119
# quiet loggers
115120
for lg in ['urllib3']:
116121
logging.getLogger(lg).propagate = False
117122

123+
if args.get('url', None) is None:
124+
raise RuntimeError('No STAC URL provided')
125+
118126
cmd = args.pop('command')
119127
if cmd == 'search':
120128
search(**args)
Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,14 @@
1919
from pystac_client.stac_api_object import STACAPIObjectMixin
2020

2121

22-
class API(pystac.Catalog, STACAPIObjectMixin):
23-
"""Instances of the ``API`` class inherit from :class:`pystac.Catalog` and provide a convenient way of interacting
24-
with APIs that conform to the `STAC API spec <https://github.com/radiantearth/stac-api-spec>`_. In addition to being
25-
a valid `STAC Catalog <https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md>`_ the
22+
class Client(pystac.Catalog, STACAPIObjectMixin):
23+
"""Instances of the ``Client`` class inherit from :class:`pystac.Catalog` and provide a convenient way of interacting
24+
with Catalogs OR APIs that conform to the `STAC API spec <https://github.com/radiantearth/stac-api-spec>`_. In addition
25+
to being a valid `STAC Catalog <https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md>`_ the
2626
API must have a ``"conformsTo"`` property that lists the conformance URIs.
2727
28-
All :class:`~pystac_client.API` instances must be given a ``conformance`` argument at instantiation, and when calling
29-
the :meth:`~pystac_client.API.from_dict` method the dictionary must contain a ``"conformsTo"`` attribute. If this is
28+
All :class:`~pystac_client.Client` instances must be given a ``conformance`` argument at instantiation, and when calling
29+
the :meth:`~pystac_client.Client.from_dict` method the dictionary must contain a ``"conformsTo"`` attribute. If this is
3030
not true then a :exc:`KeyError` is raised.
3131
3232
In addition to the methods and attributes inherited from :class:`pystac.Catalog`, this class offers some convenience
@@ -69,24 +69,24 @@ def __init__(self,
6969
self.headers = {}
7070

7171
def __repr__(self):
72-
return '<API id={}>'.format(self.id)
72+
return '<Catalog id={}>'.format(self.id)
7373

7474
@classmethod
7575
def open(cls, url, headers={}):
76-
"""Alias for PySTAC's STAC Obkect `from_file` method
76+
"""Alias for PySTAC's STAC Object `from_file` method
7777
7878
Parameters
7979
----------
8080
url : str
81-
The URL of a STAC API Catalog
81+
The URL of a STAC Catalog
8282
8383
Returns
8484
-------
85-
api : API
85+
catalog : Client
8686
"""
87-
api = cls.from_file(url)
88-
api.headers = headers
89-
return api
87+
catalog = cls.from_file(url)
88+
catalog.headers = headers
89+
return catalog
9090

9191
@classmethod
9292
def from_dict(
@@ -101,7 +101,7 @@ def from_dict(
101101
Raises
102102
------
103103
pystac_client.exceptions.ConformanceError
104-
If the API does not publish conformance URIs in either a ``"conformsTo"`` attribute in the landing page
104+
If the Catalog does not publish conformance URIs in either a ``"conformsTo"`` attribute in the landing page
105105
response or in a ``/conformance``. According to the STAC API - Core spec, services must publish this as
106106
part of a ``"conformsTo"`` attribute, but some legacy APIs fail to do so.
107107
"""
@@ -119,7 +119,7 @@ def from_dict(
119119

120120
d.pop('stac_version')
121121

122-
api = cls(
122+
catalog = cls(
123123
id=id,
124124
description=description,
125125
title=title,
@@ -133,16 +133,16 @@ def from_dict(
133133
for link in links:
134134
if link['rel'] == 'root':
135135
# Remove the link that's generated in Catalog's constructor.
136-
api.remove_links('root')
136+
catalog.remove_links('root')
137137

138138
if link['rel'] != 'self' or href is None:
139-
api.add_link(pystac.Link.from_dict(link))
139+
catalog.add_link(pystac.Link.from_dict(link))
140140

141-
return api
141+
return catalog
142142

143143
@classmethod
144144
def get_collections_list(self):
145-
"""Gets list of available collections from this API. Alias for get_child_links since children
145+
"""Gets list of available collections from this Catalog. Alias for get_child_links since children
146146
of an API are always and only ever collections
147147
"""
148148
return self.get_child_links()

pystac_client/extensions/base.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
from pystac.extensions import ExtensionError
66
from pystac.extensions.base import CatalogExtension, CollectionExtension, ItemExtension
77

8-
from pystac_client.api import API
8+
from pystac_client.client import Client
99
from pystac_client.item_collection import ItemCollection
1010
from pystac_client.item_search import ItemSearch
1111

@@ -28,7 +28,7 @@ class ExtendedObject:
2828
The class of the extension (e.g. :class:`~pystac_client.extensions.context.ContextAPIExtension`)
2929
"""
3030
def __init__(self, stac_object_class, extension_class):
31-
if stac_object_class is API:
31+
if stac_object_class is Client:
3232
if not issubclass(extension_class, APIExtension):
3333
raise ExtensionError(
3434
"Classes extending API instances must inherit from APIExtension")
@@ -111,13 +111,13 @@ def __init_subclass__(cls):
111111

112112
class APIExtension(ABC):
113113
@classmethod
114-
def _from_object(cls, stac_object: API):
114+
def _from_object(cls, stac_object: Client):
115115
return cls.from_api(stac_object)
116116

117117
@classmethod
118118
@abstractmethod
119-
def from_api(cls, api: API):
120-
"""Creates an instance of the extension from an :class:`~pystac_client.API` instance."""
119+
def from_api(cls, api: Client):
120+
"""Creates an instance of the extension from an :class:`~pystac_client.Client` instance."""
121121

122122
@classmethod
123123
@abstractmethod

pystac_client/extensions/context.py

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
from pystac.extensions.base import ExtensionDefinition
66

7-
from pystac_client import API, APIExtensions, ConformanceClasses
7+
from pystac_client import Client, APIExtensions, ConformanceClasses
88
from pystac_client.extensions import base
99
from pystac_client.item_collection import ItemCollection
1010

@@ -20,9 +20,9 @@ class ContextItemCollectionExtension(base.ItemCollectionFragment):
2020
Examples
2121
--------
2222
23-
>>> from pystac_client import API
24-
>>> api = API.from_file(...)
25-
>>> results = api.search(bbox=..., datetime=..., ...)
23+
>>> from pystac_client import Client
24+
>>> catalog = Client.from_file(...)
25+
>>> results = catalog.search(bbox=..., datetime=..., ...)
2626
>>> for i, page in enumerate(results.item_collections()):
2727
... print(f'Page {i + 1}:')
2828
... print(f'\tMatched: {page.api_ext.context.matched}')
@@ -87,19 +87,19 @@ class ContextAPIExtension(base.APIExtension):
8787
:class:`~pystac_client.conformance.STAC_API_ITEM_SEARCH_CONTEXT_EXT` conformance URIs in its ``"conformsTo"``
8888
attribute.
8989
90-
>>> from pystac_client import API, ConformanceClasses
91-
>>> api = API.from_file(...)
90+
>>> from pystac_client import Client, ConformanceClasses
91+
>>> api = Client.from_file(...)
9292
>>> api.api_ext.implements(ConformanceClasses.STAC_API_ITEM_SEARCH_CONTEXT_EXT)
9393
True
9494
"""
9595

9696
conformance = ConformanceClasses.STAC_API_ITEM_SEARCH_CONTEXT_EXT
9797
"""See the :class:`~pystac_client.conformance.STAC_API_ITEM_SEARCH_CONTEXT_EXT` for valid conformance URIs."""
98-
def __init__(self, api: API):
98+
def __init__(self, api: Client):
9999
self.api = api
100100

101101
@classmethod
102-
def from_api(cls, api: API):
102+
def from_api(cls, api: Client):
103103
return cls(api)
104104

105105
@classmethod
@@ -108,6 +108,6 @@ def _object_links(cls):
108108

109109

110110
CONTEXT_EXTENSION_DEFINITION = ExtensionDefinition(APIExtensions.CONTEXT, [
111-
base.ExtendedObject(API, ContextAPIExtension),
111+
base.ExtendedObject(Client, ContextAPIExtension),
112112
base.ExtendedObject(ItemCollection, ContextItemCollectionExtension)
113113
])

pystac_client/stac_api_object.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ class APIExtensionIndex:
1515
To access a specific extension, use the __getitem__ on this class with the
1616
extension ID:
1717
18-
>>> from pystac_client import API
19-
>>> api = API.from_file(...)
18+
>>> from pystac_client import Client
19+
>>> api = Client.from_file(...)
2020
>>> api.api_ext.context
2121
<pystac_client.extensions.context.ContextAPIExtension object at 0x1035669d0>
2222
"""

tests/cassettes/test_api/TestAPI.test_from_file.yaml renamed to tests/cassettes/test_client/TestAPI.test_from_file.yaml

File renamed without changes.

0 commit comments

Comments
 (0)