4.6.13 pde.tools.parameters module

Infrastructure for managing classes with parameters.

One aim is to allow easy management of inheritance of parameters.

Parameter	Class representing a single parameter.
DeprecatedParameter	A parameter that can still be used normally but is deprecated.
HideParameter	A helper class that allows hiding parameters of the parent classes.
Parameterized	A mixin that manages the parameters of a class.
get_all_parameters	Get a dictionary with all parameters of all registered classes.

class DeprecatedParameter(name, default_value=None, cls=<class 'object'>, description='', hidden=False, extra=None)

Bases: Parameter

A parameter that can still be used normally but is deprecated.

Initialize a parameter.

Parameters:

• name (str) – The name of the parameter

• default_value – The default value

• cls – The type of the parameter, which is used for conversion

• description (str) – A string describing the impact of this parameter. This description appears in the parameter help

• hidden (bool) – Whether the parameter is hidden in the description summary

• extra (dict) – Extra arguments that are stored with the parameter

class HideParameter(name)

Bases: object

A helper class that allows hiding parameters of the parent classes.

Parameters:

name (str) – The name of the parameter

class Parameter(name, default_value=None, cls=<class 'object'>, description='', hidden=False, extra=None)

Bases: object

Class representing a single parameter.

Initialize a parameter.

Parameters:

• name (str) – The name of the parameter

• default_value – The default value

• cls – The type of the parameter, which is used for conversion

• description (str) – A string describing the impact of this parameter. This description appears in the parameter help

• hidden (bool) – Whether the parameter is hidden in the description summary

• extra (dict) – Extra arguments that are stored with the parameter

convert(value=None)

Converts a value into the correct type for this parameter. If value is not given, the default value is converted.

Note that this does not make a copy of the values, which could lead to unexpected effects where the default value is changed by an instance.

Parameters:

value – The value to convert

Returns:

The converted value, which is of type self.cls

class Parameterized(parameters=None)

Bases: object

A mixin that manages the parameters of a class.

Initialize the parameters of the object.

Parameters:

parameters (dict) – A dictionary of parameters to change the defaults. The allowed parameters can be obtained from get_parameters() or displayed by calling show_parameters().

get_parameter_default(name)

Return the default value for the parameter with name

Parameters:

name (str) – The parameter name

classmethod get_parameters(include_hidden=False, include_deprecated=False, sort=True)

Return a dictionary of parameters that the class supports.

Parameters:

• include_hidden (bool) – Include hidden parameters

• include_deprecated (bool) – Include deprecated parameters

• sort (bool) – Return ordered dictionary with sorted keys

Returns:

a dictionary of instance of Parameter with their names as keys.

Return type:

dict

parameters_default: Sequence[Parameter | HideParameter] = []

show_parameters(description=None, sort=False, show_hidden=False, show_deprecated=False)

Show all parameters in human readable format.

Parameters:

• description (bool) – Flag determining whether the parameter description is shown. The default is to show the description only when we are in a jupyter notebook environment.

• sort (bool) – Flag determining whether the parameters are sorted

• show_hidden (bool) – Flag determining whether hidden parameters are shown

• show_deprecated (bool) – Flag determining whether deprecated parameters are shown

• default_value (bool) – Flag determining whether the default values or the current values are shown

All flags default to False.

get_all_parameters(data='name')

Get a dictionary with all parameters of all registered classes.

Parameters:

data (str) – Determines what data is returned. Possible values are ‘name’, ‘value’, or ‘description’, to return the respective information about the parameters.

Return type:

dict[str, Any]

sphinx_display_parameters(app, what, name, obj, options, lines)

Helper function to display parameters in sphinx documentation.

Example

This function should be connected to the ‘autodoc-process-docstring’ event like so:

app.connect(‘autodoc-process-docstring’, sphinx_display_parameters)