black-magic 0.0.8

Currently there is only one module available. However, I am all open for
cool ideas.

black_magic.decorator

This is intended to become a more modern and flexible replacement for the
the well known decorator module. This module benefits an API for more
flexible usage. The behaviour of the decorator module can easily be
duplicated.

For those who don’t know the decorator module: It can be used to create
wrappers for functions that look identical to the original - a common task
when replacing functions via decorators.

Furthermore, this module makes it possible to create wrappers with modified
signatures. Currently, the only specialized function that is explicitly
dedicated to this purpose is partial. If you are interested in doing
more complex modifications you can pass a dynamically created Signature
to wraps. If you make something useful, please consider contributing
your functionality to this module.

.wraps()

wraps can be used similarly to the standard functools.wraps
function. However, it returns a real function, i.e. something that will
have a useful signature when being inspected with help() or by other
metaprogramming tools. Furthermore, it knows how to copy the signature
exactly, even remembering object identity of default arguments and
annotations:

Under the hood

WARNING: performance hits incoming

Decorating a function with the tools in this module is a quite costy
operation, so don’t do it very often! Invoking the wrapper is no problem on
the other hand.

WARNING: functools.partial is evil

Be careful when passing functools.partial objects into .wraps, or
any black magic functions more generally. functools.partial features
very unsensible handling of arguments that are bound by keyword. These, and
all subsequent arguments, become keyword-only parameters. Consider the
following example: