param

Submodules

• param.__init__.pyc
• param.parameterized.pyc
• param.ipython
• param.ipython.pyc
• param._version
• param._version.pyc
• param.parameterized

Module

Parameters are a kind of class attribute allowing special behavior, including dynamically generated parameter values, documentation strings, constant and read-only parameters, and type or range checking at assignment time.

Potentially useful for any large Python program that needs user-modifiable object attributes; see the parameterized.Parameter and parameterized.Parameterized classes for more information.

This file contains subclasses of Parameter, implementing specific parameter types (e.g. Number).

param.Array

Parameter whose value is a numpy array.

param.Boolean

Binary or tristate Boolean Parameter.

param.Callable

Parameter holding a value that is a callable object, such as a function.

A keyword argument instantiate=True should be provided when a function object is used that might have state. On the other hand, regular standalone functions cannot be deepcopied as of Python 2.4, so instantiate must be False for those values.

param.ClassSelector

Parameter whose value is an instance of the specified class.

param.Composite

A Parameter that is a composite of a set of other attributes of the class.

The constructor argument ‘attribs’ takes a list of attribute names, which may or may not be Parameters. Getting the parameter returns a list of the values of the constituents of the composite, in the order specified. Likewise, setting the parameter takes a sequence of values and sets the value of the constituent attributes.

param.Dict

Parameter whose value is a dictionary.

param.Dynamic

Parameter whose value can be generated dynamically by a callable object.

If a Parameter is declared as Dynamic, it can be set a callable object (such as a function or callable class), and getting the parameter’s value will call that callable.

Note that at present, the callable object must allow attributes to be set on itself.

[Python 2.4 limitation: the callable object must be an instance of a callable class, rather than a named function or a lambda function, otherwise the object will not be picklable or deepcopyable.]

If set as time_dependent, setting the Dynamic.time_fn allows the production of dynamic values to be controlled: a new value will be produced only if the current value of time_fn is different from what it was the last time the parameter value was requested.

By default, the Dynamic parameters are not time_dependent so that new values are generated on every call regardless of the time. The default time_fn used when time_dependent is a single Time instance that allows general manipulations of time. It may be set to some other callable as required so long as a number is returned on each call.

param.Filename

Parameter that can be set to a string specifying the path of a file.

The string should be specified in UNIX style, but it will be returned in the format of the user’s operating system.

The specified path can be absolute, or relative to either:

• any of the paths specified in the search_paths attribute (if search_paths is not None);

or

• any of the paths searched by resolve_path() (if search_paths is None).

param.Foldername

Parameter that can be set to a string specifying the path of a folder.

The string should be specified in UNIX style, but it will be returned in the format of the user’s operating system.

The specified path can be absolute, or relative to either:

• any of the paths specified in the search_paths attribute (if search_paths is not None);

or

• any of the paths searched by resolve_dir_path() (if search_paths is None).

param.HookList

Parameter whose value is a list of callable objects.

This type of List Parameter is typically used to provide a place for users to register a set of commands to be called at a specified place in some sequence of processing steps.

class param.Infinity

Bases: object

An instance of this class represents an infinite value. Unlike Python’s float(‘inf’) value, this object can be safely compared with gmpy numeric types across different gmpy versions.

All operators on Infinity() return Infinity(), apart from the comparison and equality operators. Equality works by checking whether the two objects are both instances of this class.

param.Integer

Numeric Parameter required to be an Integer

param.List

Parameter whose value is a list of objects, usually of a specified type.

The bounds allow a minimum and/or maximum length of list to be enforced. If the class is non-None, all items in the list are checked to be of that type.

param.Magnitude

Numeric Parameter required to be in the range [0.0-1.0].

param.Number

A numeric Dynamic Parameter, with a default value and optional bounds.

There are two types of bounds: bounds and softbounds. bounds are hard bounds: the parameter must have a value within the specified range. The default bounds are (None,None), meaning there are actually no hard bounds. One or both bounds can be set by specifying a value (e.g. bounds=(None,10) means there is no lower bound, and an upper bound of 10). Bounds are inclusive by default, but exclusivity can be specified for each bound by setting inclusive_bounds (e.g. inclusive_bounds=(True,False) specifies an exclusive upper bound).

