param.param Package


param Package

Inheritance diagram of param.__init__

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 Parameter and Parameterized classes for more information. If you do not want to add a dependency on external code by importing from a separately installed param package, you can simply save this file as param.py and copy it and parameterized.py directly into your own package.

This file contains subclasses of Parameter, implementing specific parameter types (e.g. Number), and also imports the definition of Parameters and Parameterized classes.

class param.__init__. Action ( default=None , doc=None , precedence=None , instantiate=False , constant=False , readonly=False , pickle_default_value=True , allow_None=False ) [source]

Bases: param.__init__.Callable

A user-provided function that can be invoked like a class or object method using (). In a GUI, this might be mapped to a button, but it can be invoked directly as well.

class param.__init__. Array ( default=None , **params ) [source]

Bases: param.__init__.ClassSelector

Parameter whose value is a numpy array.

get_range ( )

Return the possible types for this parameter’s value.

(I.e. return {name: <class>} for all classes that are concrete_descendents() of self.class_ .)

Only classes from modules that have been imported are added (see concrete_descendents()).

class param.__init__. Boolean ( default=False , bounds=(0 , 1) , **params ) [source]

Bases: param.parameterized.Parameter

Binary or tristate Boolean Parameter.

class param.__init__. Callable ( default=None , doc=None , precedence=None , instantiate=False , constant=False , readonly=False , pickle_default_value=True , allow_None=False ) [source]

Bases: param.parameterized.Parameter

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.

class param.__init__. ClassSelector ( class_ , default=None , instantiate=True , is_instance=True , **params ) [source]

Bases: param.__init__.Selector

Parameter whose value is a specified class or an instance of that class. By default, requires an instance, but if is_instance=False, accepts a class instead. Both class and instance values respect the instantiate slot, though it matters only for is_instance=True.

get_range ( ) [source]

Return the possible types for this parameter’s value.

(I.e. return {name: <class>} for all classes that are concrete_descendents() of self.class_ .)

Only classes from modules that have been imported are added (see concrete_descendents()).

class param.__init__. Color ( default=None , allow_None=False , **kwargs ) [source]

Bases: param.parameterized.Parameter

Color parameter defined as a hex RGB string with an optional # prefix.

class param.__init__. Composite ( attribs=None , **kw ) [source]

Bases: param.parameterized.Parameter

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.

class param.__init__. DataFrame ( default=None , rows=None , columns=None , ordered=None , **params ) [source]

Bases: param.__init__.ClassSelector

Parameter whose value is a pandas DataFrame.

The structure of the DataFrame can be constrained by the rows and columns arguments:

rows: If specified, may be a number or an integer bounds tuple to constrain the allowable number of rows.

columns: If specified, may be a number, an integer bounds tuple, a list or a set. If the argument is numeric, constrains the number of columns using the same semantics as used for rows. If either a list or set of strings, the column names will be validated. If a set is used, the supplied DataFrame must contain the specified columns and if a list is given, the supplied DataFrame must contain exactly the same columns and in the same order and no other columns.

get_range ( )

Return the possible types for this parameter’s value.

(I.e. return {name: <class>} for all classes that are concrete_descendents() of self.class_ .)

Only classes from modules that have been imported are added (see concrete_descendents()).

class param.__init__. Date ( default=None , **kwargs ) [source]

Bases: param.__init__.Number

Date parameter of datetime type.

crop_to_bounds ( val )

Return the given value cropped to be within the hard bounds for this parameter.

If a numeric value is passed in, check it is within the hard bounds. If it is larger than the high bound, return the high bound. If it’s smaller, return the low bound. In either case, the returned value could be None. If a non-numeric value is passed in, set to be the default value (which could be None). In no case is an exception raised; all values are accepted.

get_soft_bounds ( )

For each soft bound (upper and lower), if there is a defined bound (not equal to None) then it is returned, otherwise it defaults to the hard bound. The hard bound could still be None.

set_in_bounds ( obj , val )

Set to the given value, but cropped to be within the legal bounds. All objects are accepted, and no exceptions will be raised. See crop_to_bounds for details on how cropping is done.

class param.__init__. DateRange ( default=None , bounds=None , softbounds=None , inclusive_bounds=(True , True) , **params ) [source]

Bases: param.__init__.Range

A date range specified as (start_date, end_date).

Dates must be specified as datetime-like types (see param.dt_types).

get_soft_bounds ( )

For each soft bound (upper and lower), if there is a defined bound (not equal to None) then it is returned, otherwise it defaults to the hard bound. The hard bound could still be None.

class param.__init__. Dict ( default=None , **params ) [source]

Bases: param.__init__.ClassSelector

Parameter whose value is a dictionary.

get_range ( )

Return the possible types for this parameter’s value.

(I.e. return {name: <class>} for all classes that are concrete_descendents() of self.class_ .)

Only classes from modules that have been imported are added (see concrete_descendents()).

class param.__init__. Dynamic ( **params ) [source]

Bases: param.parameterized.Parameter

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.

class param.__init__. FileSelector ( default=None , path='' , **kwargs ) [source]

Bases: param.__init__.ObjectSelector

Given a path glob, allows one file to be selected from those matching.

compute_default ( )

If this parameter’s compute_default_fn is callable, call it and store the result in self.default.

Also removes None from the list of objects (if the default is no longer None).

get_range ( ) [source]

Return the possible objects to which this parameter could be set.

(Returns the dictionary {object.name:object}.)

class param.__init__. Filename ( default=None , search_paths=None , **params ) [source]

Bases: param.__init__.Path

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).
class param.__init__. Foldername ( default=None , search_paths=None , **params ) [source]

Bases: param.__init__.Path

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).
class param.__init__. HookList ( default=[] , class_=None , instantiate=True , bounds=(0 , None) , **params ) [source]

Bases: param.__init__.List

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.__init__. Infinity [source]

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.

class param.__init__. Integer ( default=0 , **params ) [source]

Bases: param.__init__.Number

Numeric Parameter required to be an Integer

crop_to_bounds ( val )

Return the given value cropped to be within the hard bounds for this parameter.

