Skip to content

Commit 3f589ab

Browse files
lossyroblossyrob
committed
Additional documentation additions.
1 parent 615ccb3 commit 3f589ab

12 files changed

+287
-22
lines changed

‎.flake8

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[flake8]
2+
max-line-length = 100
3+
4+
## IGNORES
5+
6+
# E127: flake8 reporting incorrect continuation line indent errors
7+
# on multi-line and multi-level indents
8+
9+
# W503: flake8 reports this as incorrect, and scripts/format_code
10+
# changes code to it, so let format_code win.
11+
12+
ignore = E127,W503

‎docs/api.rst

+150
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
API Reference
2+
=============
3+
4+
This API reference is autogenerated for the Python docstrings,
5+
and organized by the section of the `STAC Spec <https://github.com/radiantearth/stac-spec/tree/v0.8.0>`_ they relate to, if related to a specific spec item.
6+
7+
Links
8+
-----
9+
10+
Catalogs, Collections and Items have links, which allow users to crawl catalogs.
11+
12+
.. autoclass:: pystac.Link
13+
:members:
14+
:undoc-members:
15+
16+
.. autoclass:: pystac.LinkType
17+
:members:
18+
:undoc-members:
19+
20+
STAC_IO
21+
-------
22+
23+
STAC_IO is the utility mechanism that PySTAC uses for reading and writing. Users of PySTAC can hook into PySTAC by overriding members to utilize their own IO methods.
24+
25+
.. autoclass:: pystac.STAC_IO
26+
:members:
27+
:undoc-members:
28+
:exclude-members: stac_object_from_dict, STAC_OBJECT_CLASSES
29+
30+
31+
32+
Catalog Spec
33+
------------
34+
35+
These classes are representations of the `Catalog Spec <https://github.com/radiantearth/stac-spec/tree/v0.8.0/catalog-spec>`_.
36+
37+
.. autoclass:: pystac.Catalog
38+
:members:
39+
:inherited-members:
40+
:undoc-members:
41+
:show-inheritance:
42+
43+
.. autoclass:: pystac.CatalogType
44+
:members:
45+
:inherited-members:
46+
:undoc-members:
47+
48+
49+
Collection Spec
50+
---------------
51+
52+
These classes are representations of the `Collection Spec <https://github.com/radiantearth/stac-spec/tree/v0.8.0/collection-spec>`_.
53+
54+
.. autoclass:: pystac.Collection
55+
:members:
56+
:inherited-members:
57+
:undoc-members:
58+
:show-inheritance:
59+
60+
.. autoclass:: pystac.Extent
61+
:members:
62+
:undoc-members:
63+
64+
.. autoclass:: pystac.SpatialExtent
65+
:members:
66+
:undoc-members:
67+
68+
.. autoclass:: pystac.TemporalExtent
69+
:members:
70+
:undoc-members:
71+
72+
.. autoclass:: pystac.Provider
73+
:members:
74+
:undoc-members:
75+
76+
Item Spec
77+
---------
78+
79+
These classes are representations of the `Item Spec <https://github.com/radiantearth/stac-spec/tree/v0.8.0/item-spec>`_.
80+
81+
.. autoclass:: pystac.Item
82+
:members:
83+
:inherited-members:
84+
:undoc-members:
85+
:show-inheritance:
86+
87+
.. autoclass:: pystac.Asset
88+
:members:
89+
:undoc-members:
90+
91+
EO Extension
92+
---------------
93+
94+
These classes are representations of the `EO Extension Spec <https://github.com/radiantearth/stac-spec/tree/v0.8.0/extensions/eo>`_.
95+
96+
.. autoclass:: pystac.EOItem
97+
:members:
98+
:inherited-members:
99+
:undoc-members:
100+
:show-inheritance:
101+
102+
.. autoclass:: pystac.EOAsset
103+
:members:
104+
:inherited-members:
105+
:undoc-members:
106+
:show-inheritance:
107+
108+
.. autoclass:: pystac.Band
109+
:members:
110+
:undoc-members:
111+
112+
113+
Label Extension
114+
---------------
115+
116+
These classes are representations of the `Label Extension Spec <https://github.com/radiantearth/stac-spec/tree/v0.8.0/extensions/label>`_.
117+
118+
.. autoclass:: pystac.LabelItem
119+
:members:
120+
:inherited-members:
121+
:undoc-members:
122+
:show-inheritance:
123+
124+
.. autoclass:: pystac.LabelType
125+
:members:
126+
:undoc-members:
127+
128+
.. autoclass:: pystac.LabelClasses
129+
:members:
130+
:undoc-members:
131+
132+
.. autoclass:: pystac.LabelOverview
133+
:members:
134+
:undoc-members:
135+
136+
.. autoclass:: pystac.LabelCount
137+
:members:
138+
:undoc-members:
139+
140+
.. autoclass:: pystac.LabelStatistics
141+
:members:
142+
:undoc-members:
143+
144+
145+
PySTAC Internal Classes
146+
-----------------------
147+
148+
.. autoclass:: pystac.resolved_object_cache.ResolvedObjectCache
149+
:members:
150+
:undoc-members:

