pydecor 2.0.1

Provided Decorators

This package provides generic decorators, which can be used with any function to provide extra utility to decorated resources, as well as prête-à-porter (ready-to-wear) decorators for immediate use.

While the information below is enough to get you started, I highly recommend checking out the decorator module docs to see all the options and details for the various decorators!

from pydecor import before

def before_func(_decorated, label=None):
    print(label)

@before(before_func, label='red')
def red_function():
    pass

red_function()

from pydecor import construct_decorator

def before_func(decorated):
    print('Starting decorated function '
          '"{}"'.format(decorated.wrapped.__name__))

def after_func(decorated):
    print('"{}" gave result "{}"'.format(
        decorated.wrapped.__name__, decorated.result
    ))

my_decorator = construct_decorator(before=before_func, after=after_func)

@my_decorator()
def this_function_returns_nothing():
    return 'nothing'

Starting decorated function "this_function_returns_nothing"
"this_function_returns_nothing" gave result "nothing"

from flask import Flask, Response, make_response
from pydecor import construct_decorator


def _set_app_json_header(decorated):
    # Ensure the response is a Response object, even if a tuple was
    # returned by the view function.
    response = make_response(decorated.result)
    response.headers.set('Content-Type', 'application/json')
    return response


application_json = construct_decorator(after=_set_app_json_header)


# Now you can decorate any Flask view, and your headers will be set.

app = Flask(__name__)

# Note that you must decorate "before" (closer to) the function than the
# app.route() decoration, because the route decorator must be called on
# the "finalized" version of your function

@app.route('/')
@application_json()
def root_view():
    return 'Hello, world!'

client = app.test_client()
response = app.get('/')

print(response.headers)

Content-Type: application/json
Content-Length: 13

Caches

Three caches are provided with pydecor. These are designed to be passed to the @memoization decorator if you want to use something other than the default LRUCache, but they are perfectly functional for use elsewhere.

All caches implement the standard dictionary interface.

Stacking

Generic and ready-to-wear decorators may be stacked! You can stack multiple of the same decorator, or you can mix and match. Some gotchas are listed below.

Generally, stacking works just as you might expect, but some care must be taken when using the @instead decorator, or @intercept, which uses @instead under the hood.

Just remember that @instead replaces everything that comes before. So, as long as @instead calls the decorated function, it’s okay to stack it. In these cases, it will be called before any decorators specified below it, and those decorators will be executed when it calls the decorated function. @intercept behaves this way, too.

If an @instead decorator does not call the decorated function and instead replaces it entirely, it must be specified first (at the bottom of the stacked decorator pile), otherwise the decorators below it will not execute.

For @before and @after, it doesn’t matter in what order the decorators are specified. @before is always called first, and @after last.

Class Decoration

Class decoration is difficult, but PyDecor aims to make it as easy and intuitive as possible!

By default, decorating a class applies that decorator to all of that class’ methods (instance, class, and static). The decoration applies to class and static methods whether they are referenced via an instance or via a class reference. “Extras” specified at the class level persist across calls to different methods, allowing for things like a class level memoization dictionary (there’s a very basic test in the test suite that demonstrates this pattern).

If you’d prefer that the decorator not apply to class and static methods, set the instance_methods_only=True when decorating the class.

If you want to decorate the class itself, and not its methods, keep in mind that the decorator will be triggered when the class is instantiated, and that, if the decorator replaces or alters the return, that return will replace the instantiated class. With those caveats in mind, setting implicit_method_decoration=False when decorating a class enables that functionality.

Method Decoration

Decorators can be applied to static, class, or instance methods directly, as well. If combined with @staticmethod or @classmethod decorators, those decorators should always be at the “top” of the decorator stack (furthest from the function).

When decorating instance methods, self is removed from the parameters passed to the provided callable.

When decorating class methods, cls is removed from the parameters passed to the provided callable.

Currently, the class and instance references do not have to be named "cls" and "self", respectively, in order to be removed. However, this is not guaranteed for future releases, so try to keep your naming standard if you can (just FYI, "self" is the more likely of the two to wind up being required).

Update a Function’s Args or Kwargs

Functions passed to @before can either return None, in which case nothing happens to the decorated functions parameters, or they can return a tuple of args (as a tuple) and kwargs (as a dict), in which case those parameters are used in the decorated function. In this example, we sillify a very serious function.

