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:

@defaults('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 implementer 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

class pymor.core.defaults.DefaultContainer

Internal singleton class holding all default values defined in pyMOR.

Not to be used directly.

Methods

get
import_all
keys
update

get(key)

import_all()

keys()

update(defaults, type='user')

pymor.core.defaults.defaults(*args)

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 via load_defaults_from_file or set_defaults in case no value has been provided by the caller of the function. Moreover, if None 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 using set_defaults or load_defaults_from_file, the default value provided in the function signature is used.

If the argument arg of function f in sub-module m of package p is marked as a default value, its value will be changeable by the aforementioned methods under the path p.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.defaults_changes()

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 via set_defaults or load_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 of defaults.

Warning

Note that when using parallelization, workers might set different defaults at the same time, resulting in equal change counts but different states of defaults at each worker.

pymor.core.defaults.get_defaults(user=True, file=True, code=True)

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 with set_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.load_defaults_from_file(filename='./pymor_defaults.py')

Loads default values defined in configuration file.

Suitable configuration files can be created via write_defaults_to_file. The file is loaded via Python’s exec 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.print_defaults(import_all=True, shorten_paths=0)

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 via set_defaults, default values set in the function signature can only be printed after the modules containing these functions have been imported. If import_all is set to True, 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.set_defaults(defaults)

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 via load_defaults_from_file or previous set_defaults calls.

Parameters

defaults

Dictionary of default values. Keys are the full paths of the default values (see defaults).

pymor.core.defaults.write_defaults_to_file(filename='./pymor_defaults.py', packages=('pymor',))

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.