fin-infra 0.1.85__py3-none-any.whl → 0.1.87__py3-none-any.whl

fin_infra/utils/__init__.py

@@ -10,8 +10,22 @@ and should be imported from there:
 
 For async retry with exponential backoff:
     from fin_infra.utils.retry import retry_async, RetryError
+
+For deprecation utilities:
+    from fin_infra.utils.deprecation import deprecated, deprecated_parameter
 """
 
+from fin_infra.utils.deprecation import (
+    DeprecatedWarning,
+    deprecated,
+    deprecated_parameter,
+)
 from fin_infra.utils.retry import RetryError, retry_async
 
-__all__ = ["RetryError", "retry_async"]
+__all__ = [
+    "RetryError",
+    "retry_async",
+    "deprecated",
+    "deprecated_parameter",
+    "DeprecatedWarning",
+]

fin_infra/utils/deprecation.py

@@ -0,0 +1,161 @@
+"""Deprecation utilities for fin-infra.
+
+This module provides decorators and functions for marking features as deprecated,
+following the deprecation policy defined in DEPRECATION.md.
+
+Example:
+    >>> from fin_infra.utils.deprecation import deprecated
+    >>>
+    >>> @deprecated(
+    ...     version="1.2.0",
+    ...     reason="Use new_function() instead",
+    ...     removal_version="1.4.0"
+    ... )
+    ... def old_function():
+    ...     pass
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+__all__ = [
+    "deprecated",
+    "deprecated_parameter",
+    "DeprecatedWarning",
+]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecatedWarning(DeprecationWarning):
+    """Custom deprecation warning for fin-infra.
+
+    This warning is used to distinguish fin-infra deprecations from
+    Python's built-in DeprecationWarning.
+    """
+
+    pass
+
+
+def deprecated(
+    version: str,
+    reason: str,
+    removal_version: str | None = None,
+    *,
+    stacklevel: int = 2,
+) -> Callable[[F], F]:
+    """Decorator to mark a function or class as deprecated.
+
+    The decorated function/class will emit a DeprecationWarning when called/instantiated.
+
+    Args:
+        version: The version in which the feature was deprecated (e.g., "1.2.0").
+        reason: The reason for deprecation and recommended alternative.
+        removal_version: The version in which the feature will be removed (e.g., "1.4.0").
+        stacklevel: Stack level for the warning (default 2 for immediate caller).
+
+    Returns:
+        A decorator that wraps the function/class with deprecation warning.
+
+    Example:
+        >>> @deprecated(
+        ...     version="1.2.0",
+        ...     reason="Use new_function() instead",
+        ...     removal_version="1.4.0"
+        ... )
+        ... def old_function():
+        ...     return "result"
+        >>>
+        >>> old_function()  # Emits DeprecationWarning
+        'result'
+    """
+
+    def decorator(func: F) -> F:
+        # Build the warning message
+        name = getattr(func, "__qualname__", getattr(func, "__name__", str(func)))
+        message = f"{name} is deprecated since version {version}."
+
+        if removal_version:
+            message += f" It will be removed in version {removal_version}."
+
+        message += f" {reason}"
+
+        if isinstance(func, type):
+            # Handle class deprecation
+            original_init = func.__init__  # type: ignore[misc]
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel)
+                original_init(self, *args, **kwargs)
+
+            func.__init__ = new_init  # type: ignore[misc]
+
+            # Add deprecation info to docstring
+            if func.__doc__:
+                func.__doc__ = f".. deprecated:: {version}\n   {reason}\n\n{func.__doc__}"
+            else:
+                func.__doc__ = f".. deprecated:: {version}\n   {reason}"
+
+            return func  # type: ignore[return-value]
+        else:
+            # Handle function deprecation
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel)
+                return func(*args, **kwargs)
+
+            # Add deprecation info to docstring
+            if wrapper.__doc__:
+                wrapper.__doc__ = f".. deprecated:: {version}\n   {reason}\n\n{wrapper.__doc__}"
+            else:
+                wrapper.__doc__ = f".. deprecated:: {version}\n   {reason}"
+
+            return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def deprecated_parameter(
+    name: str,
+    version: str,
+    reason: str,
+    removal_version: str | None = None,
+    *,
+    stacklevel: int = 2,
+) -> None:
+    """Emit a deprecation warning for a deprecated parameter.
+
+    Call this function when a deprecated parameter is used. This should be
+    called at the beginning of a function that has deprecated parameters.
+
+    Args:
+        name: The name of the deprecated parameter.
+        version: The version in which the parameter was deprecated.
+        reason: The reason for deprecation and recommended alternative.
+        removal_version: The version in which the parameter will be removed.
+        stacklevel: Stack level for the warning (default 2 for immediate caller).
+
+    Example:
+        >>> def my_function(new_param: str, old_param: str | None = None):
+        ...     if old_param is not None:
+        ...         deprecated_parameter(
+        ...             name="old_param",
+        ...             version="1.2.0",
+        ...             reason="Use new_param instead"
+        ...         )
+        ...         new_param = old_param
+        ...     return new_param
+    """
+    message = f"Parameter '{name}' is deprecated since version {version}."
+
+    if removal_version:
+        message += f" It will be removed in version {removal_version}."
+
+    message += f" {reason}"
+
+    warnings.warn(message, DeprecatedWarning, stacklevel=stacklevel + 1)