Number is also a type of Dynamic parameter, so its value can be set to a callable to get a dynamically generated number (see Dynamic).

When not being dynamically generated, bounds are checked when a Number is created or set. Using a default value outside the hard bounds, or one that is not numeric, results in an exception. When being dynamically generated, bounds are checked when a the value of a Number is requested. A generated value that is not numeric, or is outside the hard bounds, results in an exception.

As a special case, if allow_None=True (which is true by default if the parameter has a default of None when declared) then a value of None is also allowed.

A separate function set_in_bounds() is provided that will silently crop the given value into the legal range, for use in, for instance, a GUI.

softbounds are present to indicate the typical range of the parameter, but are not enforced. Setting the soft bounds allows, for instance, a GUI to know what values to display on sliders for the Number.

Example of creating a Number::

AB = Number(default=0.5, bounds=(None,10), softbounds=(0,1), doc=’Distance from A to B.’)

param.NumericTuple

A numeric tuple Parameter (e.g. (4.5,7.6,3)) with a fixed tuple length.

param.ObjectSelector

Parameter whose value must be one object from a list of possible objects.

check_on_set restricts the value to be among the current list of objects. By default, if objects are initially supplied, check_on_set is True, whereas if no objects are initially supplied, check_on_set is False. This can be overridden by explicitly specifying check_on_set initially.

If check_on_set is True (either because objects are supplied initially, or because it is explicitly specified), the default (initial) value must be among the list of objects (unless the default value is None).

param.Path

Parameter that can be set to a string specifying the path of a file or folder.

The string should be specified in UNIX style, but it will be returned in the format of the user’s operating system. Please use the Filename or Foldername classes if you require discrimination between the two possibilities.

The specified path can be absolute, or relative to either:

• any of the paths specified in the search_paths attribute (if search_paths is not None);

or

• any of the paths searched by resolve_path() (if search_paths is None).

param.Selector

Parameter whose value must be chosen from a list of possibilities.

Subclasses must implement get_range().

class param.Time(**params)

Bases: param.parameterized.Parameterized

A callable object returning a number for the current time.

Here ‘time’ is an abstract concept that can be interpreted in any useful way. For instance, in a simulation, it would be the current simulation time, while in a turn-taking game it could be the number of moves so far. The key intended usage is to allow independent Parameterized objects with Dynamic parameters to remain consistent with a global reference.

The time datatype (time_type) is configurable, but should typically be an exact numeric type like an integer or a rational, so that small floating-point errors do not accumulate as time is incremented repeatedly.

When used as a context manager using the ‘with’ statement (implemented by the __enter__ and __exit__ special methods), entry into a context pushes the state of the Time object, allowing the effect of changes to the time value to be explored by setting, incrementing or decrementing time as desired. This allows the state of time-dependent objects to be modified temporarily as a function of time, within the context’s block. For instance, you could use the context manager to “see into the future” to collect data over multiple times, without affecting the global time state once exiting the context. Of course, you need to be careful not to do anything while in context that would affect the lasting state of your other objects, if you want things to return to their starting state when exiting the context.

The starting time value of a new Time object is 0, converted to the chosen time type. Here is an illustration of how time can be manipulated using a Time object:

>>> time = Time(until=20, timestep=1)
>>> 'The initial time is %s' % time()
'The initial time is 0'
>>> 'Setting the time to %s' % time(5)
'Setting the time to 5'
>>> time += 5
>>> 'After incrementing by 5, the time is %s' % time()
'After incrementing by 5, the time is 10'
>>> with time as t:  # Entering a context
...     'Time before iteration: %s' % t()
...     'Iteration: %s' % [val for val in t]
...     'Time after iteration: %s' % t()
...     t += 2
...     'The until parameter may be exceeded outside iteration: %s' % t()
'Time before iteration: 10'
'Iteration: [10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]'
'Time after iteration: 20'
'The until parameter may be exceeded outside iteration: 22'
>>> 'After exiting the context the time is back to %s' % time()
'After exiting the context the time is back to 10'

