deprecated-params 0.1.0__tar.gz

deprecated_params-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vizonex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deprecated_params-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: deprecated-params
+Version: 0.1.0
+Summary: A Wrapper for functions, class objects and methods for deprecating keyword parameters
+Author: Vizonex
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions; python_version < "3.10"
+Dynamic: license-file
+
+# Deprecated Params 
+
+Inspired after python's warning.deprecated wrapper, deprecated_params is made to serve the single purpose of deprecating parameter names to warn users
+about incoming changes as well as retaining typehinting.
+
+
+
+## How to Deprecate Parameters
+Parameters should be keyword arguments, not positional, Reason
+for this implementation is that in theory you should've already 
+planned an alternative approch to an argument you wish 
+to deprecate.
+
+```python
+from deprecated_params import deprecated_params
+
+@deprecated_params(['x'])
+def func(y, *, x:int = 0):
+    pass
+
+# DeprecationWarning: Parameter "x" is deprecated
+func(None, x=20)
+
+# NOTE: **kw is accepted but also you could put down more than one 
+# parameter if needed...
+@deprecated_params(['foo'], {"foo":"foo was removed in ... don't use it"}, display_kw=False)
+class MyClass:
+    def __init__(self, spam:object, **kw):
+        self.spam = spam
+        self.foo = kw.get("foo", None)
+
+# DeprecationWarning: foo was removed in ... don't use it
+mc = MyClass("spam", foo="X")
+```

deprecated_params-0.1.0/README.md

@@ -0,0 +1,34 @@
+# Deprecated Params 
+
+Inspired after python's warning.deprecated wrapper, deprecated_params is made to serve the single purpose of deprecating parameter names to warn users
+about incoming changes as well as retaining typehinting.
+
+
+
+## How to Deprecate Parameters
+Parameters should be keyword arguments, not positional, Reason
+for this implementation is that in theory you should've already 
+planned an alternative approch to an argument you wish 
+to deprecate.
+
+```python
+from deprecated_params import deprecated_params
+
+@deprecated_params(['x'])
+def func(y, *, x:int = 0):
+    pass
+
+# DeprecationWarning: Parameter "x" is deprecated
+func(None, x=20)
+
+# NOTE: **kw is accepted but also you could put down more than one 
+# parameter if needed...
+@deprecated_params(['foo'], {"foo":"foo was removed in ... don't use it"}, display_kw=False)
+class MyClass:
+    def __init__(self, spam:object, **kw):
+        self.spam = spam
+        self.foo = kw.get("foo", None)
+
+# DeprecationWarning: foo was removed in ... don't use it
+mc = MyClass("spam", foo="X")
+```

deprecated_params-0.1.0/deprecated_params/__init__.py