{fin_infra-0.1.85.dist-info → fin_infra-0.1.87.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fin-infra
-Version: 0.1.85
+Version: 0.1.87
 Summary: Financial infrastructure toolkit: banking connections, market data, credit, cashflows, and brokerage integrations
 License: MIT
 Keywords: finance,banking,plaid,brokerage,markets,credit,tax,cashflow,fintech,infra
@@ -49,9 +49,14 @@ Description-Content-Type: text/markdown
 
 # fin-infra
 
-### Financial data infrastructure for fintech apps
+[![CI](https://github.com/nfraxlab/fin-infra/actions/workflows/ci.yml/badge.svg)](https://github.com/nfraxlab/fin-infra/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/fin-infra.svg)](https://pypi.org/project/fin-infra/)
+[![Python](https://img.shields.io/pypi/pyversions/fin-infra.svg)](https://pypi.org/project/fin-infra/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/fin-infra.svg)](https://pypi.org/project/fin-infra/)
+[![codecov](https://codecov.io/gh/nfraxlab/fin-infra/branch/main/graph/badge.svg)](https://codecov.io/gh/nfraxlab/fin-infra)
 
-[![PyPI](https://img.shields.io/pypi/v/fin-infra.svg)](https://pypi.org/project/fin-infra/) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Downloads](https://static.pepy.tech/badge/fin-infra/month)](https://pepy.tech/project/fin-infra)
+### Financial data infrastructure for fintech apps
 
 **Banking, investments, market data, credit scores, and financial calculations in one toolkit.**
 

{fin_infra-0.1.85.dist-info → fin_infra-0.1.87.dist-info}/RECORD

@@ -169,12 +169,13 @@ fin_infra/settings.py,sha256=11JgIhjGwWnwixV-hveEWpoWd_JC0ixLnOQoLWCiwNo,1387
 fin_infra/tax/__init__.py,sha256=U0EUKQwbDqnAYwU8WRx6AD07TaB-ELdKGISOQ-904lw,6103
 fin_infra/tax/add.py,sha256=dYigcgQFEP38NLoNuhh7vpSoy07sWX6Z_DTp1tWFJXw,14553
 fin_infra/tax/tlh.py,sha256=3khtiEkGKIIHi2mbMM0ss-GKQ8vM3FS6hly8R00qseY,21482
-fin_infra/utils/__init__.py,sha256=gKacLSWMAis--pasd8AuVN7ap0e9Z1TjRGur0J23EDo,648
+fin_infra/utils/__init__.py,sha256=x_FUlv7FONdTPHwXTbPWY-EEOBwWnm-y8TPJ1W1PrXM,944
+fin_infra/utils/deprecation.py,sha256=DTcqv7ECnrWOOwoA07JOnRci4Hqqo9YtKSSmoS-DVPY,5187
 fin_infra/utils/http.py,sha256=rDEgYsEBrEe75ml5RA-iSs3xeU5W-3j-czJlT7WbrM4,632
 fin_infra/utils/retry.py,sha256=YiyTgy26eJ1ah7fE2_-ZPa4hv4bIT4OzjYolkNWb5j0,1057
 fin_infra/version.py,sha256=4t_crzhrLum--oyowUMxtjBTzUtWp7oRTF22ewEvJG4,49
-fin_infra-0.1.85.dist-info/LICENSE,sha256=wK-Ya7Ylxa38dSIZRhvNj1ZVLIrHC-BAI8v38PNADiA,1061
-fin_infra-0.1.85.dist-info/METADATA,sha256=y13UC--sOtnmoLfYI4s1Z_THKBcpLzH3JaYaXOH41y8,10479
-fin_infra-0.1.85.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-fin_infra-0.1.85.dist-info/entry_points.txt,sha256=Sr1uikvALZMeKm-DIkeKG4L9c4SNqysXGO_IRF8_9eU,53
-fin_infra-0.1.85.dist-info/RECORD,,
+fin_infra-0.1.87.dist-info/LICENSE,sha256=wK-Ya7Ylxa38dSIZRhvNj1ZVLIrHC-BAI8v38PNADiA,1061
+fin_infra-0.1.87.dist-info/METADATA,sha256=7yOY1JncaJbV-A9TpZ2zRwb2vxUJke1AoTCyV0VVDoE,10712
+fin_infra-0.1.87.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+fin_infra-0.1.87.dist-info/entry_points.txt,sha256=Sr1uikvALZMeKm-DIkeKG4L9c4SNqysXGO_IRF8_9eU,53
+fin_infra-0.1.87.dist-info/RECORD,,