If a numeric value is passed in, check it is within the hard bounds. If it is larger than the high bound, return the high bound. If it’s smaller, return the low bound. In either case, the returned value could be None. If a non-numeric value is passed in, set to be the default value (which could be None). In no case is an exception raised; all values are accepted.

get_soft_bounds ( )

For each soft bound (upper and lower), if there is a defined bound (not equal to None) then it is returned, otherwise it defaults to the hard bound. The hard bound could still be None.

set_in_bounds ( obj , val )

Set to the given value, but cropped to be within the legal bounds. All objects are accepted, and no exceptions will be raised. See crop_to_bounds for details on how cropping is done.

class param.__init__. List ( default=[] , class_=None , instantiate=True , bounds=(0 , None) , **params ) [source]

Bases: param.parameterized.Parameter

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.

class param.__init__. ListSelector ( default=None , objects=None , instantiate=False , compute_default_fn=None , check_on_set=None , allow_None=None , **params ) [source]

Bases: param.__init__.ObjectSelector

Variant of ObjectSelector where the value can be multiple objects from a list of possible objects.

compute_default ( ) [source]

If this parameter’s compute_default_fn is callable, call it and store the result in self.default.

Also removes None from the list of objects (if the default is no longer None).

get_range ( )

Return the possible objects to which this parameter could be set.

(Returns the dictionary {object.name:object}.)

class param.__init__. Magnitude ( default=1.0 , softbounds=None , **params ) [source]

Bases: param.__init__.Number

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

crop_to_bounds ( val )

Return the given value cropped to be within the hard bounds for this parameter.

If a numeric value is passed in, check it is within the hard bounds. If it is larger than the high bound, return the high bound. If it’s smaller, return the low bound. In either case, the returned value could be None. If a non-numeric value is passed in, set to be the default value (which could be None). In no case is an exception raised; all values are accepted.

get_soft_bounds ( )

For each soft bound (upper and lower), if there is a defined bound (not equal to None) then it is returned, otherwise it defaults to the hard bound. The hard bound could still be None.

set_in_bounds ( obj , val )

Set to the given value, but cropped to be within the legal bounds. All objects are accepted, and no exceptions will be raised. See crop_to_bounds for details on how cropping is done.

class param.__init__. MultiFileSelector ( default=None , path='' , **kwargs ) [source]

Bases: param.__init__.ListSelector

Given a path glob, allows multiple files to be selected from the list of matches.

compute_default ( )

If this parameter’s compute_default_fn is callable, call it and store the result in self.default.

Also removes None from the list of objects (if the default is no longer None).

get_range ( ) [source]

Return the possible objects to which this parameter could be set.

(Returns the dictionary {object.name:object}.)

class param.__init__. Number ( default=0.0 , bounds=None , softbounds=None , inclusive_bounds=(True , True) , **params ) [source]

Bases: param.__init__.Dynamic

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 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.')
crop_to_bounds ( val ) [source]

Return the given value cropped to be within the hard bounds for this parameter.

If a numeric value is passed in, check it is within the hard bounds. If it is larger than the high bound, return the high bound. If it’s smaller, return the low bound. In either case, the returned value could be None. If a non-numeric value is passed in, set to be the default value (which could be None). In no case is an exception raised; all values are accepted.

get_soft_bounds ( ) [source]

For each soft bound (upper and lower), if there is a defined bound (not equal to None) then it is returned, otherwise it defaults to the hard bound. The hard bound could still be None.

set_in_bounds ( obj , val ) [source]

Set to the given value, but cropped to be within the legal bounds. All objects are accepted, and no exceptions will be raised. See crop_to_bounds for details on how cropping is done.

class param.__init__. NumericTuple ( default=(0 , 0) , length=None , **params ) [source]

Bases: param.__init__.Tuple

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

class param.__init__. ObjectSelector ( default=None , objects=None , instantiate=False , compute_default_fn=None , check_on_set=None , allow_None=None , **params ) [source]

Bases: param.__init__.Selector

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).

The list of objects can be supplied as a list (appropriate for selecting among a set of strings, or among a set of objects with a “name” parameter), or as a (preferably ordered) dictionary from names to objects. If a dictionary is supplied, the objects will need to be hashable so that their names can be looked up from the object value.

compute_default ( ) [source]

If this parameter’s compute_default_fn is callable, call it and store the result in self.default.

Also removes None from the list of objects (if the default is no longer None).

get_range ( ) [source]

Return the possible objects to which this parameter could be set.

(Returns the dictionary {object.name:object}.)

class param.__init__. Path ( default=None , search_paths=None , **params ) [source]

Bases: param.parameterized.Parameter

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).
class param.__init__. Range ( default=None , bounds=None , softbounds=None , inclusive_bounds=(True , True) , **params ) [source]

Bases: param.__init__.NumericTuple

A numeric range with optional bounds and softbounds

get_soft_bounds ( ) [source]

For each soft bound (upper and lower), if there is a defined bound (not equal to None) then it is returned, otherwise it defaults to the hard bound. The hard bound could still be None.

class param.__init__. Selector ( default=None , doc=None , precedence=None , instantiate=False , constant=False , readonly=False , pickle_default_value=True , allow_None=False ) [source]

Bases: param.parameterized.Parameter

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

Subclasses must implement get_range().

class param.__init__. Series ( default=None , rows=None , **params ) [source]

Bases: param.__init__.ClassSelector

Parameter whose value is a pandas Series.

The structure of the Series can be constrained by the rows argument which may be a number or an integer bounds tuple to constrain the allowable number of rows.

get_range ( )

Return the possible types for this parameter’s value.

(I.e. return {name: <class>} for all classes that are concrete_descendents() of self.class_ .)

Only classes from modules that have been imported are added (see concrete_descendents()).

