refactor: Deprecate passing file paths to plugin and stream initialization

pyproject.toml

@@ -176,6 +176,8 @@ filterwarnings = [
     "ignore:No records were available to test:UserWarning",
     # https://github.com/meltano/sdk/issues/1354
     "ignore:The function singer_sdk.testing.get_standard_tap_tests is deprecated:DeprecationWarning",
+    # https://github.com/meltano/sdk/issues/2744
+    "ignore::singer_sdk.helpers._compat.SingerSDKDeprecationWarning",
     # TODO: Address this SQLite warning in Python 3.13+
     "ignore::ResourceWarning",
 ]

singer_sdk/helpers/_compat.py

@@ -31,7 +31,13 @@
 date_fromisoformat = datetime.date.fromisoformat
 time_fromisoformat = datetime.time.fromisoformat
 
+
+class SingerSDKDeprecationWarning(DeprecationWarning):
+    """Custom deprecation warning for the Singer SDK."""
+
+
 __all__ = [
+    "SingerSDKDeprecationWarning",
     "Traversable",
     "date_fromisoformat",
     "datetime_fromisoformat",

singer_sdk/plugin_base.py

@@ -8,6 +8,7 @@
 import sys
 import time
 import typing as t
+import warnings
 from importlib import metadata
 from pathlib import Path, PurePath
 from types import MappingProxyType
@@ -22,6 +23,7 @@
 )
 from singer_sdk.exceptions import ConfigValidationError
 from singer_sdk.helpers._classproperty import classproperty
+from singer_sdk.helpers._compat import SingerSDKDeprecationWarning
 from singer_sdk.helpers._secrets import SecretString, is_common_secret_key
 from singer_sdk.helpers._util import read_json_file
 from singer_sdk.helpers.capabilities import (
@@ -144,12 +146,24 @@
             config_dict = {}
         elif isinstance(config, (str, PurePath)):
             config_dict = read_json_file(config)
+            warnings.warn(
+                "Passsing a config file path is deprecated. Please pass the config "
+                "as a dictionary instead.",
+                SingerSDKDeprecationWarning,
+                stacklevel=2,
+            )
         elif isinstance(config, list):
             config_dict = {}
             for config_path in config:
                 # Read each config file sequentially. Settings from files later in the
                 # list will override those of earlier ones.
                 config_dict.update(read_json_file(config_path))
+            warnings.warn(
+                "Passsing a list of config file paths is deprecated. Please pass the "
+                "config as a dictionary instead.",
+                SingerSDKDeprecationWarning,
+                stacklevel=2,
+            )
         elif isinstance(config, dict):
             config_dict = config
         else:

singer_sdk/streams/core.py

@@ -7,6 +7,7 @@
 import datetime
 import json
 import typing as t
+import warnings
 from os import PathLike
 from pathlib import Path
 from types import MappingProxyType
@@ -27,7 +28,10 @@
     SDKBatchMessage,
 )
 from singer_sdk.helpers._catalog import pop_deselected_record_properties
-from singer_sdk.helpers._compat import datetime_fromisoformat
+from singer_sdk.helpers._compat import (
+    SingerSDKDeprecationWarning,
+    datetime_fromisoformat,
+)
 from singer_sdk.helpers._flattening import get_flattening_options
 from singer_sdk.helpers._state import (
     finalize_state_progress_markers,
@@ -157,6 +161,12 @@
                     raise FileNotFoundError(msg)
 
                 self._schema_filepath = Path(schema)
+                warnings.warn(
+                    "Passing a schema filepath is deprecated. Please pass the schema "
+                    "dictionary or a Singer Schema object instead.",
+                    SingerSDKDeprecationWarning,
+                    stacklevel=2,
+                )
             elif isinstance(schema, dict):
                 self._schema = schema
             elif isinstance(schema, singer.Schema):

singer_sdk/tap_base.py

@@ -5,6 +5,7 @@
 import abc
 import contextlib
 import typing as t
+import warnings
 from enum import Enum
 
 import click
@@ -18,6 +19,7 @@
 )
 from singer_sdk.helpers import _state
 from singer_sdk.helpers._classproperty import classproperty
+from singer_sdk.helpers._compat import SingerSDKDeprecationWarning
 from singer_sdk.helpers._state import write_stream_state
 from singer_sdk.helpers._util import dump_json, read_json_file
 from singer_sdk.helpers.capabilities import (
@@ -102,6 +104,12 @@
             self._input_catalog = Catalog.from_dict(catalog)  # type: ignore[arg-type]
         elif catalog is not None:
             self._input_catalog = Catalog.from_dict(read_json_file(catalog))
+            warnings.warn(
+                "Passsing a catalog file path is deprecated. Please pass the catalog "
+                "as a dictionary or Catalog object instead.",
+                SingerSDKDeprecationWarning,
+                stacklevel=2,
+            )
 
         self._mapper: PluginMapper | None = None
 
@@ -114,6 +122,12 @@
             state_dict = state
         elif state:
             state_dict = read_json_file(state)
+            warnings.warn(
+                "Passsing a state file path is deprecated. Please pass the state "
+                "as a dictionary instead.",
+                SingerSDKDeprecationWarning,
+                stacklevel=2,
+            )
         self.load_state(state_dict)
 
     # Class properties