‎docs/concepts.rst

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Concepts
2+
########
3+
4+
This page will give an overview of some important concepts to understand when working with PySTAC.
5+
6+
Reading STACs
7+
=============
8+
9+
TKTK
10+
11+
Writing STACs
12+
=============
13+
14+
TKTK
15+
16+
Setting HREFs from a root
17+
-------------------------
18+
19+
TKTK
20+
21+
Catalog Types
22+
-------------
23+
24+
TKTK
25+
26+
Relative vs Absolute Link HREFs
27+
-------------------------------
28+
29+
TKTK
30+
31+
Including a ``self`` link
32+
-------------------------
33+
34+
TKTK
35+
36+
Using STAC_IO
37+
-------------
38+
39+
TKTK
40+
41+
Manipulating STACs
42+
==================
43+
44+
TKTK
45+
46+
Walking the STAC
47+
----------------
48+
49+
TKTK
50+
51+
Mapping over Items
52+
------------------
53+
54+
TKTK
55+
56+
Copying STACs in-memory
57+
=======================
58+
59+
TKTK
60+
61+
Lazy resolution of STAC items
62+
=============================
63+
64+
TKTK

‎docs/conf.py

+6-2
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
#
1515
import os
1616
import sys
17+
sys.path.insert(0, os.path.abspath('.'))
18+
sys.path.insert(0, os.path.abspath('../'))
19+
from pystac.version import __version__
20+
1721

1822
# -- Project information -----------------------------------------------------
1923

@@ -22,9 +26,9 @@
2226
author = 'Azavea'
2327

2428
# The short X.Y version
25-
version = '0.2'
29+
version = __version__
2630
# The full version, including alpha/beta/rc tags
27-
release = '0.2.0'
31+
release = __version__
2832

2933

3034
# -- General configuration ---------------------------------------------------

‎docs/index.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ PySTAC Features
2626
* Allows in-memory manipulations of STAC catalogs.
2727
* Allows users to extend the IO of STAC metadata to provide support e.g. cloud providers.
2828
* Allows easy iteration over STAC objects. Stac objects are only read in when needed.
29-
* Allows users to easily write "absolute published", "relative published" and "self-contained" catalogs as `described in the best practices documentation <https://github.com/radiantearth/stac-spec/blob/v0.8.0-rc1/best-practices.md#use-of-links>`_.
29+
* Allows users to easily write "absolute published", "relative published" and "self-contained" catalogs as `described in the best practices documentation <https://github.com/radiantearth/stac-spec/blob/v0.8.0/best-practices.md#use-of-links>`_.
3030

3131

3232
Acknowledgements
@@ -38,5 +38,7 @@ This library builds on the code and concepts of `sat-stac <https://github.com/sa
3838
:hidden:
3939
:maxdepth: 2
4040

41+
concepts
42+
api
4143
tutorials
4244
contributing

‎docs/tutorials.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
Tutorials
22
#########
33

4-
Tutorials live `here <https://github.com/azavea/pystac/tree/master/tutorials>`_
4+
Tutorials live `here <https://github.com/azavea/pystac/tree/develop/tutorials>`_

‎pystac/__init__.py

+10-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
"""
2+
PySTAC is a library for working with SpatioTemporal Asset Catalogs (STACs)
3+
"""
4+
5+
# flake8: noqa
6+
17
from pystac.version import (__version__, STAC_VERSION)
28

39
class STACError(Exception):
@@ -13,7 +19,10 @@ class STACError(Exception):
1319
from pystac.label import *
1420

