xotl.tools.decorator - Several decorators

This module contains several useful decorators, for several purposed. Also it severs as a namespace for other well-defined types of decorators.

Warning

This modules will be progressively deprecated during the 1.6 series.

We feel that either xotl.tools.objects or xotl.tools.functools are a better match for some of these decorators. But since we need to make sure about keeping dependencies, the deprecation won’t be final until 1.7.0. After 1.8.0, this modules will be finally removed.

Top-level decorators

class xotl.tools.decorator.AttributeAlias(attr_name)[source]

Descriptor to create aliases for object attributes.

This descriptor is mainly to be used internally by aliases() decorator.

xotl.tools.decorator.settle(**kwargs)[source]

Returns a decorator to settle attributes to the decorated target.

Usage:

>>> @settle(name='Name')
... class Person:
...    pass

>>> Person.name
'Name'
xotl.tools.decorator.namer(name, **kwargs)[source]

Like settle(), but ‘__name__’ is a required positional argument.

Usage:

>>> @namer('Identity', custom=1)
... class I:
...    pass

>>> I.__name__
'Identity'

>>> I.custom
1
xotl.tools.decorator.aliases(*names, **kwargs)[source]

In a class, create an AttributeAlias descriptor for each definition as keyword argument (alias=existing_attribute).

If “names” are given, then the definition context is looked and are assigned to it the same decorator target with all new names:

>>> @aliases('foo', 'bar')
... def foobar(*args):
...     'This function is added to its module with two new names.'
xotl.tools.decorator.assignment_operator(func, maybe_inline=False)[source]

Makes a function that receives a name, and other args to get its first argument (the name) from an assignment operation, meaning that it if its used in a single assignment statement the name will be taken from the left part of the = operator.

Warning

This function is dependant of CPython’s implementation of the language and won’t probably work on other implementations. Use only you don’t care about portability, but use sparingly (in case you change your mind about portability).

xotl.tools.decorator.instantiate(target, *args, **kwargs)[source]

Some singleton classes must be instantiated as part of its declaration because they represents singleton objects.

Every argument, positional or keyword, is passed as such when invoking the target. The following two code samples show two cases:

>>> @instantiate
... class Foobar:
...    def __init__(self):
...        print('Init...')
Init...


>>> @instantiate('test', context={'x': 1})
... class Foobar:
...    def __init__(self, name, context):
...        print('Initializing a Foobar instance with name={name!r} '
...              'and context={context!r}'.format(**locals()))
Initializing a Foobar instance with name='test' and context={'x': 1}

In all cases, Foobar remains the class, not the instance:

>>> Foobar  
<class '...Foobar'>
xotl.tools.decorator.constant_bagger(func, *args, **kwds)[source]

Create a “bag” with constant values.

Decorated object must be a callable, but the result will be a class containing the constant values.

For example:

>>> @constant_bagger
... def MYBAG():
...     return dict(X=1, Y=2)

It will generate:

class MYBAG:
    X = 1
    Y = 2

When called with arguments, these will be used as actual arguments for the decorated function:

>>> @constant_bagger(X=1, Y=2)
... def MYBAG(**kwds):
...     return kwds

Constant bags are singletons that can be updated:

>>> MYBAG(Z=3) is MYBAG
True

>>> MYBAG.Z
3
class xotl.tools.decorator.memoized_instancemethod(fget, doc=None)[source]

Decorate a method memoize its return value.

Best applied to no-arg methods: memoization is not sensitive to argument values, and will always return the same value even when called with different arguments.

This is extracted from the SQLAlchemy project’s codebase, merit and copyright goes to SQLAlchemy authors:

Copyright (C) 2005-2011 the SQLAlchemy authors and contributors

This module is part of SQLAlchemy and is released under the MIT License:
http://www.opensource.org/licenses/mit-license.php