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 abstractunittest.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
- buffile
Buffer that will hold captured stderr output. Must import
write()
andfileno()
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
- buffile or None
Buffer that will hold captured stdout output. Must import
write()
andfileno()
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_filterstr
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
- funcfunction or class, optional
Function or class to deprecate. This is just a hack to main backward compatibility with non-keyword accepting versions of deprecated.
- versionstr, optional
If not None, version by which deprecated function or class will be removed
- insteadstr, 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
- funcfunction
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
- funcfunction
Function to wrap
- Returns
- function
wrapped function
- plastid.util.services.decorators.notused(func)[source]¶
Notused annotation decorator. Only for marking code.
- Parameters
- funcfunction
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
- funcfunction
Function to parallelize. Must take one parameter. Per multiprocessing spec, must be declared in global scope.
- processesint, 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
- funcfunction
Function that should only be run in a non-abstract subclass
- Returns
- function
wrapped function