bot.utils.function

Utilities for interaction with functions.

Module Contents

Functions

get_arg_value(→ Any)	Return a value from arguments based on a name or position.
get_arg_value_wrapper(→ Decorator)	Call decorator_func with the value of the arg at the given name/position.
get_bound_args(→ BoundArgs)	Bind args and kwargs to func and return a mapping of parameter names to argument values.
update_wrapper_globals() → types.FunctionType)	Update globals of wrapper with the globals from wrapped.
command_wraps(...)	Update the decorated function to look like wrapped and update globals for discordpy forwardref evaluation.

Attributes

log
Argument
BoundArgs
Decorator
ArgValGetter

bot.utils.function.log

bot.utils.function.Argument

bot.utils.function.BoundArgs

bot.utils.function.Decorator

bot.utils.function.ArgValGetter

exception bot.utils.function.GlobalNameConflictError

Bases: Exception

Raised when there’s a conflict between the globals used to resolve annotations of wrapped and its wrapper.

bot.utils.function.get_arg_value(name_or_pos: Argument, arguments: BoundArgs) → Any

Return a value from arguments based on a name or position.

arguments is an ordered mapping of parameter names to argument values.

Raise TypeError if name_or_pos isn’t a str or int. Raise ValueError if name_or_pos does not match any argument.

bot.utils.function.get_arg_value_wrapper(decorator_func: collections.abc.Callable[[ArgValGetter], Decorator], name_or_pos: Argument, func: collections.abc.Callable[[Any], Any] | None = None) → Decorator

Call decorator_func with the value of the arg at the given name/position.

decorator_func must accept a callable as a parameter to which it will pass a mapping of parameter names to argument values of the function it’s decorating.

func is an optional callable which will return a new value given the argument’s value.

Return the decorator returned by decorator_func.

bot.utils.function.get_bound_args(func: collections.abc.Callable, args: tuple, kwargs: dict[str, Any]) → BoundArgs

Bind args and kwargs to func and return a mapping of parameter names to argument values.

Default parameter values are also set.

bot.utils.function.update_wrapper_globals(wrapper: types.FunctionType, wrapped: types.FunctionType, *, ignored_conflict_names: set[str] = frozenset()) → types.FunctionType

Update globals of wrapper with the globals from wrapped.

For forwardrefs in command annotations discordpy uses the __global__ attribute of the function to resolve their values, with decorators that replace the function this breaks because they have their own globals.

This function creates a new function functionally identical to wrapper, which has the globals replaced with a merge of `wrapped`s globals and the `wrapper`s globals.

An exception will be raised in case wrapper and wrapped share a global name that is used by wrapped’s typehints and is not in ignored_conflict_names, as this can cause incorrect objects being used by discordpy’s converters.

bot.utils.function.command_wraps(wrapped: types.FunctionType, assigned: collections.abc.Sequence[str] = functools.WRAPPER_ASSIGNMENTS, updated: collections.abc.Sequence[str] = functools.WRAPPER_UPDATES, *, ignored_conflict_names: set[str] = frozenset()) → collections.abc.Callable[[types.FunctionType], types.FunctionType]

Update the decorated function to look like wrapped and update globals for discordpy forwardref evaluation.