More specific STAC_IO deprecation warnings

CHANGELOG.md

@@ -82,7 +82,7 @@
 ### Changed
 
 - API change: The extension API changed significantly. See ([#309](https://github.com/stac-utils/pystac/pull/309)) for more details.
-- API change: Refactored the global STAC_IO object to an instance-specific `StacIO` implementation. STAC_IO is deprecated and will be removed next release. ([#309](https://github.com/stac-utils/pystac/pull/309))
+- API change: Refactored the global STAC_IO object to an instance-specific `StacIO` implementation. ([#309](https://github.com/stac-utils/pystac/pull/309))
 - Asset.get_absolute_href returns None if no absolute href can be inferred (previously the relative href that was passed in was returned) ([#309](https://github.com/stac-utils/pystac/pull/309))
 
 ### Removed
@@ -91,6 +91,11 @@
 - Removed `LinkMixin`, and implemented those methods on `STACObject` directly. STACObject was the only class using LinkMixin and this should not effect users ([#309](https://github.com/stac-utils/pystac/pull/309)
 - Removed `single-file-stac` extension; this extension is being removed in favor of ItemCollection usage ([#309](https://github.com/stac-utils/pystac/pull/309)
 
+# Deprecated
+
+- Deprecated `STAC_IO` in favor of new `StacIO` class. `STAC_IO` will be removed in
+  v1.0.0. ([#309](https://github.com/stac-utils/pystac/pull/309))
+
 ## [v0.5.6]
 
 ### Added

docs/api.rst

@@ -164,11 +164,18 @@ RelType
 IO
 --
 
+StacIO
+~~~~~~
+
+.. autoclass:: pystac.StacIO
+   :members:
+   :undoc-members:
+
 STAC_IO
 ~~~~~~~
 
-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.
+.. deprecated:: 1.0.0-beta.1
+   Use :class:`pystac.StacIO` instead. This class will be removed in v1.0.0.
 
 .. autoclass:: pystac.stac_io.STAC_IO
    :members:

pystac/stac_io.py

@@ -271,22 +271,28 @@ class STAC_IO:
     """
 
     @staticmethod
-    def read_text_method(uri: str) -> str:
+    def issue_deprecation_warning() -> None:
         warnings.warn(
-            "STAC_IO is deprecated. "
-            "Please use instances of StacIO (e.g. StacIO.default()).",
+            "STAC_IO is deprecated and will be removed in v1.0.0. "
+            "Please use instances of StacIO (e.g. StacIO.default()) instead.",
             DeprecationWarning,
         )
+
+    def __init__(self) -> None:
+        STAC_IO.issue_deprecation_warning()
+
+    def __init_subclass__(cls) -> None:
+        STAC_IO.issue_deprecation_warning()
+
+    @staticmethod
+    def read_text_method(uri: str) -> str:
+        STAC_IO.issue_deprecation_warning()
         return StacIO.default().read_text(uri)
 
     @staticmethod
     def write_text_method(uri: str, txt: str) -> None:
         """Default method for writing text."""
-        warnings.warn(
-            "STAC_IO is deprecated. "
-            "Please use instances of StacIO (e.g. StacIO.default()).",
-            DeprecationWarning,
-        )
+        STAC_IO.issue_deprecation_warning()
         return StacIO.default().write_text(uri, txt)
 
     @staticmethod
@@ -295,11 +301,7 @@ def stac_object_from_dict(
         href: Optional[str] = None,
         root: Optional["Catalog_Type"] = None,
     ) -> "STACObject_Type":
-        warnings.warn(
-            "STAC_IO is deprecated. "
-            "Please use instances of StacIO (e.g. StacIO.default()).",
-            DeprecationWarning,
-        )
+        STAC_IO.issue_deprecation_warning()
         return pystac.serialization.stac_object_from_dict(d, href, root)
 
     # This is set in __init__.py
@@ -356,6 +358,7 @@ def read_json(cls, uri: str) -> Dict[str, Any]:
             STAC_IO in order to enable additional URI types, replace that member
             with your own implementation.
         """
+        STAC_IO.issue_deprecation_warning()
         result: Dict[str, Any] = json.loads(STAC_IO.read_text(uri))
         return result
 

tests/test_stac_io.py

@@ -22,6 +22,39 @@ def test_stac_io_issues_warnings(self) -> None:
             self.assertEqual(len(w), 1)
             self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
 
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+            # Trigger instantiation warning.
+            _ = STAC_IO()
+
+            self.assertEqual(len(w), 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+
+            class CustomSTAC_IO(STAC_IO):
+                pass
+
+            self.assertEqual(len(w), 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+
+            d = STAC_IO.read_json(
+                TestCases.get_path("data-files/item/sample-item.json")
+            )
+            _ = STAC_IO.stac_object_from_dict(d)
+
+            self.assertEqual(len(w), 3)
+            self.assertTrue(
+                all(issubclass(wrn.category, DeprecationWarning) for wrn in w)
+            )
+
     def test_read_write_collection(self) -> None:
         collection = pystac.read_file(
             TestCases.get_path("data-files/collections/multi-extent.json")