class param.__init__. Time ( **params ) [source]

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 String label ( allow_None=False, basestring=<class ‘str’>, constant=False, default=Time, instantiate=False, pickle_default_value=True, precedence=None, readonly=False, regex=None, watchers={} )
The label given to the Time object. Can be used to convey more specific notions of time as appropriate. For instance, the label could be ‘Simulation Time’ or ‘Duration’.
param Parameter time_type ( allow_None=False, constant=True, default=<class ‘int’>, instantiate=True, pickle_default_value=True, precedence=None, readonly=False, watchers={} )
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.
param Parameter timestep ( allow_None=False, constant=False, default=1.0, instantiate=False, pickle_default_value=True, precedence=None, readonly=False, watchers={} )
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 ( allow_None=False, constant=False, default=Infinity(), instantiate=False, pickle_default_value=True, precedence=None, readonly=False, watchers={} )
Declaration of an expected end to time values, if any. When using the iterator interface, iteration will end before this value is exceeded.
param String unit ( allow_None=True, basestring=<class ‘str’>, constant=False, default=None, instantiate=False, pickle_default_value=True, precedence=None, readonly=False, regex=None, watchers={} )
The units of the time dimensions. The default of None is set as the global time function may on an arbitrary time base. Typical values for the parameter are ‘seconds’ (the SI unit for time) or subdivisions thereof (e.g. ‘milliseconds’).
debug ( **kwargs )

Inspect .param.debug method for the full docstring

defaults ( **kwargs )

Inspect .param.defaults method for the full docstring

force_new_dynamic_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.Time'>)
get_param_values = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.Time'>)
get_value_generator = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.Time'>)
inspect_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.Time'>)
message ( **kwargs )

Inspect .param.message method for the full docstring

classmethod params ( *args , **kwargs )

Inspect .param.params method for the full docstring

pprint ( imports=None , prefix=' ' , unknown_value='<?>' , qualify=False , separator='' )

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults ( *args , **kwargs )

Inspect .param.print_param_defaults method for the full docstring

print_param_values ( **kwargs )

Inspect .param.print_param_values method for the full docstring

script_repr ( imports=[] , prefix=' ' )

Variant of __repr__ designed for generating a runnable script.

classmethod set_default ( *args , **kwargs )

Inspect .param.set_default method for the full docstring

set_dynamic_time_fn = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.Time'>)
set_param = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.Time'>)
state_pop ( )

Restore the most recently saved state.

See state_push() for more details.

state_push ( )

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

time_type

alias of builtins.int

verbose ( **kwargs )

Inspect .param.verbose method for the full docstring

warning ( **kwargs )

Inspect .param.warning method for the full docstring

class param.__init__. Tuple ( default=(0 , 0) , length=None , **params ) [source]

Bases: param.parameterized.Parameter

A tuple Parameter (e.g. (‘a’,7.6,[3,5])) with a fixed tuple length.

class param.__init__. XYCoordinates ( default=(0.0 , 0.0) , **params ) [source]

Bases: param.__init__.NumericTuple

A NumericTuple for an X,Y coordinate.

param.__init__. abbreviate_paths ( pathspec , named_paths ) [source]

Given a dict of (pathname,path) pairs, removes any prefix shared by all pathnames. Helps keep menu items short yet unambiguous.

param.__init__. as_unicode ( obj ) [source]

Safely casts any object to unicode including regular string (i.e. bytes) types in python 2.

param.__init__. concrete_descendents ( parentclass ) [source]

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.__init__. hashable ( x ) [source]

Return a hashable version of the given object x, with lists and dictionaries converted to tuples. Allows mutable objects to be used as a lookup key in cases where the object has not actually been mutated. Lookup will fail (appropriately) in cases where some part of the object has changed. Does not (currently) recursively replace mutable subobjects.

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

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

param.__init__. named_objs ( objlist , namesdict=None ) [source]

Given a list of objects, returns a dictionary mapping from string name for the object to the object itself. Accepts an optional name,obj dictionary, which will override any other name if that item is present in the dictionary.

class param.__init__. normalize_path ( **params ) [source]

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, basestring=<class ‘str’>, constant=False, default=/home/travis/build/ioam/param, instantiate=False, pickle_default_value=False, precedence=None, readonly=False, regex=None, watchers={} )
Prepended to the specified path, if that path is not absolute.
debug ( **kwargs )

Inspect .param.debug method for the full docstring

defaults ( **kwargs )

Inspect .param.defaults method for the full docstring

force_new_dynamic_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.normalize_path'>)
get_param_values = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.normalize_path'>)
get_value_generator = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.normalize_path'>)
inspect_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.normalize_path'>)
instance = functools.partial(<function ParameterizedFunction.instance>, <class 'param.__init__.normalize_path'>)
message ( **kwargs )

Inspect .param.message method for the full docstring

classmethod params ( *args , **kwargs )

Inspect .param.params method for the full docstring

pprint ( imports=None , prefix='\n ' , unknown_value='<?>' , qualify=False , separator='' )

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults ( *args , **kwargs )

Inspect .param.print_param_defaults method for the full docstring

print_param_values ( **kwargs )

Inspect .param.print_param_values method for the full docstring

script_repr ( imports=[] , prefix=' ' )

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default ( *args , **kwargs )

Inspect .param.set_default method for the full docstring

set_dynamic_time_fn = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.normalize_path'>)
set_param = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.normalize_path'>)
state_pop ( )

Restore the most recently saved state.

See state_push() for more details.

state_push ( )

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose ( **kwargs )

Inspect .param.verbose method for the full docstring

warning ( **kwargs )

Inspect .param.warning method for the full docstring

param.__init__. param_union ( *parameterizeds , **kwargs ) [source]

Given a set of Parameterized objects, returns a dictionary with the union of all param name,value pairs across them. If warn is True (default), warns if the same parameter has been given multiple values; otherwise uses the last value

param.__init__. produce_value ( value_obj ) [source]

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.__init__. resolve_path ( **params ) [source]

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 List search_paths ( allow_None=False, bounds=(0, None), constant=False, default=[‘/home/travis/build/ioam/param’], instantiate=True, pickle_default_value=False, precedence=None, readonly=False, watchers={} )
Prepended to a non-relative path, in order, until a file is found.
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, watchers={} )
String specifying whether the path refers to a ‘File’ or a ‘Folder’.
debug ( **kwargs )

Inspect .param.debug method for the full docstring

defaults ( **kwargs )

Inspect .param.defaults method for the full docstring

