Document using -W with pytest to detect deprecations

docs/development/release-process.md

@@ -21,3 +21,9 @@ SemVer makes it easier to see at a glance how compatible releases are with each
 ## Deprecation policy
 
 A [feature release](#feature-releases) may deprecate a feature, but it will not remove it until the next major release. A deprecation will be clearly documented in the changelog and in the code.
+
+All deprecated features will emit a `SingerDeprecationWarning` when used, so users can raise them as exceptions when running their tests to ensure that they are not using any deprecated features:
+
+```console
+$ pytest -W error::singer_sdk.utils.deprecation.SingerSDKDeprecationWarning
+```

singer_sdk/streams/rest.py

@@ -26,6 +26,7 @@
 )
 from singer_sdk.plugin_base import PluginBase as TapBaseClass
 from singer_sdk.streams.core import Stream
+from singer_sdk.utils.deprecation import SingerSDKDeprecationWarning
 
 if TYPE_CHECKING:
     from backoff.types import Details
@@ -484,7 +485,7 @@ def get_new_paginator(self) -> BaseAPIPaginator:
             A paginator instance.
         """
         if hasattr(self, "get_next_page_token"):
-            warning = DeprecationWarning(
+            warning = SingerSDKDeprecationWarning(
                 "`RESTStream.get_next_page_token` is deprecated and will not be used "
                 + "in a future version of the Meltano Singer SDK. "
                 + "Override `RESTStream.get_new_paginator` instead."
@@ -535,13 +536,16 @@ def get_records(self, context: dict | None) -> Iterable[dict[str, Any]]:
         Yields:
             One item per (possibly processed) record in the API.
         """
+        # warn(SingerSDKDeprecationWarning("Use `request_records` instead."))
         for record in self.request_records(context):
             transformed_record = self.post_process(record, context)
             if transformed_record is None:
                 # Record filtered out during post_process()
                 continue
             yield transformed_record
 
+        self.requests_session.close()
+
     def parse_response(self, response: requests.Response) -> Iterable[dict]:
         """Parse the response and return an iterator of result records.
 

singer_sdk/utils/__init__.py

@@ -0,0 +1 @@
+"""Helpers for internal development of the Singer SDK."""

singer_sdk/utils/deprecation.py

@@ -0,0 +1,7 @@
+"""Utilities for deprecating features."""
+
+__all__ = ["SingerSDKDeprecationWarning"]
+
+
+class SingerSDKDeprecationWarning(DeprecationWarning):
+    """Warning to raise when a deprecated feature is used."""

tests/core/test_streams.py

@@ -28,6 +28,7 @@
     Property,
     StringType,
 )
+from singer_sdk.utils.deprecation import SingerSDKDeprecationWarning
 
 CONFIG_START_DATE = "2021-01-01"
 
@@ -461,7 +462,7 @@ def test_next_page_token_jsonpath(
     RestTestStream.next_page_token_jsonpath = path
     stream = RestTestStream(tap)
 
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(SingerSDKDeprecationWarning):
         paginator = stream.get_new_paginator()
 
     next_page = paginator.get_next(fake_response)