Merge pull request stac-utils#50 from azavea/rde/feature/identify-version

Add functionality for identifying STAC JSON information

Author: lossyrob

docs/api.rst

@@ -229,6 +229,51 @@ SingleFileSTAC
    :members:
    :undoc-members:
 
+Serialization
+-------------
+
+PySTAC includes a ``pystac.serialization`` package for serialization concerns that
+are used internally, but may also be useful to external tools.
+
+merge_common_properties
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pystac.serialization
+   :members: merge_common_properties
+
+indentify_stac_object
+~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pystac.serialization
+   :members: identify_stac_object
+
+indentify_stac_object_type
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pystac.serialization
+   :members: identify_stac_object_type
+
+
+STACJSONDescription
+~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: pystac.serialization.STACJSONDescription
+   :members:
+   :undoc-members:
+
+STACVersionRange
+~~~~~~~~~~~~~~~~
+
+.. autoclass:: pystac.serialization.STACVersionRange
+   :members:
+   :undoc-members:
+
+STACObjectType
+~~~~~~~~~~~~~~
+
+.. autoclass:: pystac.serialization.STACObjectType
+   :members:
+   :undoc-members:
 
 PySTAC Internal Classes
 -----------------------

docs/concepts.rst

@@ -311,3 +311,47 @@ Resolution Caching
 The root :class:`~pystac.Catalog` instance of a STAC (the Catalog which is linked to by every associated object's ``root`` link) contains a cache of resolved objects. This cache points to in-memory instances of :class:`~pystac.STACObject` s that have already been resolved through PySTAC crawling links associated with that root catalog. The cache works off of the stac object's ID, which is why **it is necessary for every STAC object in the catalog to have a unique identifier, which is unique across the entire STAC**.
 
 When a link is being resolved from a STACObject that has it's root set, that root is passed into the :func:`Link.resolve_stac_object <pystac.Link.resolve_stac_object>` call. That root's :class:`~pystac.resolved_object_cache.ResolvedObjectCache` will be used to ensure that if the link is pointing to an object that has already been resolved, then that link will point to the same, single instance in the cache. This ensures working with STAC objects in memory doesn't create a situation where multiple copies of the same STAC objects are created from different links, manipulated, and written over each other.
+
+Working with STAC JSON
+======================
+
+The ``pystac.serialization`` package has some functionality around working directly with STAC
+JSON objects, without utilizing PySTAC object types. This is used internally by PySTAC, but might also be useful to users working directly with JSON (e.g. on validation).
+
+
+Identifing STAC objects from JSON
+---------------------------------
+
+Users can identify STAC information, including the object type, version and extensions,
+from JSON. The main method for this is :func:`~pystac.serialization.identify_stac_object`,
+which returns an object that contains the object type, the range of versions this object is
+valid for (according to PySTAC's best guess), the common extensions implemented by this object,
+and any custom extensions (represented by URIs to JSON Schemas).
+
+.. code-block:: python
+
+   from pystac.serialization import identify_stac_object
+
+   json_dict = ...
+
+   info = identify_stac_object(json_dict, merge_collection_properties=True)
+
+   # The object type
+   info.object_type
+
+   # The version range
+   info.version_range
+
+   # The common extensions
+   info.common_extensions
+
+   # The custom Extensions
+   info.custom_extensions
+
+Merging common properties
+-------------------------
+
+The :func:`~pystac.serialization.merge_common_properties` will take a JSON dict that represents
+an item, and if it is associated with a collection, merge in the collection's properties.
+You can pass in a dict that contains previously read collections that caches collections by the HREF of the collection link and/or the collection ID, which can help avoid multiple reads of
+collection links.

pystac/__init__.py

@@ -27,6 +27,8 @@ class STACError(Exception):
 from pystac.eo import *
 from pystac.label import *
 
+from pystac.serialization import (identify_stac_object, STACObjectType)
+
 
 def _stac_object_from_dict(d, href=None, root=None):
     """Determines how to deserialize a dictionary into a STAC object.
@@ -42,28 +44,24 @@ def _stac_object_from_dict(d, href=None, root=None):
     Note: This is used internally in STAC_IO to deserialize STAC Objects.
     It is in the top level __init__ in order to avoid circular dependencies.
     """
-    extensions = d.get('stac_extensions', [])
-    if 'type' in d:
-        if d['type'] == 'FeatureCollection':
-            # Dealing with an Item Collection
-            if 'collections' in d:
-                return SingleFileSTAC.from_dict(d, href=href, root=root)
-            else:
-                return ItemCollection.from_dict(d, href=href, root=root)
-        else:
-            # Dealing with an Item
-            if 'eo' in extensions or \
-               any([k for k in d['properties'].keys() if k.startswith('eo:')]):
-                return EOItem.from_dict(d, href=href, root=root)
-            elif 'label' in extensions or \
-                 any([k for k in d['properties'].keys() if k.startswith('label:')]):
-                return LabelItem.from_dict(d, href=href, root=root)
-            else:
-                return Item.from_dict(d, href=href, root=root)
-    elif 'extent' in d:
-        return Collection.from_dict(d, href=href, root=root)
-    else:
+    info = identify_stac_object(d)
+
+    # TODO: Transorm older versions to newest version (pystac.serialization.migrate)
+
+    if info.object_type == STACObjectType.CATALOG:
         return Catalog.from_dict(d, href=href, root=root)
+    if info.object_type == STACObjectType.COLLECTION:
+        return Collection.from_dict(d, href=href, root=root)
+    if info.object_type == STACObjectType.ITEMCOLLECTION:
+        if 'single-file-stac' in info.common_extensions:
+            return SingleFileSTAC.from_dict(d, href=href, root=root)
+        return ItemCollection.from_dict(d, href=href, root=root)
+    if info.object_type == STACObjectType.ITEM:
+        if 'eo' in info.common_extensions:
+            return EOItem.from_dict(d, href=href, root=root)
+        if 'label' in info.common_extensions:
+            return LabelItem.from_dict(d, href=href, root=root)
+        return Item.from_dict(d, href=href, root=root)
 
 
 STAC_IO.stac_object_from_dict = _stac_object_from_dict

pystac/serialization/__init__.py

@@ -0,0 +1,8 @@
+# flake8: noqa
+
+from pystac.serialization.identify import (STACObjectType, STACJSONDescription,
+                                           STACVersionRange,
+                                           identify_stac_object,
+                                           identify_stac_object_type)
+
+from pystac.serialization.common_properties import merge_common_properties

pystac/serialization/common_properties.py

@@ -0,0 +1,59 @@
+from pystac.utils import make_absolute_href
+from pystac.stac_io import STAC_IO
+
+
+def merge_common_properties(item_dict, collection_cache=None, json_href=None):
+    """Merges Collection properties into an Item.
+
+    Args:
+        item_dict: JSON dict of the Item which properties should be merged
+            into.
+        collection_cache: Optional cache of Collection JSON that has previously
+            read. Keyed to either the Collection ID or an HREF.
+        json_href: The HREF of the file that this JSON comes from. Used
+            to resolve relative paths.
+
+    Returns:
+        bool: True if Collection properties have been merged, otherwise False.
+    """
+    properties_merged = False
+    collection = None
+    collection_href = None
+
+    # Try the cache if we have a collection ID.
+    if 'collection' in item_dict:
+        collection_id = item_dict['collection']
+        if collection_cache is not None:
+            collection = collection_cache.get(collection_id)
+
+    # Next, try the collection link.
+    if collection is None:
+        links = item_dict['links']
+        collection_link = next((l for l in links if l['rel'] == 'collection'),
+                               None)
+        if collection_link is not None:
+            collection_href = collection_link['href']
+            if json_href is not None:
+                collection_href = make_absolute_href(collection_href,
+                                                     json_href)
+            if collection_cache is not None:
+                collection = collection_cache.get(collection_href)
+
+            if collection is None:
+                collection = STAC_IO.read_json(collection_href)
+
+    if collection is not None:
+        if 'properties' in collection:
+            for k in collection['properties']:
+                if k not in item_dict['properties']:
+                    properties_merged = True
+                    item_dict['properties'][k] = collection['properties'][k]
+
+        if collection_cache is not None and collection[
+                'id'] not in collection_cache:
+            collection_id = collection['id']
+            collection_cache[collection_id] = collection
+            if collection_href is not None:
+                collection_cache[collection_href] = collection
+
+    return properties_merged