force_new_dynamic_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.resolve_path'>)
get_param_values = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.resolve_path'>)
get_value_generator = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.resolve_path'>)
inspect_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.resolve_path'>)
instance = functools.partial(<function ParameterizedFunction.instance>, <class 'param.__init__.resolve_path'>)
message ( **kwargs )

Inspect .param.message method for the full docstring

classmethod params ( *args , **kwargs )

Inspect .param.params method for the full docstring

pprint ( imports=None , prefix='\n ' , unknown_value='<?>' , qualify=False , separator='' )

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults ( *args , **kwargs )

Inspect .param.print_param_defaults method for the full docstring

print_param_values ( **kwargs )

Inspect .param.print_param_values method for the full docstring

script_repr ( imports=[] , prefix=' ' )

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default ( *args , **kwargs )

Inspect .param.set_default method for the full docstring

set_dynamic_time_fn = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.resolve_path'>)
set_param = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.__init__.resolve_path'>)
state_pop ( )

Restore the most recently saved state.

See state_push() for more details.

state_push ( )

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose ( **kwargs )

Inspect .param.verbose method for the full docstring

warning ( **kwargs )

Inspect .param.warning method for the full docstring


ipython Module

Inheritance diagram of param.ipython

Optional IPython extension for working with Parameters.

This extension offers extended but completely optional functionality for IPython users. From within IPython, it may be loaded using:

%load_ext param.ipython

This will register the %params line magic to allow easy inspection of all the parameters defined on a parameterized class or object:

%params <parameterized class or object>

All parameters of the class or object will be listed in the IPython pager together with all their corresponding attributes and docstrings. Note that the class or object to be inspected must already exist in the active namespace.

class param.ipython. ParamPager ( metaclass=False ) [source]

Bases: object

Callable class that displays information about the supplied Parameterized object or class in the IPython pager.

get_param_info ( obj , include_super=True ) [source]

Get the parameter dictionary, the list of modifed parameters and the dictionary or parameter values. If include_super is True, parameters are also collected from the super classes.

param_docstrings ( info , max_col_len=100 , only_changed=False ) [source]

Build a string to that presents all of the parameter docstrings in a clean format (alternating red and blue for readability).


parameterized Module

Inheritance diagram of param.parameterized

Generic support for objects with full-featured Parameters and messaging.

class param.parameterized. Comparator [source]

Bases: object

Comparator defines methods for determining whether two objects should be considered equal. It works by registering custom comparison functions, which may either be registed by type or with a predicate function. If no matching comparison can be found for the two objects the comparison will return False.

If registered by type the Comparator will check whether both objects are of that type and apply the comparison. If the equality function is instead registered with a function it will call the function with each object individually to check if the comparison applies. This is useful for defining comparisons for objects without explicitly importing them.

To use the Comparator simply call the is_equal function.

class param.parameterized. Event ( what , name , obj , cls , old , new , type )

Bases: tuple

cls

Alias for field number 3

count ( value ) → integer -- return number of occurrences of value
index ( value [ , start [ , stop ] ] ) → integer -- return first index of value.

Raises ValueError if the value is not present.

name

Alias for field number 1

new

Alias for field number 5

obj

Alias for field number 2

old

Alias for field number 4

type

Alias for field number 6

what

Alias for field number 0

class param.parameterized. MInfo ( inst , cls , name , method )

Bases: tuple

cls

Alias for field number 1

count ( value ) → integer -- return number of occurrences of value
index ( value [ , start [ , stop ] ] ) → integer -- return first index of value.

Raises ValueError if the value is not present.

inst

Alias for field number 0

method

Alias for field number 3

name

Alias for field number 2

class param.parameterized. PInfo ( inst , cls , name , pobj , what )

Bases: tuple

cls

Alias for field number 1

count ( value ) → integer -- return number of occurrences of value
index ( value [ , start [ , stop ] ] ) → integer -- return first index of value.

Raises ValueError if the value is not present.

inst

Alias for field number 0

name

Alias for field number 2

pobj

Alias for field number 3

what

Alias for field number 4

class param.parameterized. ParamOverrides ( overridden , dict_ , allow_extra_keywords=False ) [source]

Bases: dict

A dictionary that returns the attribute of a specified object if that attribute is not present in itself.

Used to override the parameters of an object.

clear ( ) → None. Remove all items from D.
copy ( ) → a shallow copy of D
extra_keywords ( ) [source]

Return a dictionary containing items from the originally supplied dict_ whose names are not parameters of the overridden object.

fromkeys ( )

Returns a new dict with keys from iterable and values equal to value.

get ( k [ , d ] ) → D[k] if k in D, else d. d defaults to None. [source]
items ( ) → a set-like object providing a view on D's items
keys ( ) → a set-like object providing a view on D's keys
param_keywords ( ) [source]

Return a dictionary containing items from the originally supplied dict_ whose names are parameters of the overridden object (i.e. not extra keywords/parameters).

pop ( k [ , d ] ) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem ( ) → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault ( k [ , d ] ) → D.get(k,d), also set D[k]=d if k not in D
update ( [ E , ] **F ) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values ( ) → an object providing a view on D's values
class param.parameterized. Parameter ( default=None , doc=None , precedence=None , instantiate=False , constant=False , readonly=False , pickle_default_value=True , allow_None=False ) [source]

Bases: object

An attribute descriptor for declaring parameters.

Parameters are a special kind of class attribute. Setting a Parameterized class attribute to be a Parameter instance causes that attribute of the class (and the class’s instances) to be treated as a Parameter. This allows special behavior, including dynamically generated parameter values, documentation strings, constant and read-only parameters, and type or range checking at assignment time.

For example, suppose someone wants to define two new kinds of objects Foo and Bar, such that Bar has a parameter delta, Foo is a subclass of Bar, and Foo has parameters alpha, sigma, and gamma (and delta inherited from Bar). She would begin her class definitions with something like this:

class Bar(Parameterized):
delta = Parameter(default=0.6, doc=’The difference between steps.’) …
class Foo(Bar):

alpha = Parameter(default=0.1, doc=’The starting value.’) sigma = Parameter(default=0.5, doc=’The standard deviation.’,

constant=True)

gamma = Parameter(default=1.0, doc=’The ending value.’) …