@@ -0,0 +1,273 @@
+"""
+Deprecated Params
+-----------------
+
+A Library dedicated for warning users about deprecated paramter
+names and changes
+
+
+
+"""
+
+from __future__ import annotations
+
+import inspect
+import sys
+import warnings
+import functools
+import inspect
+from types import MethodType
+from typing import Callable, Sequence, TypeVar, Mapping, overload
+
+if sys.version_info < (3, 10):
+    from typing_extensions import ParamSpec
+else:
+    from typing import ParamSpec
+
+
+__version__ = "0.1.0"
+__license__ = "Appache 2.0"
+
+
+_T = TypeVar("_T", covariant=True)
+_P = ParamSpec("_P")
+
+KEYWORD_ONLY = inspect.Parameter.KEYWORD_ONLY
+VAR_KEYWORD = inspect.Parameter.VAR_KEYWORD
+
+
+__all__ = (
+    "MissingKeywordsError",
+    "InvalidParametersError",
+    "deprecated_params",
+)
+
+
+class _KeywordsBaseException(Exception):
+    def __init__(self, keywords: set[str], *args):
+        self._keywords = keywords
+        super().__init__(*args)
+
+    @property
+    def keywords(self):
+        return self._keywords
+
+    @keywords.setter
+    def keywords(self, kw):
+        raise ValueError("keywords property is immutable")
+
+
+class MissingKeywordsError(_KeywordsBaseException):
+    """Missing keyword for argument"""
+
+    def __init__(self, keywords: set[str], *args):
+        super().__init__(
+            keywords, f"Missing Keyword arguments for: {list(keywords)!r}", *args
+        )
+
+
+class InvalidParametersError(_KeywordsBaseException):
+    """Parameters were positonal arguments without defaults or keyword arguments"""
+
+    def __init__(self, keywords: set[str], *args):
+        super().__init__(
+            keywords,
+            f"Arguments :{list(keywords)!r} should not be positional",
+            *args,
+        )
+
+
+class deprecated_params:
+    """
+    A Wrapper inspired by python's wrapper deprecated from 3.13
+    and is used to deprecate parameters
+    """
+
+    def __init__(
+        self,
+        params: Sequence[str],
+        message: str | Mapping[str, str] = "is deprecated",
+        /,
+        *,
+        # default_message should be utilized when a keyword isn't
+        # given in message if messaged is defined as a dictionary.
+        default_message: str | None = None,
+        category: type[Warning] | None = DeprecationWarning,
+        stacklevel: int = 3,
+        display_kw: bool = True,
+    ):
+        if not isinstance(message, (str, dict, Mapping)):
+            raise TypeError(
+                f"Expected an object of type str or dict or Mappable type for 'message', not {type(message).__name__!r}"
+            )
+
+        self.params = set(params)
+        self.message = message or "is deprecated"
+        self.message_is_dict = isinstance(message, (Mapping, dict))
+        self.display_kw = display_kw
+        self.category = category
+        self.stacklevel = stacklevel
+        self.default_message = default_message or "do not use"
+
+    def __check_with_missing(
+        self,
+        fn,
+        missing: set[str] | None = None,
+        invalid_params: set[str] | None = None,
+        skip_missing: bool | None = None,
+        allow_miss: bool = False,
+    ):
+        sig = inspect.signature(fn)
+
+        missing = missing if missing is not None else set(self.params)
+        invalid_params = set() if invalid_params is None else invalid_params
+
+        skip_missing = (
+            any([p.kind == VAR_KEYWORD for p in sig.parameters.values()])
+            if skip_missing is None
+            else skip_missing
+        )
+
+        for m in self.params:
+            if not allow_miss:
+                p = sig.parameters[m]
+            else:
+                p = sig.parameters.get(m) # type: ignore
+                if p is None:
+                    continue
+            print(p.kind, p.name)
+            # Check if were keyword only or aren't carrying a default param
+            if p.kind != KEYWORD_ONLY:
+                # Anything this isn't a keyword should be considered as deprecated
+                # as were still technically using it.
+                invalid_params.add(p.name)
+
+            if not skip_missing:
+                missing.remove(p.name)
+
+        return missing, invalid_params, skip_missing
+
+    def __check_for_missing_kwds(
+        self,
+        fn,
+        missing: set[str] | None = None,
+        invalid_params: set[str] | None = None,
+        skip_missing: bool | None = None,
+        allow_miss: bool = False,
+    ):
+        # copy sequence to check for missing parameter names
+        missing, invalid_params, skip_missing = self.__check_with_missing(
+            fn, missing, invalid_params, skip_missing, allow_miss
+        )
+
+        if invalid_params:
+            raise InvalidParametersError(invalid_params)
+
+        if missing and not skip_missing:
+            raise MissingKeywordsError(missing)
+
+    def __warn(self, kw_name: str):
+        msg = ""
+        if self.display_kw:
+            msg += 'Parameter "%s" ' % kw_name
+
+        if self.message_is_dict:
+            msg += self.message.get(kw_name, self.default_message)  # type: ignore
+        else:
+            msg += self.message  # type: ignore
+
+        warnings.warn(msg, self.category, stacklevel=self.stacklevel + 1)
+
+    @overload
+    def __call__(self, arg: type[_T]) -> type[_T]: ...
+
+    @overload
+    def __call__(self, arg: Callable[_P, _T]) -> Callable[_P, _T]: ...
+
+    # Mirrors python's deprecated wrapper with a few changes
+    def __call__(self, arg):
+        not_dispatched = self.params.copy()
+
+        @functools.wraps(not_dispatched)
+        def check_kw_arguments(kw: dict):
+            if not_dispatched:
+                for k in kw.keys():
+                    print(k, not_dispatched)
+                    if k in not_dispatched:
+                        self.__warn(k)
+                        # remove after so we don't repeat
+                        not_dispatched.remove(k)
+
+        if isinstance(arg, type):
+            # NOTE: Combining init and new together is done to
+            # solve deprecation of both new_args and init_args
+
+            missing, invalid_params, skip_missing = self.__check_with_missing(
+                arg.__init__, allow_miss=True
+            )
+
+            original_new = arg.__new__
+            self.__check_for_missing_kwds(
+                original_new, missing, invalid_params, skip_missing, allow_miss=True
+            )
+
+            @functools.wraps(original_new)
+            def __new__(cls, /, *args, **kwargs):
+                check_kw_arguments(kwargs)
+                if original_new is not object.__new__:
+                    return original_new(cls, *args, **kwargs)
+                # Python Comment: Mirrors a similar check in object.__new__.
+                elif cls.__init__ is object.__init__ and (args or kwargs):
+                    raise TypeError(f"{cls.__name__}() takes no arguments")
+                else:
+                    return original_new(cls)
+
+            arg.__new__ = staticmethod(__new__)
+
+            original_init_subclass = arg.__init_subclass__
+            # Python Comment: We need slightly different behavior if __init_subclass__
+            # is a bound method (likely if it was implemented in Python)
+            if isinstance(original_init_subclass, MethodType):
+                self.__check_for_missing_kwds(original_init_subclass)
+
+                original_init_subclass = original_init_subclass.__func__
+
+                @functools.wraps(original_init_subclass)
+                def __init_subclass__(*args, **kwargs):
+                    check_kw_arguments(kwargs)
+                    return original_init_subclass(*args, **kwargs)
+
+                arg.__init_subclass__ = classmethod(__init_subclass__)
+            # Python Comment: Or otherwise, which likely means it's a builtin such as
+            # object's implementation of __init_subclass__.
+            else:
+
+                @functools.wraps(original_init_subclass)
+                def __init_subclass__(*args, **kwargs):
+                    check_kw_arguments(kwargs)
+                    return original_init_subclass(*args, **kwargs)
+
+                arg.__init_subclass__ = __init_subclass__
+
+            return arg
+
+        elif callable(arg):
+            # Check for missing functon arguments
+            self.__check_for_missing_kwds(arg)
+
+            @functools.wraps(arg)
+            def wrapper(*args, **kwargs):
+                check_kw_arguments(kwargs)
+                return arg(*args, **kwargs)
+
+            if sys.version_info >= (3, 12):
+                if inspect.iscoroutinefunction(arg):
+                    wrapper = inspect.markcoroutinefunction(wrapper)
+
+            return wrapper
+
+        else:
+            raise TypeError(
+                "@deprecated_params decorator with non-None category must be applied to "
+                f"a class or callable, not {arg!r}"
+            )

