Welcome to metawrap’s documentation!¶

Contents:

metawrap¶

A collection of wrappers for functions and classes.

Free software: BSD 3-Clause
Documentation: https://metawrap.readthedocs.io.

Features¶

TODO

Credits¶

This package was created with Cookiecutter and the nanshe-org/nanshe-cookiecutter project template.

Installation¶

Stable release¶

To install metawrap, run this command in your terminal:

$ pip install metawrap

This is the preferred method to install metawrap, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources¶

The sources for metawrap can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/jakirkham/metawrap

Or download the tarball:

$ curl  -OL https://github.com/jakirkham/metawrap/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage¶

To use metawrap in a project:

import metawrap

API¶

metawrap package¶

Submodules¶

metawrap.metawrap module¶

The module metawrap provides support decorating functions and classes.

Overview¶

The module metawrap extends wrapping abilities found in functools. In particular, it is ensured all wrapped functions contain an attribute __wrapped__, which points back to the original function before the wrapper was applied. Also, the ability to wrap classes with a decorator to apply a metaclass or series of ``metaclass``es is provided. Making it much easier to transform classes without mucking in their internals.

API¶

metawrap.metawrap.class_decorate_all_methods(*decorators)[source]¶

Returns a decorator that decorates a class such that all its methods are decorated by the decorators provided.

Parameters:	decorators (tuple*) – decorators to decorate all methods with.
Returns:	a decorator for the class.
Return type:	(decorator)

metawrap.metawrap.class_decorate_methods(**method_decorators)[source]¶

Returns a decorator that decorates a class such that specified methods are decorated by the decorators provided.

Parameters:	*method_decorators (tuple*) – method names with a single decorator or a list of decorators.
Returns:	a decorator for the class.
Return type:	(decorator)

metawrap.metawrap.class_static_variables(**kwargs)[source]¶

Returns a decorator that decorates a class such that it has the given static variables set.

Parameters:	*kwargs (tuple*) – keyword args will be set to the value provided.
Returns:	a decorator for the class.
Return type:	(decorator)

metawrap.metawrap.identity_wrapper(a_callable)[source]¶

Trivially wraps a given callable without doing anything else to it.

Parameters:	a_callable (callable) – the callable that is being wrapped.
Returns:	a wrapped callable.
Return type:	(callable)

metawrap.metawrap.metaclass(meta)[source]¶

Returns a decorator that decorates a class such that the given metaclass is applied.

Note

Decorator will add the __metaclass__ attribute so the last metaclass applied is known. Also, decorator will add the __wrapped__ attribute so that the unwrapped class can be retrieved.

Parameters:	meta (metaclass) – metaclass to apply to a given class.
Returns:	a decorator for the class.
Return type:	(decorator)

metawrap.metawrap.metaclasses(*metas)[source]¶

Returns a decorator that decorates a class such that the given metaclasses are applied.

Note

Shorthand for repeated application of metaclass.

Parameters:	metas (metaclasses*) – metaclasses to apply to a given class.
Returns:	a decorator for the class.
Return type:	(decorator)

metawrap.metawrap.repack_call_args(a_callable, *args, **kwargs)[source]¶

Reorganizes args and kwargs to match the given callables signature.

Parameters:

a_callable (callable) – some callable.
*args (callable) – positional arguments for the callable.
**kwargs (callable) – keyword arguments for the callable.

Returns:

all arguments as passed as position: arguments, all default arguments and all arguments passed as keyword arguments.

Return type:

args (tuple)

metawrap.metawrap.static_variables(**kwargs)[source]¶

Returns a decorator that decorates a callable such that it has the given static variables set.

Parameters:	kwargs (tuple*) – keyword args will be set to the value provided.
Returns:	a decorator for the callable.
Return type:	(decorator)

metawrap.metawrap.tied_call_args(a_callable, *args, **kwargs)[source]¶

Ties all the args to their respective variable names.

Parameters:

a_callable (callable) – some callable.
*args (callable) – positional arguments for the callable.
**kwargs (callable) – keyword arguments for the callable.

Returns:

ordered dictionary of arguments name and: their values, all variadic position arguments, all variadic keyword arguments.

