ADD: Deprecation warnings for client SType enum

Author: nmacholl

databento/__init__.py

@@ -1,4 +1,5 @@
 import logging
+import warnings
 
 from databento.common import utility
 from databento.common.dbnstore import DBNStore
@@ -56,6 +57,9 @@
 # Setup logging
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
+# Setup deprecation warnings
+warnings.simplefilter("always", DeprecationWarning)
+
 # Convenience imports
 enable_logging = utility.enable_logging
 from_dbn = DBNStore.from_file

databento/common/deprecated.py

@@ -6,7 +6,6 @@
 def deprecated(func: Any) -> Any:
     @functools.wraps(func)
     def new_func(*args: Any, **kwargs: Any) -> Any:
-        warnings.simplefilter("always", DeprecationWarning)
         warnings.warn(
             func.__doc__,
             category=DeprecationWarning,

databento/common/enums.py

@@ -1,5 +1,6 @@
-from enum import Enum, Flag, IntFlag, unique
-from typing import Callable, Type, TypeVar, Union
+import warnings
+from enum import Enum, EnumMeta, Flag, IntFlag, unique
+from typing import Any, Callable, Iterable, Type, TypeVar, Union
 
 
 M = TypeVar("M", bound=Enum)
@@ -77,6 +78,46 @@ def coerced_new(enum: Type[M], value: object) -> M:
     return enum_type
 
 
+class DeprecatedAccess(EnumMeta):
+    """
+    runs a user-specified function whenever member is accessed
+    """
+
+    def __getattribute__(cls, name: str) -> object:
+        obj = super().__getattribute__(name)
+        if isinstance(obj, Enum) and obj._on_access:  # type: ignore
+            obj._on_access()  # type: ignore
+        return obj
+
+    def __getitem__(cls, name: str, *_: Iterable[Any]) -> object:  # type: ignore
+        member: Any = super().__getitem__(name)
+        if member._on_access:
+            member._on_access()
+        return member
+
+    def __call__(  # type: ignore
+        cls,
+        value: str,
+        names=None,
+        *,
+        module=None,
+        qualname=None,
+        type=None,
+        start=1,
+    ) -> object:
+        obj = super().__call__(
+            value,
+            names,
+            module=module,
+            qualname=qualname,
+            type=type,
+            start=start,
+        )
+        if isinstance(obj, Enum) and obj._on_access:
+            obj._on_access()
+        return obj
+
+
 class StringyMixin:
     """
     Mixin class for overloading __str__ on Enum types.
@@ -206,19 +247,46 @@ class Delivery(StringyMixin, str, Enum):
     DISK = "disk"
 
 
+def deprecated_enum(old_value: str, new_value: str) -> str:
+    warnings.warn(
+        f"{old_value} is deprecated to {new_value}",
+        category=DeprecationWarning,
+        stacklevel=3,  # This makes the error happen in user code
+    )
+    return new_value
+
+
 @unique
 @coercible
-class SType(StringyMixin, str, Enum):
+class SType(StringyMixin, str, Enum, metaclass=DeprecatedAccess):
     """Represents a symbology type."""
 
-    PRODUCT_ID = "product_id"  # Deprecated for `instrument_id`
-    NATIVE = "native"  # Deprecated for `raw_symbol`
-    SMART = "smart"  # Deprecated for `parent` and `continuous`
+    PRODUCT_ID = "product_id", "instrument_id"  # Deprecated for `instrument_id`
+    NATIVE = "native", "raw_symbol"  # Deprecated for `raw_symbol`
+    SMART = "smart", "parent", "continuous"  # Deprecated for `parent` and `continuous`
     INSTRUMENT_ID = "instrument_id"
     RAW_SYMBOL = "raw_symbol"
     PARENT = "parent"
     CONTINUOUS = "continuous"
 
+    def __new__(cls, value: str, *args: Iterable[str]) -> "SType":
+        variant = super().__new__(cls, value)
+        variant._value_ = value
+        variant.__args = args  # type: ignore
+        variant._on_access = variant.__deprecated if args else None  # type: ignore
+        return variant
+
+    def __eq__(self, other: object) -> bool:
+        return str(self) == str(other)
+
+    def __deprecated(self) -> None:
+        other_values = " or ".join(self.__args)  # type: ignore
+        warnings.warn(
+            f"SType of {self.value} is deprecated; use {other_values}",
+            category=DeprecationWarning,
+            stacklevel=3,
+        )
+
 
 @unique
 @coercible

databento/common/parsing.py

@@ -56,7 +56,7 @@ def optional_values_list_to_string(
 @singledispatch
 def optional_symbols_list_to_string(
     symbols: Optional[Union[Iterable[str], Iterable[int], str, int]],
-    stype_in: SType,
+    _: SType,
 ) -> str:
     """
     Concatenate a symbols string or iterable of symbol strings (if not None).
@@ -109,7 +109,7 @@ def _(symbols: int, stype_in: SType) -> str:
     optional_symbols_list_to_string
 
     """
-    if stype_in == SType.INSTRUMENT_ID:
+    if stype_in == SType.INSTRUMENT_ID or stype_in == SType.PRODUCT_ID:
         return str(symbols)
     raise ValueError(
         f"value `{symbols}` is not a valid symbol for stype {stype_in}; "
@@ -143,7 +143,7 @@ def _(symbols: str, stype_in: SType) -> str:
         return ",".join(map(symbol_to_string, symbol_list))
 
     # TODO(cs): Temporary mapping until past stype rename deprecation period
-    if stype_in in (SType.SMART, SType.CONTINUOUS):
+    if stype_in in (SType.SMART, SType.PARENT, SType.CONTINUOUS):
         return validate_smart_symbol(symbols)
     return symbols.strip().upper()
 

tests/test_common_enums.py

@@ -147,3 +147,35 @@ def test_int_flags_stringy_mixin(enum_type: Type[Flag]) -> None:
         assert str(record_flags) == ", ".join(
             f.name.lower() for f in enum_type if f in record_flags
         )
+
+
+def test_stype_deprecation() -> None:
+    """
+    Test that a deprecation warning is emitted when
+    accessing a deprecated SType member.
+    """
+    with pytest.deprecated_call():
+        SType.PRODUCT_ID
+
+    with pytest.deprecated_call():
+        SType.NATIVE
+
+    with pytest.deprecated_call():
+        SType.SMART
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "product_id",
+        "native",
+        "smart",
+    ],
+)
+def test_stype_deprecation_strings(name: str) -> None:
+    """
+    Test that a deprecation warning is emitted when
+    constructing an SType from strings.
+    """
+    with pytest.deprecated_call():
+        SType(name)