4.6.10. 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: str, default_value=None, cls=<class 'object'>, description: str = '', hidden: bool = False, extra: ~Optional[~Dict[str, ~Any]] = 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: str)[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: str, default_value=None, cls=<class 'object'>, description: str = '', hidden: bool = False, extra: ~Optional[~Dict[str, ~Any]] = 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: Optional[Dict[str, Any]] = 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: bool = False, include_deprecated: bool = False, sort: bool = True) Dict[str, Parameter][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[Union[Parameter, HideParameter]] = []
show_parameters(description: Optional[bool] = None, sort: bool = False, show_hidden: bool = False, show_deprecated: bool = 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: str = 'name') Dict[str, Any][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.

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)