from pydecor import before

def spamify_func(decorated):
    """Mess with the function arguments"""
    args = tuple(['spam' for _ in decorated.args])
    kwargs = {k: 'spam' for k in decorated.kwargs}
    return args, kwargs


@before(spamify_func)
def serious_function(serious_string, serious_kwarg='serious'):
    """A very serious function"""
    print('A serious arg: {}'.format(serious_string))
    print('A serious kwarg: {}'.format(serious_kwarg))

serious_function('Politics', serious_kwarg='Religion')

The output?

A serious arg: spam
A serious kwarg: spam

Do Something with a Function’s Return Value

Functions passed to @after receive the decorated function’s return value as part of the Decorated instance. If @after returns None, the return value is sent back unchanged. However, if @after returns something, its return value is sent back as the return value of the function.

In this example, we ensure that a function’s return value has been thoroughly spammified.

from pydecor import after

def spamify_return(decorated):
    """Spamify the result of a function"""
    return 'spam-spam-spam-spam-{}-spam-spam-spam-spam'.format(decorated.result)


@after(spamify_return)
def unspammed_function():
    """Return a non-spammy value"""
    return 'beef'

print(unspammed_function())

The output?

spam-spam-spam-spam-beef-spam-spam-spam-spam

Do Something Instead of a Function

Functions passed to @instead also provide wrapped context via the Decorated object. But, if the instead callable does not call the wrapped function, it won’t get called at all. Maybe you want to skip a function when a certain condition is True, but you don’t want to use pytest.skipif, because pytest can’t be a dependency of your production code for whatever reason.

from pydecor import instead

def skip(decorated, when=False):
    if when:
        pass
    else:
        # Calling `decorated` calls the wrapped function.
        return decorated(*decorated.args, **decorated.kwargs)


@instead(skip, when=True)
def uncalled_function():
    print("You won't see me (you won't see me)")


uncalled_function()

The output?

(There is no output, because the function was skipped)

Automatically Log Function Calls and Results