param Parameter timestep (constant=False, default=1.0, instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Stepsize to be used with the iterator interface. Time can be advanced or decremented by any value, not just those corresponding to the stepsize, and so this value is only a default.

param Parameter until (constant=False, default=Infinity(), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)

Declaration of an expected end to time values, if any. When using the iterator interface, iteration will end before this value is exceeded.

param Parameter time_type (constant=True, default=<type ‘int’>, instantiate=True, pickle_default_value=True, precedence=None, readonly=False)

Callable that Time will use to convert user-specified time values into the current time; all times will be of the resulting numeric type. By default, time is of integer type, but you can supply any arbitrary-precision type like a fixed-point decimal or a rational, to allow fractional times. Floating-point times are also allowed, but are not recommended because they will suffer from accumulated rounding errors. For instance, incrementing a floating-point value 0.0 by 0.05, 20 times, will not reach 1.0 exactly. Instead, it will be slightly higher than 1.0, because 0.05 cannot be represented exactly in a standard floating point numeric type. Fixed-point or rational types should be able to handle such computations exactly, avoiding accumulation issues over long time intervals. Some potentially useful exact number classes:: - int: Suitable if all times can be expressed as integers. - Python’s decimal.Decimal and fractions.Fraction classes: widely available but slow and also awkward to specify times (e.g. cannot simply type 0.05, but have to use a special constructor or a string). - fixedpoint.FixedPoint: Allows a natural representation of times in decimal notation, but very slow and needs to be installed separately. - gmpy.mpq: Allows a natural representation of times in decimal notation, and very fast because it uses the GNU Multi-Precision library, but needs to be installed separately and depends on a non-Python library. gmpy.mpq is gmpy’s rational type.

time_type

alias of int

param.XYCoordinates

A NumericTuple for an X,Y coordinate.

param.concrete_descendents(parentclass)

Return a dictionary containing all subclasses of the specified parentclass, including the parentclass. Only classes that are defined in scripts that have been run or modules that have been imported are included, so the caller will usually first do from package import *.

Only non-abstract classes will be included.

param.main = Parameterized(name='main')

Top-level object to allow messaging not tied to a particular Parameterized object, as in ‘param.main.warning(“Invalid option”)’.

class param.normalize_path(**params)

Bases: param.parameterized.ParameterizedFunction

Convert a UNIX-style path to the current OS’s format, typically for creating a new file or directory.

If the path is not already absolute, it will be made absolute (using the prefix parameter).

Should do the same as Python’s os.path.abspath(), except using prefix rather than os.getcwd).

param String prefix (allow_None=False, constant=False, default=/var/lib/buildbot/slaves/docs/build/doc, instantiate=False, pickle_default_value=False, precedence=None, readonly=False)

Prepended to the specified path, if that path is not absolute.

param.produce_value(value_obj)

A helper function that produces an actual parameter from a stored object: if the object is callable, call it, otherwise return the object.

class param.resolve_path(**params)

Bases: param.parameterized.ParameterizedFunction

Find the path to an existing file, searching the paths specified in the search_paths parameter if the filename is not absolute, and converting a UNIX-style path to the current OS’s format if necessary.

To turn a supplied relative path into an absolute one, the path is appended to paths in the search_paths parameter, in order, until the file is found.

An IOError is raised if the file is not found.

Similar to Python’s os.path.abspath(), except more search paths than just os.getcwd() can be used, and the file must exist.

param Boolean path_to_file (allow_None=False, bounds=(0, 1), constant=False, default=True, instantiate=False, pickle_default_value=False, precedence=None, readonly=False)

String specifying whether the path refers to a ‘File’ or a ‘Folder’.

param List search_paths (bounds=(0, None), constant=False, default=[‘/var/lib/buildbot/slaves/docs/build/doc’], instantiate=True, pickle_default_value=False, precedence=None, readonly=False)

Prepended to a non-relative path, in order, until a file is found.