Skip to main content

Decorator utility that operates on black magic

Project description

Build Status Coverage Latest Version Downloads License

Metaprogramming modules that operate on black magic!

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.

Usage

This module exports two important functions: wraps and partial.

black_magic.decorator.wraps

You can use it just like the standard functools.wraps function:

>>> from black_magic.decorator import wraps

>>> x = []
>>> def real(a:int, b=x) -> "Returns b":
...     return b

>>> @wraps(real)
... def fake(*args, **kwargs):
...     print("Fake!")
...     return real(*args, **kwargs)

This will not only update the docstring of the fake function to look like the original but generate a wrapper function that has exactly the same signature:

>>> assert fake(1) is x   # check object-identity of default-parameter!
Fake!

>>> from inspect import signature
>>> assert signature(fake) == signature(real)

If you want to get real crazy you can even use ast.expr’s:

>>> import ast
>>> fake = wraps(real)(ast.Num(n=1))
>>> fake(0)
1

WARNING: Do NOT use black_magic.decorator.wraps with functools.partial! It won’t work (in most cases).

black_magic.decorator.partial

This is similar to the functools.partial function.

>>> from black_magic.decorator import partial

>>> def real(arg):
...     print(arg)
>>> partial(real, arg=0)()
0

There are some differences, though:

  • this function returns a function object which looks like the input function, except for the modified parameters.

  • all overwritten parameters are completely removed from the signature. In functools.partial this is true only for arguments bound by position.

  • the **kwargs are stripped first, then *args

    >>> partial(lambda a,b,c: (a,b,c), 2, a=1)(3)
    (1, 2, 3)
    
  • by leaving the func argument empty partial can act as decorator:

    >>> @partial(None, bar=0)
    ... def foo(bar):
    ...     print(bar)
    >>> foo()
    0
    

Under the hood

Q: This uses ugly str concat and eval code, right?

A: No, it uses abstract syntax trees to do its dynamic code generation.

Tests

This module has been tested to work on python{2.6, 2.7, 3.2, 3.3} and PyPy1.9 using Travis CI.

License

To the extent possible under law, Thomas Gläßle has waived all copyright and related or neighboring rights to black-magic. This work is published from: Germany.

To the extent possible under law, the person who associated CC0 with black-magic has waived all copyright and related or neighboring rights to black-magic.

You should have received a copy of the CC0 legalcode along with this work. If not, see http://creativecommons.org/publicdomain/zero/1.0/.

Changelog

0.0.5

  • add black_magic.decorator.partial

0.0.4

  • support any callable to be passed to ASTorator.decorate
  • convert README to .rst

Project details


Release history Release notifications

History Node

0.0.12

History Node

0.0.11

History Node

0.0.10

History Node

0.0.9

History Node

0.0.8

History Node

0.0.7

History Node

0.0.6

This version
History Node

0.0.5

History Node

0.0.4

History Node

0.0.3

History Node

0.0.2

History Node

0.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
black-magic-0.0.5.tar.gz (12.9 kB) Copy SHA256 hash SHA256 Source None Feb 14, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page