stouputils.decorators.common module#

WRAPPED_ATTRIBUTE: str = '__wrapped__'[source]#

Attribute functools assigns last, so that inspect.signature() follows a wrapper back to the original.

safe_wraps(
wrapped: Any,
) → Callable[[WrapperT], WrapperT][source]#

Tolerant replacement for functools.wraps(), copying only the metadata that can actually be copied.

functools.wraps assigns __type_params__ among other attributes, and a function object rejects any value that is not a tuple. Decorating an object whose attributes are synthesised, such as a Sphinx autodoc mock, therefore raises TypeError and takes down the import of every module that touches the decorated symbol. Skipping the attributes that refuse to be copied keeps the decorator working on anything callable.

Parameters:

wrapped (Any) – Object the wrapper stands for

Returns:

Decorator applying the metadata to a wrapper

Return type:

Callable[[WrapperT], WrapperT]

Examples

>>> def original(a: int) -> int:
...     ''' Doc. '''
...     return a
>>> @safe_wraps(original)
... def wrapper(*args: Any, **kwargs: Any) -> int: ...
>>> wrapper.__name__, wrapper.__doc__.strip()
('original', 'Doc.')

An attribute a function refuses is skipped, where functools.wraps would raise TypeError:

>>> class Synthetic:
...     __type_params__ = "not a tuple"
>>> @safe_wraps(Synthetic())
... def survivor() -> None: ...
>>> survivor.__name__
'survivor'
get_function_name(
func: CallableAny,
) → str[source]#

Get the name of a function, returns “<unknown>” if the name cannot be retrieved.

get_wrapper_name(
decorator_name: str,
func: CallableAny,
) → str[source]#

Get a descriptive name for a wrapper function.

Parameters:

  • decorator_name (str) – Name of the decorator

  • func (CallableAny) – Function being decorated

Returns:

Combined name for the wrapper function (e.g., “stouputils.decorators.handle_error@function_name”)

Return type:

str

set_wrapper_name(
wrapper: CallableAny,
name: str,
) → None[source]#

Set the wrapper function’s visible name (code object name) for clearer tracebacks.

Parameters:

  • wrapper (CallableAny) – Wrapper function to update

  • name (str) – New name to set