pymor.core.defaults
¶
This module contains pyMOR’s facilities for handling default values.
A default value in pyMOR is always the default value of some
function argument. To mark the value of an optional function argument
as a user-modifiable default value use the defaults
decorator.
As an additional feature, if None
is passed for such an argument,
its default value is used instead of None
. This is useful
for writing code of the following form:
@default('option')
def algorithm(U, option=42):
...
def method_called_by_user(V, option_for_algorithm=None):
...
algorithm(U, option=option_for_algorithm)
...
If the user does not provide option_for_algorithm
to
method_called_by_user
, the default 42
is automatically chosen
without the implementor of method_called_by_user
having to care
about this.
The user interface for handling default values in pyMOR is provided
by set_defaults
, load_defaults_from_file
,
write_defaults_to_file
and print_defaults
.
If pyMOR is imported, it will automatically search for a configuration
file named pymor_defaults.py
in the current working directory.
If found, the file is loaded via load_defaults_from_file
.
However, as a security precaution, the file will only be loaded if it is
owned by the user running the Python interpreter
(load_defaults_from_file
uses exec
to load the configuration).
As an alternative, the environment variable PYMOR_DEFAULTS
can be
used to specify the path of a configuration file. If empty or set to
NONE
, no configuration file will be loaded whatsoever.
Warning
Note that changing defaults may affect the result of a (cached)
function call. pyMOR will emit a warning, when a result is retrieved
from the cache that has been computed using an earlier set of
defaults
(see defaults_changes
).
Module Contents¶
Classes¶
Internal singleton class holding all default values defined in pyMOR. |
Functions¶
Function decorator for marking function arguments as user-configurable defaults. |
|
Print all |
|
Write the currently set |
|
Loads |
|
Set |
|
Get |
|
Returns the number of changes made to to pyMOR's global |
- class pymor.core.defaults.DefaultContainer[source]¶
Internal singleton class holding all default values defined in pyMOR.
Not to be used directly.
- pymor.core.defaults.defaults(*args)[source]¶
Function decorator for marking function arguments as user-configurable defaults.
If a function decorated with
defaults
is called, the values of the marked default parameters are set to the values defined viaload_defaults_from_file
orset_defaults
in case no value has been provided by the caller of the function. Moreover, ifNone
is passed as a value for a default argument, the argument is set to its default value, as well. If no value has been specified usingset_defaults
orload_defaults_from_file
, the default value provided in the function signature is used.If the argument
arg
of functionf
in sub-modulem
of packagep
is marked as a default value, its value will be changeable by the aforementioned methods under the pathp.m.f.arg
.Note that the
defaults
decorator can also be used in user code.Parameters
- args
List of strings containing the names of the arguments of the decorated function to mark as pyMOR defaults. Each of these arguments has to be a keyword argument (with a default value).
- pymor.core.defaults.print_defaults(import_all=True, shorten_paths=2)[source]¶
Print all
default
values set in pyMOR.Parameters
- import_all
While
print_defaults
will always print all defaults defined in loaded configuration files or set viaset_defaults
, default values set in the function signature can only be printed after the modules containing these functions have been imported. Ifimport_all
is set toTrue
,print_defaults
will therefore first import all of pyMOR’s modules, to provide a complete lists of defaults.- shorten_paths
Shorten the paths of all default values by
shorten_paths
components. The last two path components will always be printed.
- pymor.core.defaults.write_defaults_to_file(filename='./pymor_defaults.py', packages=('pymor',))[source]¶
Write the currently set
default
values to a configuration file.The resulting file is an ordinary Python script and can be modified by the user at will. It can be loaded in a later session using
load_defaults_from_file
.Parameters
- filename
Name of the file to write to.
- packages
List of package names. To discover all default values that have been defined using the
defaults
decorator,write_defaults_to_file
will recursively import all sub-modules of the named packages before creating the configuration file.
- pymor.core.defaults.load_defaults_from_file(filename='./pymor_defaults.py')[source]¶
Loads
default
values defined in configuration file.Suitable configuration files can be created via
write_defaults_to_file
. The file is loaded via Python’sexec
function, so be very careful with configuration files you have not created your own. You have been warned!Parameters
- filename
Path of the configuration file.
- pymor.core.defaults.set_defaults(defaults)[source]¶
Set
default
values.This method sets the default value of function arguments marked via the
defaults
decorator, overriding default values specified in the function signature or set earlier viaload_defaults_from_file
or previousset_defaults
calls.Parameters
- defaults
Dictionary of default values. Keys are the full paths of the default values (see
defaults
).
- pymor.core.defaults.get_defaults(user=True, file=True, code=True)[source]¶
Get
default
values.Returns all
default
values as a dict. The parameters can be set to filter by type.Parameters
- user
If
True
, returned dict contains defaults that have been set by the user withset_defaults
.- file
If
True
, returned dict contains defaults that have been loaded from file.- code
If
True
, returned dict contains unmodified default values.
- pymor.core.defaults.defaults_changes()[source]¶
Returns the number of changes made to to pyMOR’s global
defaults
.This methods returns the number of changes made to the state of pyMOR’s global
defaults
viaset_defaults
orload_defaults_from_file
since the start of program execution.Since changing
defaults
may affect the result of a (cached) function call, this value is used to warn when a result is retrieved from the cache that has been computed using an earlier set ofdefaults
.Warning
Note that when using
parallelization
, workers might set different defaults at the same time, resulting in equal change counts but different states ofdefaults
at each worker.