4.6.11 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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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')[source]

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)[source]

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)