wabisabi

wabisabi.default_parameter_change(version, old_kwargs, library_name, current_library_version)

Deprecates a default value for a kwarg.

If the software version is greater or equal to that of version, this decorator returns the original function without any modifications.

If the user doesn’t specify a parameter that will change default values, it will issue a FutureWarning pointing to the line of his code, in a single warning for all changes in the default parameters.

It also modifies the __signature__ of the function so that the function appears to have the default parameters to whatever the default values are in the current version of the function.

Finally, if a docstring is provided, it appends a warning message compatible numpydoc.

Parameters

version: version-like

The version in which the parameter will take the new default value. If the software version reaches this value, the new default will be taken on without warning.

old_kwargs:

The list of keyword arguments, with their old default values specified, as a dictionary. You should be able to copy paste your old keyword arguments and put then in a dict.

library_namestr

The human readable name for your library.

current_library_versionversion-like

The current version of your library.

Examples

>>> @default_parameter_change('0.16', doc(this='tim'))
... def foo(this='foo', bar='zip'):
...     '''Prints your parameter.
...
...     **This function has a depeprecation decorator set to '0.16'**
...
...     Parameters
...     ----------
...     this : str
...         This is the string parameter that should be printed
...
...     '''
...     print(bar)
...     return this

wabisabi.kwonly_change(version, previous_arg_order=None, keep_old_signature=False, library_name=None, current_library_version=None)

Returns a decorator that enforces a smaller number of positional arguments.

If the current library version is smaller than version in which the new signature takes effect, this deprecator will:

Issue a warnign pointing to the user’s code if they call a function with too many positional arguments.

If you want to move the new keyword only arguments after the keyword only seperator, you should specify a list with the previous order of arguments as the parameter previous_arg_order. If this parameter is not specified, it is assumed that the previous function signature allowed all parameters to be specified as either positional or keyword arguments.

Parameters

version: version-like

Version in which the new function signature takes full effect.

previous_arg_order: list of strings or ``None``

If the function previously had keyword only arguments, you should use this to specify the names of previous positional arguments. If set to none, it is assumed that the previous version of the function would accept all parameters as positional or keyword arguments. Specifying this also allows you to re-order the new keyword only. To re-iterate, you cannot swap the order of positional arguments with this deprecator.

keep_old_signature: bool

If set to true, the signature will reflect the previous signature of the function. This is not recommended since showing new users the keyword-only version of the signature will not cause them to write wrong code. If they follow the new signature, their code will be correct and they will avoid the FutureWarning.

library_name: str

Friendly library name to include in warning messages

current_library_version: version-like

The current version of the shipped library (typically your module’s __version__).

Examples

>>> from wabisabi import kwonly_change
>>> import functools
>>>
>>> kwonly_change = functools.partial(kwonly_change,
...                                   library_name='my super lib',
...                                   current_library_version='0.14')
>>> @kwonly_change('0.15')
... def foo_new(zap='zip', *, bar='hello', baz='world'):
...     return zap + bar + baz