Module Contents

The module unittest_expander’s public interface consists of the following functions, classes and constants.

(See: Narrative Documentation – for a much richer description of most of them, including a lot of usage examples…)

The expand() class decorator

@expand

or

@expand(*, into=globals())

Deprecated since version 0.4.0: The into argument will become illegal in the version 0.5.0.

———

This decorator is intended to be applied to test classes: doing that causes that test parameters – previously attached to related test methods (and/or classes) by decorating them with foreach() – are “expanded”, that is, actual parametrized versions of those methods (and/or classes) are generated.

The public interface provided by expand() includes also the following attributes (making it possible to customize how names of parametrized test methods and classes are generated):

expand.global_name_pattern

expand.global_name_formatter

The foreach() method/class decorator

@foreach(param_collection)

param_collection must be a parameter collection – that is, one of:

• a paramseq instance,
• a sequence not being a text string (in other words, such an object for whom isinstance(obj, collections.abc.Sequence) and not isinstance(obj, str) returns True in Python 3) – for example, a list,
• a mapping (i.e., such an object that isinstance(obj, collections.abc.Mapping) returns True in Python 3) – for example, a dict,
• a set (i.e., such an object that isinstance(obj, collections.abc.Set) returns True in Python 3) – for example, a set or frozenset,
• a callable (i.e., such an object that callable(obj) returns True) which is supposed: to accept one positional argument (the test class) or no arguments at all, and to return an iterable object (i.e., an object that could be used as a for loop’s subject, able to yield consecutive items) – for example, a generator.

Any valid parameter collection will be, under the hood, automatically coerced to a paramseq.

Deprecated since version 0.4.0: A parameter collection given as a tuple (i.e., an instance of the built-in type tuple or of a subclass of it, e.g., a named tuple) will become illegal in the version 0.5.0 (note that this deprecation concerns tuples used as parameter collections themselves, not as items of parameter collections; the latter are – and will be – perfectly OK). As a parameter collection, instead of a tuple, use another type (e.g., a list).

Deprecated since version 0.4.3: A parameter collection given as an instance of the Python 3 built-in type bytes or bytearray (or of a subclass thereof) will become illegal in the version 0.5.0.

Each item of a parameter collection is supposed to be:

• a param instance,
• a tuple (converted automatically to a param which contains parameter values being the items of that tuple),
• any other object (converted automatically to a param which contains only one parameter value: that object).

or

@foreach(*param_collection_items, **param_collection_labeled_items)

The total number of given arguments (positional and/or keyword ones) must be greater than 1. Each argument will be treated as a parameter collection’s item (see above); for each keyword argument (if any), its name will be used to label() the item it refers to.

———

This decorator is intended to be applied to test methods and/or test classes – to attach to those methods (or classes) the test parameters from the specified parameter collection (only then it is possible to generate, by using expand(), actual parametrized methods and/or classes…).

Deprecated since version 0.4.0: Support for decorating test classes with foreach() will be removed in the version 0.5.0.

The paramseq class

class paramseq(param_collection)

param_collection must be a parameter collection – that is, one of:

• a paramseq instance,
• a sequence not being a text string (in other words, such an object for whom isinstance(obj, collections.abc.Sequence) and not isinstance(obj, str) returns True in Python 3) – for example, a list,
• a mapping (i.e., such an object that isinstance(obj, collections.abc.Mapping) returns True in Python 3) – for example, a dict,
• a set (i.e., such an object that isinstance(obj, collections.abc.Set) returns True in Python 3) – for example, a set or frozenset,
• a callable (i.e., such an object that callable(obj) returns True) which is supposed: to accept one positional argument (the test class) or no arguments at all, and to return an iterable object (i.e., an object that could be used as a for loop’s subject, able to yield consecutive items) – for example, a generator.

Deprecated since version 0.4.0: A parameter collection given as a tuple (i.e., an instance of the built-in type tuple or of a subclass of it, e.g., a named tuple) will become illegal in the version 0.5.0 (note that this deprecation concerns tuples used as parameter collections themselves, not as items of parameter collections; the latter are – and will be – perfectly OK). As a parameter collection, instead of a tuple, use another type (e.g., a list).

Deprecated since version 0.4.3: A parameter collection given as an instance of the Python 3 built-in type bytes or bytearray (or of a subclass thereof) will become illegal in the version 0.5.0.

Each item of a parameter collection is supposed to be:

• a param instance,
• a tuple (converted automatically to a param which contains parameter values being the items of that tuple),
• any other object (converted automatically to a param which contains only one parameter value: that object).

or

class paramseq(*param_collection_items, **param_collection_labeled_items)

The total number of given arguments (positional and/or keyword ones) must be greater than 1. Each argument will be treated as a parameter collection’s item (see above); for each keyword argument (if any), its name will be used to label() the item it refers to.

———

A paramseq instance is the canonical form of a parameter collection – whose items are param instances.

The public interface provided by this class includes the following instance methods:

__add__(param_collection)

Returns a new paramseq instance – being a result of concatenation of the current paramseq instance and given param_collection (see the description of the paramseq constructor’s argument param_collection…).

Deprecated since version 0.4.0: param_collection being a tuple will become illegal in the version 0.5.0.

Deprecated since version 0.4.3: param_collection being a Python 3 bytes or bytearray will become illegal in the version 0.5.0.

__radd__(param_collection)

Returns a new paramseq instance – being a result of concatenation of given param_collection (see the description of the paramseq constructor’s argument param_collection…) and the current paramseq instance.

Deprecated since version 0.4.0: param_collection being a tuple will become illegal in the version 0.5.0.

Deprecated since version 0.4.3: param_collection being a Python 3 bytes or bytearray will become illegal in the version 0.5.0.

context(context_manager_factory, *its_args, **its_kwargs, _enable_exc_suppress_=False)

Returns a new paramseq instance contaning clones of the items of the current instance – each cloned with a param.context() call (see below), to which all given arguments are passed.

The param class

class param(*args, **kwargs)

args and kwargs specify actual (positional and keyword) arguments to be passed to test method call(s).

———

A param instance is the canonical form of a parameter collection’s item. It represents a single combination of test parameter values.

The public interface provided by this class includes the following instance methods:

context(context_manager_factory, *its_args, **its_kwargs, _enable_exc_suppress_=False)

Returns a new param instance being a clone of the current instance, with the specified context manager factory (and its arguments) attached.

By default, the possibility to suppress exceptions by returning a true value from context manager’s __exit__() is disabled (exceptions are propagated even if __exit__() returns True); to enable this possibility you need to set the _enable_exc_suppress_ keyword argument to True.

label(text)

Returns a new param instance being a clone of the current instance, with the specified textual label attached.

Non-essential constants and classes

The __version__ constant

__version__

The version of unittest_expander as a PEP 440-compliant identifier (being a str).

The Substitute class

class Substitute(actual_object)

actual_object is the object to be proxied (typically, it is a test method or test class, previously decorated with foreach()).

———

Apart from exposing in a transparent way nearly all attributes of the proxied object, the public interface provided by this class includes the following instance attribute:

actual_object

The proxied object itself (unwrapped).

Substitute instances are not callable.