deprecated-params documentation

Based off python’s warnings.deprecated(…) wrapper PEP 702

deprecated-params was made for solving the problems of warning users that certain parameters will not be used anymore and that better ones exist. The library’s intent is to be lazy yet readable, tiny, easy to use & disposable later from any python library as it’s aim is to be used temporarily until no longer required. Although libraries may have similar characteristics to this one, it was my goal to give a simplsitic package name with a simplsitic interface meant to be something small and easy to maintain over longer periods of time and hopes to be maintainable for many years to come. I have used it with my other pypi packages that I maintain already or it stilly currently has this library it inplace. deprecated-params should retain typehinting at all-times and should be able to retain type typehints of anything you can wrap to any function or class under the sun including functions like __init__, __init_subclass__ & __new__ all of which will retain Parameter data with ides such as Visual-Studio-Code, PyCharm and many more.

Goals & Mission

It will remain maintained until around 2040 or until something better comes along such as the python standard library adopting it’s own version of this library making the use of this library with newer versions of python obsolete.

Even if AI takes over it will attempt to remain written, developed and maintained by a human with the goal of remaining AI-Free software as a work of art.

Installation

$ pip install deprecated-params

The library requires Python 3.9 or newer.

API

Deprecated Params

A Library for to warning users about keyword parameters being removed or changed:

from deprecated_params import deprecated_params

@deprecated_params(['x'])
def func(y, *, x:int = 0):
    pass

It will remain maintained until around 2040 or until something better comes along such as the python standard library adopting it’s own version of this library making the use of this library with newer versions of python obsolete.

Even if AI takes over it will attempt to remain written, developed and maintained by a human with the goal of remaining AI-Free software as a work of art.

exception deprecated_params.InvalidParametersError(keywords: set[str], *args: Any)[source]

Raised when Parameters were positional arguments without defaults or keyword arguments

__init__(keywords: set[str], *args: Any) → None[source]

initializes invalid keywords, deprecated parameters should not be positional arguments as that would defeat the purpose of deprecating a function’s parameters.

exception deprecated_params.MissingKeywordsError(keywords: set[str], *args: Any)[source]

Raised when Missing a keyword for an argument

__init__(keywords: set[str], *args: Any) → None[source]

Initializes missing keywords

final class deprecated_params.deprecated_params(params: Sequence[str] | Iterable[str] | str, message: str | ~collections.abc.Mapping[str, str]='is deprecated', /, *, default_message: str | None = None, category: type[Warning] | None = <class 'DeprecationWarning'>, stacklevel: int = 1, display_kw: bool = True, removed_in: str | ~collections.abc.Sequence[int] | ~collections.abc.Mapping[str, str | ~collections.abc.Sequence[int]] | None=None)[source]

A Wrapper inspired by python’s wrapper deprecated from 3.13 used to for deprecating a function’s parameters.

Changed in version 0.1.8: this wrapper also passes along an attribute called __deprecated_params__ with a dictionary of all the preloaded deprecation warnings to each given parameter. Ides such as VSCode, Pycharm and more could theoretically utilize __deprecated_params__ elsewhere help to assist users and developers while writing and editing code.

Changed in version 0.8.0: __deprecated_params__ now uses an immutable dictionary called MappingProxyType to prevent needing to copy everything.

__call__(arg: type[_T]) → type[_T][source]
__call__(arg: Callable[[_P], _T]) → Callable[[_P], _T]

Call self as a function.

__init__(params: Sequence[str] | Iterable[str] | str, message: str | ~collections.abc.Mapping[str, str]='is deprecated', /, *, default_message: str | None = None, category: type[Warning] | None = <class 'DeprecationWarning'>, stacklevel: int = 1, display_kw: bool = True, removed_in: str | ~collections.abc.Sequence[int] | ~collections.abc.Mapping[str, str | ~collections.abc.Sequence[int]] | None=None) → None[source]

Initializes deprecated parameters to pass along to different functions

Parameters:

  • params – A Sequence of keyword parameters of single keyword parameter to deprecate and warn the removal of.

  • message –

    A single message for to assign to each parameter to be deprecated otherwise you can deprecate multiple under different reasons:

    @deprecated_params(
    ['mispel', 'x'],
    message={
        'mispel': 'misspells the word misspelling',
        'x':'you get the idea...'
    }
)
def mispelled_func(misspelling = None, *, mispel:str, x:int):
    ...

  • category – Used to warrant a custom warning category if required or needed to specify what Deprecation warning should appear.

  • stacklevel – What level should this wanring appear at? Default: 1

  • default_message – When a parameter doesn’t have a warning message try using this message instead

  • display_kw – Displays which parameter is deprecated in the warning message under Parameter “%s” … followed by the rest of the message

  • removed_in –

    Displays which version of your library’s program will remove this keyword parameter in:

    @deprecated_params(
    ['mispel', 'x'],
    removed_in={
        'mispel':'0.1.4',
        'x':(0, 1, 3)
    } # sequences of numbers are also allowed if preferred.
)

def mispelled_func(misspelling = None, *, mispel:str, x:int):
    ...

    you can also say that all parameters will be removed in one version:

    @deprecated_params(
    ['mispel', 'x'],
    removed_in='0.1.5' # or (0, 1, 5)
)
def mispelled_func(misspelling = None, *, mispel:str, x:int):
    ...

Indices and tables