plastid.util.services.decorators module

Function decorators useful for scripts or analyses

Decorators

catch_warnings()
Catch warnings raised by wrapped function
deprecated()
Function or class decorator. Wrapped functions or classes raise FutureWarnings when called or instantiated, respectively
parallelize()
Parallelize the running of a single-parameter function over multiple instances of its parameter
catch_stdout()
Redirect standard out from a wrapped function into a buffer
catch_stderr()
Redirect standard error from a wrapped function into a buffer
in_separate_process()
Run decorated function in a separate process, to force garbage collection of that function’s memory contents when the function completes and reduce overall long-term memory usage.
notimplemented()
Wrapped functions raise NotImplementedErrors. Use if committing incomplete code.
notused()
No effects. Used for code annotation only
skip_if_abstract()
Function decorator for unit tests. Wrapped methods will be skipped if they are called from a unittest.TestCase with ‘Abstract’ in its name, and run only in subclasses of the abstract unittest.TestCase in which they are defined
plastid.util.services.decorators.catch_stderr(buf=None)[source]

Function factory producing decorators that capture stderr to a buffer

Parameters:
buf : file

Buffer that will hold captured stderr output. Must import write() and fileno() methods. If None, os.devnull will be used.

Returns:
function

Function decorator

Examples

Create a pipe, and use it to catch stderr:

>>> import sys
>>> import os
>>>
>>> def my_func():
>>>    sys.stderr.write("some message")

>>> read_end, write_end = os.pipe()
>>> buf = os.fdopen(write_end,"w")

>>> wrapped = catch_stderr(buf)(my_func)
>>> wrapped() # generates stderr

>>> buf.close()
>>> captured = os.fdopen(read_end).read()
>>> print(captured)
# output from captured stderr here

>>> captured.close() # remember to close!
plastid.util.services.decorators.catch_stdout(buf=None)[source]

Function factory producing decorators that capture stdout to a buffer

Parameters:
buf : file or None

Buffer that will hold captured stdout output. Must import write() and fileno() methods. If None, os.devnull will be used.

Returns:
function

Function decorator

Examples

Create a pipe, and use it to catch stdout:

>>> import sys
>>> import os
>>>
>>> def my_func():
>>>     sys.stdout.write("some message")

>>> read_end, write_end = os.pipe()
>>> buf = os.fdopen(write_end,"w")
>>> 
>>> wrapped = catch_stdout(buf)(my_func)
>>> wrapped() # generates stdout

>>> buf.close()
>>> captured = os.fdopen(read_end).read()
>>> print(captured)
# output here

>>> captured.close() # remember to close!
plastid.util.services.decorators.catch_warnings(simple_filter='ignore')[source]

Function factory producing function decorators that suppress warnings

Parameters:
simple_filter : str

Warnings filter action. Quoted from warnings:

Value Disposition
error Turn warnings into exceptions
ignore Ignore all warnings
always Always print warnings
default Print first occurrence of each warning type, for each location where warning is issued
module Print first occurrence of each warning type, for each module where warning is issued
once Print first occurrence of matching warnings, regardless of location

(source: warnings)

This decorator does NOT support the onceperfamily custom warning action.

Returns:
function

Decorator function

See also

warnings
Warnings module, especially sections on warnings filters
plastid.util.services.decorators.deprecated(func=None, version=None, instead=None)[source]

Deprecation annotation decorator for functions or classes. Wrapped functions or classes will raise FutureWarnings with called or instantiated, respectively.

Parameters:
func : function or class, optional

Function or class to deprecate. This is just a hack to main backward compatibility with non-keyword accepting versions of deprecated.

version : str, optional

If not None, version by which deprecated function or class will be removed

instead : str, optional

If not None, users will be told to use this function or class instead

Returns:
object

wrapped function or class

plastid.util.services.decorators.in_separate_process(func)[source]

Decorator that runs a function in a separate process, to force garbage collection collection upon termination of that process, limiting long-term memory usage.

Parameters:
func : function

Function to run in a separate process. Per multiprocessing spec, must be declared in global scope.

Returns:
function

wrapped function

See also

multiprocessing
Python multiprocessing module, for writing parallel programs
plastid.util.services.decorators.notimplemented(func)[source]

NotImplemented annotation decorator. Calls to functions annotated with this decorator raise NotImplementedError, which record attributes of function callers

Parameters:
func : function

Function to wrap

Returns:
function

wrapped function

plastid.util.services.decorators.notused(func)[source]

Notused annotation decorator. Only for marking code.

Parameters:
func : function

Function to wrap

Returns:
function

wrapped function

plastid.util.services.decorators.parallelize(func)[source]

Decorator to parallelize the running of a single-parameter function over multiple instances of its parameter(s)

Parameters:
func : function

Function to parallelize. Must take one parameter. Per multiprocessing spec, must be declared in global scope.

processes : int, optional

Number of processes to use (Default: 4)

Returns:
function

wrapped function

See also

multiprocessing
Python multiprocessing module, for writing parallel programs
plastid.util.services.decorators.skip_if_abstract(func)[source]

Decorator function to keep unittest from running methods (defined in abstract classes) that are only intended to be run when inherited by fully-fleshed out subclasses. Wrapped methods are actually called from all non-abstract subclasses that inherit the method.

Parameters:
func : function

Function that should only be run in a non-abstract subclass

Returns:
function

wrapped function

plastid.util.services.decorators.skipdoc(func_or_class)[source]

Instruct Sphinx not to generate documentation for func_or_class

Parameters:
func_or_class : function or class

Function or class not to document

Returns:
object

Wrapped function or class