1521
def stac_object_from_dict(d):
16-
"""Determines how to deserialize a dictionary into a STAC object."""
22+
"""Determines how to deserialize a dictionary into a STAC object.
23+
24+
Note: This is used internally in STAC_IO to deserialize STAC Objects.
25+
It is pl"""
1726
if 'type' in d:
1827
if 'label:description' in d['properties']:
1928
return LabelItem.from_dict(d)

‎pystac/catalog.py

+21-14
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
import os
22
import json
3-
from copy import (deepcopy, copy)
3+
from copy import deepcopy
44

5-
from pystac import STACError
65
from pystac import STAC_VERSION
76
from pystac.stac_object import STACObject
87
from pystac.io import STAC_IO
@@ -11,33 +10,40 @@
1110
from pystac.resolved_object_cache import ResolvedObjectCache
1211
from pystac.utils import (is_absolute_href, make_absolute_href)
1312

13+
1414
class CatalogType:
15+
SELF_CONTAINED = 'SELF_CONTAINED'
1516
"""A 'self-contained catalog' is one that is designed for portability.
1617
Users may want to download a catalog from online and be able to use it on their
1718
local computer, so all links need to be relative.
1819
19-
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0-rc1/best-practices.md#self-contained-catalogs
20+
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0/best-practices.md#self-contained-catalogs # noqa
2021
"""
21-
SELF_CONTAINED = 'SELF_CONTAINED'
2222

23+
ABSOLUTE_PUBLISHED = 'ABSOLUTE_PUBLISHED'
2324
"""
2425
Absolute Published Catalog is a catalog that uses absolute links for everything,
2526
both in the links objects and in the asset hrefs.
2627
27-
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0-rc1/best-practices.md#published-catalogs
28+
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0-rc1/best-practices.md#published-catalogs # noqa
2829
"""
29-
ABSOLUTE_PUBLISHED = 'ABSOLUTE_PUBLISHED'
3030

31+
RELATIVE_PUBLISHED = 'RELATIVE_PUBLISHED'
3132
"""
3233
Relative Published Catalog is a catalog that uses relative links for everything,
3334
but includes an absolute self link at the root catalog, to identify its online location.
3435
35-
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0-rc1/best-practices.md#published-catalogs
36+
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0/best-practices.md#published-catalogs # noqa
3637
"""
37-
RELATIVE_PUBLISHED = 'RELATIVE_PUBLISHED'
3838

3939

4040
class Catalog(STACObject):
41+
"""A PySTAC Catalog represents a STAC catalog in memory.
42+
43+
See: https://github.com/radiantearth/stac-spec/blob/v0.8.0/catalog/catalog-spec.md
44+
"""
45+
46+
"""Default file name that will be given to this STAC item in a cononical format."""
4147
DEFAULT_FILE_NAME = "catalog.json"
4248

4349
def __init__(self, id, description, title=None, href=None):
@@ -209,12 +215,13 @@ def save(self, catalog_type):
209215
Args:
210216
211217
catalog_type: The catalog type that dictates the structure of the catalog to save.
212-
If the catalog type is CatalogType.ABSOLUTE_PUBLISHED, all self links will be included,
213-
and link type will be set to ABSOLUTE.
214-
If the catalog type is CatalogType.RELATIVE_PUBLISHED, this catalog's self link will be
215-
included, but no child catalog will have self links. Link types will be set to RELATIVE.
216-
If the catalog type is CatalogType.SELF_CONTAINED, no self links will be included.
218+
If the catalog type is CatalogType.ABSOLUTE_PUBLISHED,
219+
all self links will be included, and link type will be set to ABSOLUTE.
220+
If the catalog type is CatalogType.RELATIVE_PUBLISHED, this catalog's self
221+
link will be included, but no child catalog will have self links.
217222
Link types will be set to RELATIVE.
223+
If the catalog type is CatalogType.SELF_CONTAINED, no self links will be
224+
included. Link types will be set to RELATIVE.
218225
"""
219226

220227
# Ensure relative vs absolute
@@ -226,7 +233,7 @@ def save(self, catalog_type):
226233
include_self_link = catalog_type in [CatalogType.ABSOLUTE_PUBLISHED,
227234
CatalogType.RELATIVE_PUBLISHED]
228235

229-
if catalog_type == CatalogType.RELATIVE_PUBLISHED:
236+
if catalog_type == CatalogType.RELATIVE_PUBLISHED:
230237
child_catalog_type = CatalogType.SELF_CONTAINED
231238
else:
232239
child_catalog_type = catalog_type

0 commit comments

Comments
 (0)