Return type:

args (tuple)

metawrap.metawrap.unwrap(a_callable)[source]¶

Returns the underlying function that was wrapped.

Parameters:	a_callable (callable) – some wrapped (or not) callable.
Returns:	the callable that is no longer wrapped.
Return type:	(callable)

metawrap.metawrap.update_wrapper(wrapper, wrapped, assigned=('__module__', '__name__', '__doc__'), updated=('__dict__', ))[source]¶

Extends functools.update_wrapper to ensure that it stores the wrapped function in the attribute __wrapped__.

Parameters:	wrapper (callable) – the replacement callable. wrapped (callable) – the callable that is being wrapped. assigned (tuple) – is a tuple naming the attributes assigned directly from the wrapped function to the wrapper function (defaults to functools.WRAPPER_ASSIGNMENTS) updated (tuple) – is a tuple naming the attributes of the wrapper that are updated with the corresponding attribute from the wrapped function (defaults to functools.WRAPPER_UPDATES)
Returns:	the wrapped callable.
Return type:	(callable)

metawrap.metawrap.with_setup_state(setup=None, teardown=None)[source]¶

Adds setup and teardown callable to a function s.t. they can mutate it.

Based on with_setup from nose. This goes a bit further than nose does and provides a mechanism for the setup and teardown functions to change the callable in question. In other words, variables generated in setup can be stored in the functions globals and then cleaned up and removed in teardown. The final result of using this function should be a function equivalent to one generated by with_setup.

Parameters:	setup (callable) – A callable that takes the decorated function as an argument. This sets up the function before execution. teardown (callable) – A callable that takes the decorated function as an argument. This cleans up the function after execution.
Returns:	Does the actual decoration.
Return type:	callable

metawrap.metawrap.with_setup_state_handler(a_callable)[source]¶

A final wrapper for with_setup_state.

This calls setup and teardown before and after if defined. When used as a decorator, this should come after all setup and teardown calls.

Parameters:	a_callable (callable) – A callable to run `setup` and `teardown` on.
Returns:	The wrapped function.
Return type:	callable

metawrap.metawrap.wraps(wrapped, assigned=('__module__', '__name__', '__doc__'), updated=('__dict__', ))[source]¶

Builds on functools.wraps to ensure that it stores the wrapped function in the attribute __wrapped__.

Parameters:

wrapped (callable) – the callable that is being wrapped.
assigned (tuple) – is a tuple naming the attributes assigned directly from the wrapped function to the wrapper function (defaults to functools.WRAPPER_ASSIGNMENTS)
updated (tuple) – is a tuple naming the attributes of the wrapper that are updated with the corresponding attribute from the wrapped function (defaults to functools.WRAPPER_UPDATES)

Returns:

a decorator for callable, which will: contain wrapped.

Return type:

(callable)

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/jakirkham/metawrap/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

metawrap could always use more documentation, whether as part of the official metawrap docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/jakirkham/metawrap/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up metawrap for local development.

Fork the metawrap repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/metawrap.git

Install your local copy into an environment. Assuming you have conda installed, this is how you set up your fork for local development (on Windows drop source). Replace “<some version>” with the Python version used for testing.:
```
$ conda create -n metawrapenv python="<some version>"
$ source activate metawrapenv
$ python setup.py develop
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions:
```
$ flake8 metawrap tests
$ python setup.py test or py.test
```
To get flake8, just conda install it into your environment.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 2.7, 3.4, 3.5, and 3.6. Check https://travis-ci.org/jakirkham/metawrap/pull_requests and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ python -m unittest tests.test_metawrap

Welcome to metawrap’s documentation!¶

metawrap¶

Features¶

Credits¶

Installation¶

Stable release¶

From sources¶

Usage¶

API¶

metawrap package¶

Submodules¶

metawrap.metawrap module¶

Overview¶

API¶

Contributing¶

Types of Contributions¶

Report Bugs¶

Fix Bugs¶

Implement Features¶

Write Documentation¶

Submit Feedback¶

Get Started!¶

Pull Request Guidelines¶

Tips¶

Indices and tables¶