deprecated_params-0.1.0/deprecated_params.egg-info/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: deprecated-params
+Version: 0.1.0
+Summary: A Wrapper for functions, class objects and methods for deprecating keyword parameters
+Author: Vizonex
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions; python_version < "3.10"
+Dynamic: license-file
+
+# Deprecated Params 
+
+Inspired after python's warning.deprecated wrapper, deprecated_params is made to serve the single purpose of deprecating parameter names to warn users
+about incoming changes as well as retaining typehinting.
+
+
+
+## How to Deprecate Parameters
+Parameters should be keyword arguments, not positional, Reason
+for this implementation is that in theory you should've already 
+planned an alternative approch to an argument you wish 
+to deprecate.
+
+```python
+from deprecated_params import deprecated_params
+
+@deprecated_params(['x'])
+def func(y, *, x:int = 0):
+    pass
+
+# DeprecationWarning: Parameter "x" is deprecated
+func(None, x=20)
+
+# NOTE: **kw is accepted but also you could put down more than one 
+# parameter if needed...
+@deprecated_params(['foo'], {"foo":"foo was removed in ... don't use it"}, display_kw=False)
+class MyClass:
+    def __init__(self, spam:object, **kw):
+        self.spam = spam
+        self.foo = kw.get("foo", None)
+
+# DeprecationWarning: foo was removed in ... don't use it
+mc = MyClass("spam", foo="X")
+```