Maybe you want to make sure your functions get logged without having to bother with the logging boilerplate each time. @log_call tries to automatically get a logging instance corresponding to the module in which the decoration occurs (in the same way as if you made a call to logging.getLogger(__name__), or you can pass it your own, fancy, custom, spoiler-bedecked logger instance.

from logging import getLogger, StreamHandler
from sys import stdout

from pydecor import log_call


# We're just getting a logger here so we can see the output. This isn't
# actually necessary for @log_call to work!
log = getLogger(__name__)
log.setLevel('DEBUG')
log.addHandler(StreamHandler(stdout))


@log_call()
def get_lucky(*args, **kwargs):
    """We're up all night 'till the sun."""
    return "We're up all night for good fun."


get_lucky('Too far', 'to give up', who_we='are')

And the output?

get_lucky(*('Too far', 'to give up'), **{'who_we': 'are'}) -> "We're up all night for good fun"

Intercept an Exception and Re-raise a Custom One

Are you a put-upon library developer tired of constantly having to re-raise custom exceptions so that users of your library can have one nice try/except looking for your base exception? Let’s make that easier:

from pydecor import intercept


class BetterException(Exception):
    """Much better than all those other exceptions"""


@intercept(catch=RuntimeError, reraise=BetterException)
def sometimes_i_error(val):
    """Sometimes, this function raises an exception"""
    if val > 5:
        raise RuntimeError('This value is too big!')


for i in range(7):
    sometimes_i_error(i)

The output?

Traceback (most recent call last):
  File "/Users/Nautilus/Library/Preferences/PyCharm2017.1/scratches/scratch_1.py", line 88, in <module>
    sometimes_i_error(i)
  File "/Users/Nautilus/Documents/Programming/pydecor/pydecor/decorators.py", line 389, in wrapper
    return fn(**fkwargs)
  File "/Users/Nautilus/Documents/Programming/pydecor/pydecor/functions.py", line 58, in intercept
    raise_from(new_exc, context)
  File "<string>", line 2, in raise_from
__main__.BetterException: This value is too big!

Intercept an Exception, Do Something, and Re-raise the Original

Maybe you don’t want to raise a custom exception. Maybe the original one was just fine. All you want to do is print a special message before re-raising the original exception. PyDecor has you covered:

from pydecor import intercept


def print_exception(exc):
    """Make sure stdout knows about our exceptions"""
    print('Houston, we have a problem: {}'.format(exc))


@intercept(catch=Exception, handler=print_exception, reraise=True)
def assert_false():
    """All I do is assert that False is True"""
    assert False, 'Turns out, False is not True'


assert_false()

And the output:

Houston, we have a problem: Turns out, False is not True
Traceback (most recent call last):
  File "/Users/Nautilus/Library/Preferences/PyCharm2017.1/scratches/scratch_1.py", line 105, in <module>
    assert_false()
  File "/Users/Nautilus/Documents/Programming/pydecor/pydecor/decorators.py", line 389, in wrapper
    return fn(**fkwargs)
  File "/Users/Nautilus/Documents/Programming/pydecor/pydecor/functions.py", line 49, in intercept
    return decorated(*decorated_args, **decorated_kwargs)
  File "/Users/Nautilus/Library/Preferences/PyCharm2017.1/scratches/scratch_1.py", line 102, in assert_false
    assert False, 'Turns out, False is not True'
AssertionError: Turns out, False is not True

Intercept an Exception, Handle, and Be Done with It

Sometimes an exception isn’t the end of the world, and it doesn’t need to bubble up to the top of your application. In these cases, maybe just handle it and don’t re-raise:

from pydecor import intercept


def let_us_know_it_happened(exc):
    """Just let us know an exception happened (if we are reading stdout)"""
    print('This non-critical exception happened: {}'.format(exc))


@intercept(catch=ValueError, handler=let_us_know_it_happened)
def resilient_function(val):
    """I am so resilient!"""
    val = int(val)
    print('If I get here, I have an integer: {}'.format(val))


resilient_function('50')
resilient_function('foo')

Output:

If I get here, I have an integer: 50
This non-critical exception happened: invalid literal for int() with base 10: 'foo'

Note that the function does not continue running after the exception is handled. Use this for short-circuiting under certain conditions rather than for instituting a try/except:pass block. Maybe one day I’ll figure out how to make this work like that, but as it stands, the decorator surrounds the entire function, so it does not provide that fine-grained level of control.

More Prête-à-porter Decorators

• skipif - similar to py.test’s decorator, skip the function if a provided condition is True

Let me know if you’ve got any idea for other decorators that would be nice to have!

Type Annotations

Now that we’ve dropped support for Python 2, we can use type annotations to properly annotate function inputs and return values and make them available to library authors.

Contributor Conduct

There is a CODE_OF_CONDUCT.md file with details, based on one of GitHub’s templates, but the upshot is that I expect everyone who contributes to this project to do their best to be helpful, friendly, and patient. Discrimination of any kind will not be tolerated and will be promptly reported to GitHub.

On a personal note, Open Source survives because of people who are willing to contribute their time and effort for free. The least we can do is treat them with respect.

Tests

Tests can be run with:

make test

This will use whatever your local python3 happens to be. If you have other pythons available, you can run:

make tox

to try to run locally for all supported Python versions.

If you have docker installed, you can run:

make test-docker-{version}  # e.g. make test-docker-3.6

to pull down an appropriate Docker image and run tests inside of it. You can also run:

make test-docker

to do this for all supported versions of Python.

PRs that cause tests to fail will not be merged until tests pass.

Any new functionality is expected to come with appropriate tests. If you have any questions, feel free to reach out to me via email at msplanchard @ gmail or on GH via Issues.

Autoformatting

This project uses black for autoformatting. I recommend setting your editor up to format on save for this project, but you can also run:

make fmt

to format everything.

Linting

Linting can be run with:

make lint

Currently, linting verifies that there are:

• No flake8 errors

• No mypy errors

• No pylint errors

• No files that need be formatted

You should ensure that make lint returns 0 before opening a PR.

Docs

Docs are autogenerated via Sphinx. You can build them locally by running:

make docs

You can then open docs/_build/html/index.html in your web browser of choice to see how the documentation will look with your changes.

Deployment

Deployment is handled through pushing tags. Any tag pushed to GH causes a push to PyPI if the current version is not yet present there.

Pushing the appropriate tag is made easier through the use of:

VERSION=1.0.0 make distribute

where VERSION obviously should be the current version. This will verify the specified version matches the package’s current version, check to be sure that the most recent master is being distributed, prompt for a message, and create and push a signed tag of the format v{version}.