Class Foo would then have four parameters, with delta defaulting to 0.6.

Parameters have several advantages over plain attributes:

  1. Parameters can be set automatically when an instance is constructed: The default constructor for Foo (and Bar) will accept arbitrary keyword arguments, each of which can be used to specify the value of a Parameter of Foo (or any of Foo’s superclasses). E.g., if a script does this:

    myfoo = Foo(alpha=0.5)

    myfoo.alpha will return 0.5, without the Foo constructor needing special code to set alpha.

    If Foo implements its own constructor, keyword arguments will still be accepted if the constructor accepts a dictionary of keyword arguments (as in def __init__(self,**params): ), and then each class calls its superclass (as in super(Foo,self).__init__(**params) ) so that the Parameterized constructor will process the keywords.

  2. A Parameterized class need specify only the attributes of a Parameter whose values differ from those declared in superclasses; the other values will be inherited. E.g. if Foo declares

    delta = Parameter(default=0.2)

    the default value of 0.2 will override the 0.6 inherited from Bar, but the doc will be inherited from Bar.

  3. The Parameter descriptor class can be subclassed to provide more complex behavior, allowing special types of parameters that, for example, require their values to be numbers in certain ranges, generate their values dynamically from a random distribution, or read their values from a file or other external source.

  4. The attributes associated with Parameters provide enough information for automatically generating property sheets in graphical user interfaces, allowing Parameterized instances to be edited by users.

Note that Parameters can only be used when set as class attributes of Parameterized classes. Parameters used as standalone objects, or as class attributes of non-Parameterized classes, will not have the behavior described here.

class param.parameterized. ParameterMetaclass [source]

Bases: type

Metaclass allowing control over creation of Parameter classes.

mro ( ) → list

return a type’s method resolution order

class param.parameterized. Parameterized ( **params ) [source]

Bases: object

params(name=String)

Base class for named objects that support Parameters and message formatting.

Automatic object naming: Every Parameterized instance has a name parameter. If the user doesn’t designate a name=<str> argument when constructing the object, the object will be given a name consisting of its class name followed by a unique 5-digit number.

Automatic parameter setting: The Parameterized __init__ method will automatically read the list of keyword parameters. If any keyword matches the name of a Parameter (see Parameter class) defined in the object’s class or any of its superclasses, that parameter in the instance will get the value given as a keyword argument. For example:

class Foo(Parameterized):
xx = Parameter(default=1)

foo = Foo(xx=20)

in this case foo.xx gets the value 20.

When initializing a Parameterized instance (‘foo’ in the example above), the values of parameters can be supplied as keyword arguments to the constructor (using parametername=parametervalue); these values will override the class default values for this one instance.

If no ‘name’ parameter is supplied, self.name defaults to the object’s class name with a unique number appended to it.

Message formatting: Each Parameterized instance has several methods for optionally printing output. This functionality is based on the standard Python ‘logging’ module; using the methods provided here, wraps calls to the ‘logging’ module’s root logger and prepends each message with information about the instance from which the call was made. For more information on how to set the global logging level and change the default message prefix, see documentation for the ‘logging’ module.

 Object has no parameters.

debug ( **kwargs ) [source]

Inspect .param.debug method for the full docstring

defaults ( **kwargs ) [source]

Inspect .param.defaults method for the full docstring

force_new_dynamic_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.Parameterized'>) [source]
get_param_values = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.Parameterized'>) [source]
get_value_generator = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.Parameterized'>) [source]
inspect_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.Parameterized'>) [source]
message ( **kwargs ) [source]

Inspect .param.message method for the full docstring

classmethod params ( *args , **kwargs ) [source]

Inspect .param.params method for the full docstring

pprint ( imports=None , prefix=' ' , unknown_value='<?>' , qualify=False , separator='' ) [source]

(Experimental) Pretty printed representation that may be evaluated with eval. See pprint() function for more details.

classmethod print_param_defaults ( *args , **kwargs ) [source]

Inspect .param.print_param_defaults method for the full docstring

print_param_values ( **kwargs ) [source]

Inspect .param.print_param_values method for the full docstring

script_repr ( imports=[] , prefix=' ' ) [source]

Variant of __repr__ designed for generating a runnable script.

classmethod set_default ( *args , **kwargs ) [source]

Inspect .param.set_default method for the full docstring

set_dynamic_time_fn = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.Parameterized'>) [source]
set_param = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.Parameterized'>) [source]
state_pop ( ) [source]

Restore the most recently saved state.

See state_push() for more details.

state_push ( ) [source]

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose ( **kwargs ) [source]

Inspect .param.verbose method for the full docstring

warning ( **kwargs ) [source]

Inspect .param.warning method for the full docstring

class param.parameterized. ParameterizedFunction ( **params ) [source]

Bases: param.parameterized.Parameterized

params(name=String)

Acts like a Python function, but with arguments that are Parameters.

Implemented as a subclass of Parameterized that, when instantiated, automatically invokes __call__ and returns the result, instead of returning an instance of the class.

To obtain an instance of this class, call instance().

 Object has no parameters.

debug ( **kwargs )

Inspect .param.debug method for the full docstring

defaults ( **kwargs )

Inspect .param.defaults method for the full docstring

force_new_dynamic_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.ParameterizedFunction'>)
get_param_values = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.ParameterizedFunction'>)
get_value_generator = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.ParameterizedFunction'>)
inspect_value = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.ParameterizedFunction'>)
instance = functools.partial(<function ParameterizedFunction.instance>, <class 'param.parameterized.ParameterizedFunction'>) [source]
message ( **kwargs )

Inspect .param.message method for the full docstring

classmethod params ( *args , **kwargs )

Inspect .param.params method for the full docstring

pprint ( imports=None , prefix='\n ' , unknown_value='<?>' , qualify=False , separator='' ) [source]

Same as Parameterized.pprint, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod print_param_defaults ( *args , **kwargs )

Inspect .param.print_param_defaults method for the full docstring

print_param_values ( **kwargs )

Inspect .param.print_param_values method for the full docstring

script_repr ( imports=[] , prefix=' ' ) [source]

Same as Parameterized.script_repr, except that X.classname(Y is replaced with X.classname.instance(Y

classmethod set_default ( *args , **kwargs )

Inspect .param.set_default method for the full docstring

set_dynamic_time_fn = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.ParameterizedFunction'>)
set_param = functools.partial(<function Parameters.deprecate.<locals>.inner>, <class 'param.parameterized.ParameterizedFunction'>)
state_pop ( )

Restore the most recently saved state.

See state_push() for more details.

state_push ( )

Save this instance’s state.

For Parameterized instances, this includes the state of dynamically generated values.

Subclasses that maintain short-term state should additionally save and restore that state using state_push() and state_pop().

Generally, this method is used by operations that need to test something without permanently altering the objects’ state.

verbose ( **kwargs )

Inspect .param.verbose method for the full docstring

warning ( **kwargs )

Inspect .param.warning method for the full docstring

class param.parameterized. ParameterizedMetaclass ( name , bases , dict_ ) [source]

Bases: type

The metaclass of Parameterized (and all its descendents).

The metaclass overrides type.__setattr__ to allow us to set Parameter values on classes without overwriting the attribute descriptor. That is, for a Parameterized class of type X with a Parameter y, the user can type X.y=3, which sets the default value of Parameter y to be 3, rather than overwriting y with the constant value 3 (and thereby losing all other info about that Parameter, such as the doc string, bounds, etc.).

The __init__ method is used when defining a Parameterized class, usually when the module where that class is located is imported for the first time. That is, the __init__ in this metaclass initializes the class object, while the __init__ method defined in each Parameterized class is called for each new instance of that class.

Additionally, a class can declare itself abstract by having an attribute __abstract set to True. The ‘abstract’ attribute can be used to find out if a class is abstract or not.

abstract

Return True if the class has an attribute __abstract set to True. Subclasses will return False unless they themselves have __abstract set to true. This mechanism allows a class to declare itself to be abstract (e.g. to avoid it being offered as an option in a GUI), without the “abstract” property being inherited by its subclasses (at least one of which is presumably not abstract).

get_param_descriptor ( param_name ) [source]

Goes up the class hierarchy (starting from the current class) looking for a Parameter class attribute param_name. As soon as one is found as a class attribute, that Parameter is returned along with the class in which it is declared.

mro ( ) → list

return a type’s method resolution order

class param.parameterized. Parameters ( cls , self=None ) [source]

Bases: object

Object that holds the namespace and implementation of Parameterized methods as well as any state that is not in __slots__ or the Parameters themselves.

Exists at both the metaclass level (instantiated by the metaclass) and at the instance level. Can contain state specific to either the class or the instance as necessary.

debug ( msg , *args , **kw ) [source]

Print msg merged with args as a debugging statement.

See Python’s logging module for details of message formatting.

defaults ( ) [source]

Return {parameter_name:parameter.default} for all non-constant Parameters.

Note that a Parameter for which instantiate==True has its default instantiated.

classmethod deprecate ( fn ) [source]

Decorator to issue warnings for API moving onto the param namespace and to add a docstring directing people to the appropriate method.

force_new_dynamic_value ( name ) [source]

Force a new value to be generated for the dynamic attribute name, and return it.

If name is not dynamic, its current value is returned (i.e. equivalent to getattr(name).

get_param_values ( onlychanged=False ) [source]

Return a list of name,value pairs for all Parameters of this object.

When called on an instance with onlychanged set to True, will only return values that are not equal to the default value (onlychanged has no effect when called on a class).

get_value_generator ( name ) [source]

Return the value or value-generating object of the named attribute.

For most parameters, this is simply the parameter’s value (i.e. the same as getattr()), but Dynamic parameters have their value-generating object returned.

inspect_value ( name ) [source]

Return the current value of the named attribute without modifying it.

Same as getattr() except for Dynamic parameters, which have their last generated value returned.

message ( msg , *args , **kw ) [source]

Print msg merged with args as a message.

See Python’s logging module for details of message formatting.

params ( parameter_name=None ) [source]

Return the Parameters of this class as the dictionary {name: parameter_object}

Includes Parameters from this class and its superclasses.

print_param_defaults ( ) [source]

Print the default values of all cls’s Parameters.

print_param_values ( ) [source]

Print the values of all this object’s Parameters.

set_default ( param_name , value ) [source]

Set the default value of param_name.

Equivalent to setting param_name on the class.

set_dynamic_time_fn ( time_fn , sublistattr=None ) [source]

Set time_fn for all Dynamic Parameters of this class or instance object that are currently being dynamically generated.

Additionally, sets _Dynamic_time_fn=time_fn on this class or instance object, so that any future changes to Dynamic Parmeters can inherit time_fn (e.g. if a Number is changed from a float to a number generator, the number generator will inherit time_fn).

If specified, sublistattr is the name of an attribute of this class or instance that contains an iterable collection of subobjects on which set_dynamic_time_fn should be called. If the attribute sublistattr is present on any of the subobjects, set_dynamic_time_fn() will be called for those, too.

set_param ( *args , **kwargs ) [source]

For each param=value keyword argument, sets the corresponding parameter of this object or class to the given value.

For backwards compatibility, also accepts set_param(“param”,value) for a single parameter value using positional arguments, but the keyword interface is preferred because it is more compact and can set multiple values.

trigger ( *param_names ) [source]

Trigger watchers for the given set of parameter names. Watchers will be triggered whether or not the parameter values have actually changed.

unwatch ( watcher ) [source]

Unwatch watchers set either with watch or watch_values.

verbose ( msg , *args , **kw ) [source]

Print msg merged with args as a verbose message.

See Python’s logging module for details of message formatting.

warning ( msg , *args , **kw ) [source]

Print msg merged with args as a warning, unless module variable warnings_as_exceptions is True, then raise an Exception containing the arguments.

See Python’s logging module for details of message formatting.

class param.parameterized. String ( default='' , regex=None , allow_None=False , **kwargs ) [source]

Bases: param.parameterized.Parameter

A String Parameter, with a default value and optional regular expression (regex) matching.

Example of using a regex to implement IPv4 address matching:

class IPAddress(String):
  '''IPv4 address as a string (dotted decimal notation)'''
 def __init__(self, default="0.0.0.0", allow_None=False, **kwargs):
     ip_regex = '^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
     super(IPAddress, self).__init__(default=default, regex=ip_regex, **kwargs)
basestring

alias of builtins.str

class param.parameterized. Watcher ( inst , cls , fn , mode , onlychanged , parameter_names )

Bases: tuple

cls

Alias for field number 1

count ( value ) → integer -- return number of occurrences of value
fn

Alias for field number 2

index ( value [ , start [ , stop ] ] ) → integer -- return first index of value.

Raises ValueError if the value is not present.

inst

Alias for field number 0

mode

Alias for field number 3

onlychanged

Alias for field number 4

parameter_names

Alias for field number 5

param.parameterized. add_metaclass ( metaclass ) [source]

Class decorator for creating a class with a metaclass.

param.parameterized. all_equal ( arg1 , arg2 ) [source]

Return a single boolean for arg1==arg2, even for numpy arrays using element-wise comparison.

Uses all(arg1==arg2) for sequences, and arg1==arg2 otherwise.

If both objects have an ‘_infinitely_iterable’ attribute, they are not be zipped together and are compared directly instead.

param.parameterized. as_uninitialized ( fn ) [source]

Decorator: call fn with the parameterized_instance’s initialization flag set to False, then revert the flag.

(Used to decorate Parameterized methods that must alter a constant Parameter.)

class param.parameterized. bothmethod ( func ) [source]

Bases: object

‘optional @classmethod’

A decorator that allows a method to receive either the class object (if called on the class) or the instance object (if called on the instance) as its first argument.

Code (but not documentation) copied from: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/523033 .

param.parameterized. classlist ( class_ ) [source]

Return a list of the class hierarchy above (and including) the given class.

Same as inspect.getmro( class_ )[::-1]

param.parameterized. dbprint_prefix = None

If not None, the value of this Parameter will be called (using ‘()’) before every call to __db_print, and is expected to evaluate to a string that is suitable for prefixing messages and warnings (such as some indicator of the global state).

param.parameterized. descendents ( class_ ) [source]

Return a list of the class hierarchy below (and including) the given class.

The list is ordered from least- to most-specific. Can be useful for printing the contents of an entire class hierarchy.

param.parameterized. get_all_slots ( class_ ) [source]

Return a list of slot names for slots defined in class_ and its superclasses.

param.parameterized. get_occupied_slots ( instance ) [source]

Return a list of slots for which values have been set.

(While a slot might be defined, if a value for that slot hasn’t been set, then it’s an AttributeError to request the slot’s value.)

param.parameterized. logging_level ( level ) [source]

Temporarily modify param’s logging level.

class param.parameterized. overridable_property ( fget=None , fset=None , fdel=None , doc=None ) [source]

Bases: object

The same as Python’s “property” attribute, but allows the accessor methods to be overridden in subclasses.

param.parameterized. pprint ( val , imports , prefix='\n ' , settings=[] , unknown_value='<?>' , qualify=False , separator='' ) [source]

(Experimental) Pretty printed representation of a parameterized object that may be evaluated with eval.

Similar to repr except introspection of the constructor (__init__) ensures a valid and succinct representation is generated.

Only parameters are represented (whether specified as standard, positional, or keyword arguments). Parameters specified as positional arguments are always shown, followed by modified parameters specified as keyword arguments, sorted by precedence.

unknown_value determines what to do where a representation cannot be generated for something required to recreate the object. Such things include non-parameter positional and keyword arguments, and certain values of parameters (e.g. some random state objects).

Supplying an unknown_value of None causes unrepresentable things to be silently ignored. If unknown_value is a string, that string will appear in place of any unrepresentable things. If unknown_value is False, an Exception will be raised if an unrepresentable value is encountered.

If supplied, imports should be a list, and it will be populated with the set of imports required for the object and all of its parameter values.

If qualify is True, the class’s path will be included (e.g. “a.b.C()”), otherwise only the class will appear (“C()”).

Parameters will be separated by a comma only by default, but the separator parameter allows an additional separator to be supplied (e.g. a newline could be supplied to have each Parameter appear on a separate line).

NOTE: pprint will replace script_repr in a future version of param, but is not yet a complete replacement for script_repr.

param.parameterized. print_all_param_defaults ( ) [source]

Print the default values for all imported Parameters.

param.parameterized. script_repr ( val , imports , prefix , settings ) [source]

Variant of repr() designed for generating a runnable script.

Instances of types that require special handling can use the script_repr_reg dictionary. Using the type as a key, add a function that returns a suitable representation of instances of that type, and adds the required import statement.

The repr of a parameter can be suppressed by returning None from the appropriate hook in script_repr_reg.

param.parameterized. script_repr_reg = {<class 'random.Random'>: <function empty_script_repr>, <class 'mtrand.RandomState'>: <function empty_script_repr>, <class 'list'>: <function container_script_repr>, <class 'tuple'>: <function container_script_repr>, <class 'function'>: <function function_script_repr>}

see script_repr()

class param.parameterized. shared_parameters [source]

Bases: object

Context manager to share parameter instances when creating multiple Parameterized objects of the same type. Parameter default values are instantiated once and cached to be reused when another Parameterized object of the same type is instantiated. Can be useful to easily modify large collections of Parameterized objects at once and can provide a significant speedup.


version Module

Inheritance diagram of param.version

Provide consistent and up-to-date __version__ strings for Python packages.

See https://github.com/pyviz/autover for more information.

class param.version. OldDeprecatedVersion ( release=None , fpath=None , commit=None , reponame=None , dev=None , commit_count=0 ) [source]

Bases: object

A simple approach to Python package versioning that supports PyPI releases and additional information when working with version control. When obtaining a package from PyPI, the version returned is a string-formatted rendering of the supplied release tuple. For instance, release (1,0) tagged as v1.0 in the version control system will return 1.0 for str(__version__) . Any number of items can be supplied in the release tuple, with either two or three numeric versioning levels typical.

During development, a command like git describe will be used to compute the number of commits since the last version tag, the short commit hash, and whether the commit is dirty (has changes not yet committed). Version tags must start with a lowercase ‘v’ and have a period in them, e.g. v2.0, v0.9.8 or v0.1.

Development versions are supported by setting the dev argument to an appropriate dev version number. The corresponding tag can be PEP440 compliant (using .devX) of the form v0.1.dev3, v1.9.0.dev2 etc but it doesn’t have to be as the dot may be omitted i.e v0.1dev3, v1.9.0dev2 etc.

Also note that when version control system (VCS) information is used, the comparison operators take into account the number of commits since the last version tag. This approach is often useful in practice to decide which version is newer for a single developer, but will not necessarily be reliable when comparing against a different fork or branch in a distributed VCS.

For git, if you want version control information available even in an exported archive (e.g. a .zip file from GitHub), you can set the following line in the .gitattributes file of your project:

__init__.py export-subst
abbrev ( dev_suffix='' ) [source]

Abbreviated string representation, optionally declaring whether it is a development version.

commit

A specification for this particular VCS version, e.g. a short git SHA

commit_count

Return the number of commits since the last release

dirty

True if there are uncommited changes, False otherwise

fetch ( ) [source]

Returns a tuple of the major version together with the appropriate SHA and dirty bit (for development version only).

release

Return the release tuple

verify ( string_version=None ) [source]

Check that the version information is consistent with the VCS before doing a release. If supplied with a string version, this is also checked against the current version. Should be called from setup.py with the declared package version before releasing to PyPI.

class param.version. Version ( release=None , fpath=None , commit=None , reponame=None , commit_count_prefix='.post' , archive_commit=None , **kwargs ) [source]

Bases: object

A simple approach to Python package versioning that supports PyPI releases and additional information when working with version control. When obtaining a package from PyPI, the version returned is a string-formatted rendering of the supplied release tuple. For instance, release (1,0) tagged as v1.0 in the version control system will return 1.0 for str(__version__) . Any number of items can be supplied in the release tuple, with either two or three numeric versioning levels typical.

During development, a command like git describe will be used to compute the number of commits since the last version tag, the short commit hash, and whether the commit is dirty (has changes not yet committed). Version tags must start with a lowercase ‘v’ and have a period in them, e.g. v2.0, v0.9.8 or v0.1 and may include the PEP440 prerelease identifiers of ‘a’ (alpha) ‘b’ (beta) or ‘rc’ (release candidate) allowing tags such as v2.0.a3, v0.9.8.b3 or v0.1.rc5.

Also note that when version control system (VCS) information is used, the number of commits since the last version tag is determined. This approach is often useful in practice to decide which version is newer for a single developer, but will not necessarily be reliable when comparing against a different fork or branch in a distributed VCS.

For git, if you want version control information available even in an exported archive (e.g. a .zip file from GitHub), you can set the following line in the .gitattributes file of your project:

__init__.py export-subst

Note that to support pip installation directly from GitHub via git archive, a .version file must be tracked by the repo to supply the release number (otherwise only the short SHA is available).

The PEP440 format returned is [N!]N(.N)*[{a|b|rc}N][.postN+SHA] where everything before .postN is obtained from the tag, the N in .postN is the number of commits since the last tag and the SHA is obtained via git describe. This later portion is only shown if the commit count since the last tag is non zero. Instead of ‘.post’, an alternate valid prefix such as ‘.rev’, ‘_rev’, ‘_r’ or ‘.r’ may be supplied.

abbrev ( ) [source]

Abbreviated string representation of just the release number.

commit

A specification for this particular VCS version, e.g. a short git SHA

commit_count

Return the number of commits since the last release

dirty

True if there are uncommited changes, False otherwise

fetch ( ) [source]

Returns a tuple of the major version together with the appropriate SHA and dirty bit (for development version only).

classmethod get_setup_version ( setup_path , reponame , describe=False , dirty='report' , pkgname=None , archive_commit=None ) [source]

Helper for use in setup.py to get the version from the .version file (if available) or more up-to-date information from git describe (if available).

Assumes the __init__.py will be found in the directory {reponame}/__init__.py relative to setup.py unless pkgname is explicitly specified in which case that name is used instead.

If describe is True, the raw string obtained from git described is returned which is useful for updating the .version file.

The dirty policy can be one of ‘report’, ‘strip’, ‘raise’. If it is ‘report’ the version string may end in ‘-dirty’ if the repository is in a dirty state. If the policy is ‘strip’, the ‘-dirty’ suffix will be stripped out if present. If the policy is ‘raise’, an exception is raised if the repository is in a dirty state. This can be useful if you want to make sure packages are not built from a dirty repository state.

prerelease

Either None or one of ‘aN’ (alpha), ‘bN’ (beta) or ‘rcN’ (release candidate) where N is an integer.

release

Return the release tuple

verify ( string_version=None ) [source]

Check that the version information is consistent with the VCS before doing a release. If supplied with a string version, this is also checked against the current version. Should be called from setup.py with the declared package version before releasing to PyPI.

param.version. get_setup_version ( location , reponame , pkgname=None , archive_commit=None ) [source]

Helper for use in setup.py to get the current version from either git describe or the .version file (if available).

Set pkgname to the package name if it is different from the repository name.

To ensure git information is included in a git archive, add setup.py to .gitattributes (in addition to __init__): ` __init__.py export-subst setup.py export-subst ` Then supply “$Format:%h$” for archive_commit.

param.version. get_setupcfg_version ( ) [source]

As get_setup_version(), but configure via setup.cfg.

If your project uses setup.cfg to configure setuptools, and hence has at least a “name” key in the [metadata] section, you can set the version as follows: ` [metadata] name = mypackage version = attr: autover.version.get_setup_version2 `

If the repository name is different from the package name, specify reponame as a [tool:autover] option: ` [tool:autover] reponame = mypackage `

To ensure git information is included in a git archive, add setup.cfg to .gitattributes (in addition to __init__): ` __init__.py export-subst setup.cfg export-subst `

Then add the following to setup.cfg: ` [tool:autover.configparser_workaround.archive_commit=$Format:%h$] `

The above being a section heading rather than just a key is because setuptools requires % to be escaped with %, or it can’t parse setup.cfg…but then git export-subst would not work.