deprecated_params-0.1.0/deprecated_params.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+deprecated_params/__init__.py
+deprecated_params.egg-info/PKG-INFO
+deprecated_params.egg-info/SOURCES.txt
+deprecated_params.egg-info/dependency_links.txt
+deprecated_params.egg-info/requires.txt
+deprecated_params.egg-info/top_level.txt
+tests/test_wrapper.py

deprecated_params-0.1.0/deprecated_params.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

deprecated_params-0.1.0/deprecated_params.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[:python_version < "3.10"]
+typing-extensions

deprecated_params-0.1.0/deprecated_params.egg-info/top_level.txt

@@ -0,0 +1 @@
+deprecated_params

deprecated_params-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["setuptools"]
+
+[project]
+name = "deprecated-params"
+version = "0.1.0"
+description = "A Wrapper for functions, class objects and methods for deprecating keyword parameters"
+readme = "README.md"
+authors = [
+    { name = "Vizonex" },
+]
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    'typing-extensions; python_version<"3.10"'
+]
+

deprecated_params-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deprecated_params-0.1.0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+if __name__ == "__main__":
+    setup()

deprecated_params-0.1.0/tests/test_wrapper.py

@@ -0,0 +1,52 @@
+import pytest
+from deprecated_params import deprecated_params
+
+
+# should carry w x y
+def test_deprecated_param():
+    @deprecated_params(["x"], "is deprecated")
+    def my_func(w: int, *, x: int = None, y: int = None):
+        pass
+
+    with pytest.warns(DeprecationWarning, match='Parameter "x" is deprecated'):
+        my_func(0, x=0)
+
+
+def test_class_wrapper_and_kw_display_disabled():
+    @deprecated_params(["foo"], "foo is deprecated", display_kw=False)
+    class MyClass:
+        def __init__(self, spam: object, *, foo: object = None):
+            self.spam = spam
+            self.foo = foo
+
+    mc = MyClass("spam")
+    assert mc.spam == "spam"
+    assert mc.foo == None
+
+    with pytest.warns(DeprecationWarning, match="foo is deprecated"):
+        MyClass("spam", foo="foo")
+
+
+class TornadoWarning(DeprecationWarning):
+    pass
+
+
+def test_dataclasses_with_wrapper_message_dicts_custom_warning():
+    from dataclasses import dataclass, field
+
+    @deprecated_params(
+        ["foo"],
+        {"foo": "got foo", "spam": "got spam"},
+        display_kw=False,
+        category=TornadoWarning,
+    )
+    @dataclass
+    class Class:
+        foo: str | None = field(kw_only=True, default=None)
+        spam: str | None = field(kw_only=True, default=None)
+
+    with pytest.warns(TornadoWarning, match="got foo"):
+        Class(foo="foo")
+
+
+# TODO: Metaclasses...