Merge branch 'main' into clone-items

Author: gadomski

CHANGELOG.md

@@ -33,6 +33,7 @@
 - Use `TypeVar` for alternate constructors ([#983](https://github.com/stac-utils/pystac/pull/983))
 - Behavior when required fields are missing in `Item.from_dict` ([#994](https://github.com/stac-utils/pystac/pull/994))
 - By default, `ItemCollection` now clones items in iterator (`clone_items=True`) ([#1016](https://github.com/stac-utils/pystac/pull/1016))
+- `TemplateError` in `layout.py` deprecated in favor of duplicate in `errors.py` ([#1018](https://github.com/stac-utils/pystac/pull/1018))
 
 ### Fixed
 

docs/Makefile

@@ -12,7 +12,7 @@ help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 livehtml:
-	sphinx-autobuild -z ../pystac --host 0.0.0.0 ${SOURCEDIR} $(BUILDDIR)/html -d _build/doctrees
+	sphinx-autobuild --watch ../pystac --host 0.0.0.0 ${SOURCEDIR} $(BUILDDIR)/html -d _build/doctrees
 
 .PHONY: help Makefile
 

docs/api.rst

@@ -166,7 +166,7 @@ The following exceptions may be raised internally by the library.
   be present but is missing or ``None``.
 * :class:`pystac.STACValidationError`: Raised by validation calls if the STAC JSON is
   invalid.
-* :class:`pystac.layout.TemplateError`: Raised when an error occurs while converting a
+* :class:`pystac.TemplateError`: Raised when an error occurs while converting a
   template string into data for :class:`~pystac.layout.LayoutTemplate`.
 
 Serialization

pystac/__init__.py

@@ -4,6 +4,7 @@
 """
 __all__ = [
     "__version__",
+    "TemplateError",
     "STACError",
     "STACTypeError",
     "DuplicateObjectKeyError",
@@ -44,6 +45,7 @@
 from typing import Any, Dict, Optional
 
 from pystac.errors import (
+    TemplateError,
     STACError,
     STACTypeError,
     DuplicateObjectKeyError,

pystac/errors.py

@@ -1,6 +1,14 @@
 from typing import Any, Optional, Union
 
 
+class TemplateError(Exception):
+    """Exception thrown when an error occurs during converting a template
+    string into data for :class:`~pystac.layout.LayoutTemplate`
+    """
+
+    pass
+
+
 class STACError(Exception):
     """A STACError is raised for errors relating to STAC, e.g. for
     invalid formats or trying to operate on a STAC that does not have

pystac/layout.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from abc import ABC, abstractmethod
 from collections import OrderedDict
 from string import Formatter
@@ -16,11 +17,25 @@
 
 
 class TemplateError(Exception):
-    """Exception thrown when an error occurs during converting a template
+    """DEPRECATED.
+
+    .. deprecated:: 1.7.0
+        Use :class:`pystac.errors.TemplateError` instead.
+
+    Exception thrown when an error occurs during converting a template
     string into data for :class:`~pystac.layout.LayoutTemplate`
     """
 
-    pass
+    def __init__(self, *args, **kwargs) -> None:  # type: ignore
+        warnings.warn(
+            message=(
+                "TemplateError in pystac.layout is deprecated and will be "
+                "removed in pystac version 2.0.0. Use TemplateError in "
+                "pystac.errors instead."
+            ),
+            category=DeprecationWarning,
+        )
+        super().__init__(*args, **kwargs)
 
 
 class LayoutTemplate:
@@ -114,7 +129,7 @@ def _get_template_value(self, stac_object: STACObject, template_var: str) -> Any
                 if dt is None:
                     dt = stac_object.common_metadata.start_datetime
                 if dt is None:
-                    raise TemplateError(
+                    raise pystac.TemplateError(
                         "Item {} does not have a datetime or "
                         "datetime range set; cannot template {} in {}".format(
                             stac_object, template_var, self.template
@@ -134,12 +149,12 @@ def _get_template_value(self, stac_object: STACObject, template_var: str) -> Any
                 if template_var == "collection":
                     if stac_object.collection_id is not None:
                         return stac_object.collection_id
-                    raise TemplateError(
+                    raise pystac.TemplateError(
                         f"Item {stac_object} does not have a collection ID set; "
                         f"cannot template {template_var} in {self.template}"
                     )
             else:
-                raise TemplateError(
+                raise pystac.TemplateError(
                     '"{}" cannot be used to template non-Item {} in {}'.format(
                         template_var, stac_object, self.template
                     )
@@ -148,7 +163,7 @@ def _get_template_value(self, stac_object: STACObject, template_var: str) -> Any
         # Allow dot-notation properties for arbitrary object values.
         props = template_var.split(".")
         prop_source: Optional[Union[pystac.STACObject, Dict[str, Any]]] = None
-        error = TemplateError(
+        error = pystac.TemplateError(
             "Cannot find property {} on {} for template {}".format(
                 template_var, stac_object, self.template
             )
@@ -181,7 +196,7 @@ def _get_template_value(self, stac_object: STACObject, template_var: str) -> Any
                     if not hasattr(v, prop):
                         raise error
                     v = getattr(v, prop)
-        except TemplateError as e:
+        except pystac.TemplateError as e:
             if template_var in self.defaults:
                 return self.defaults[template_var]
             raise e
@@ -204,7 +219,7 @@ def get_template_values(self, stac_object: STACObject) -> Dict[str, Any]:
             stac object.
 
         Raises:
-            TemplateError: If a value for a template variable cannot be
+            pystac.TemplateError: If a value for a template variable cannot be
                 derived from the stac object and there is no default,
                 this error will be raised.
         """
@@ -227,7 +242,7 @@ def substitute(self, stac_object: STACObject) -> str:
             from this stac object.
 
         Raises:
-            TemplateError: If a value for a template variable cannot be
+            pystac.TemplateError: If a value for a template variable cannot be
                 derived from the stac object and there is no default,
                 this error will be raised.
         """

requirements-docs.txt

@@ -1,7 +1,8 @@
 Sphinx==5.0.1
-ipython==8.10.0
+ipython==8.11.0
 jinja2<4.0
 nbsphinx==0.8.12
 pydata-sphinx-theme==0.9.0
+sphinx-autobuild==2021.3.14
 sphinx-design==0.3.0
 sphinxcontrib-fulltoc==1.2.0

tests/test_layout.py

@@ -9,7 +9,6 @@
     BestPracticesLayoutStrategy,
     CustomLayoutStrategy,
     LayoutTemplate,
-    TemplateError,
     TemplateLayoutStrategy,
 )
 from pystac.utils import JoinType, join_path_or_url
@@ -103,7 +102,7 @@ def test_throws_for_no_collection(self) -> None:
         item.set_collection(None)
         assert item.collection_id is None
 
-        with self.assertRaises(TemplateError):
+        with self.assertRaises(pystac.TemplateError):
             template.get_template_values(item)
 
     def test_nested_properties(self) -> None: