pydrobert.param.argparse

Hooks for command-line interface with params

class pydrobert.param.argparse.ParameterizedFileReadAction(option_strings, dest, parameterized=None, type=None, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn', required=False, help=None, metavar=None, nargs=None, const=None)[source]

Bases: Action

Base class for deserializing files into a Parameterized object

Subclasses of this class can be added as the ‘action’ keyword to an argparse.ArgumentParser.add_argument() call. The action will read the file path passed as an argument via command line and use the contents of the file to populate param.parameterized.Parameterized instances. The subclass deserializes the contents of the file according to the pydrobert.param.serialization.deserialize_from_filetype() function, where filetype is replaced with the subclass’ file type.

There are three ways to specify parameterized objects to populate. They are mutually exclusive:

  1. Set the keyword type with the subclass of param.parameterized.Parameterized you want to deserialize into. A new instance of that subclass will be created with the name type.__name__. The instance will be returned in the parsed namespace’s attribute whose name matches dest as well.

  2. Set the keyword parameterized with an instance of param.parameterized.Parameterized. That instance will be populated and also returned in the parsed namespace’s attribute whose name matches dest.

  3. Set the keyword parameterized as a hierarchical dictionary of param.parameterized.Parameterized instances. The leaves of the dictionary will be populated according to the “hierarchical mode” specified in the documentation of pydrobert.param.serialization.deserialize_from_dict(). The same dictionary will be returned in the parsed namespace’s attribute whose name matches dest.

Parameters

  • option_strings (List[str]) – A list of command-line option strings which should be associated with this action.

  • dest (str) – The name of the attribute to hold the created object.

  • parameterized (Union[Parameterized, dict, None]) –

  • type (Optional[Type[Parameterized]]) –

  • deserializer_name_dict (Optional[dict]) – Use specific deserializers for parameters with specific names.

  • deserializer_type_dict (Optional[dict]) – Use specific deserializers for parameters with exactly matching types.

  • on_missing (Literal[‘ignore’, ‘warn’, ‘raise’]) – What to do if the parameterized instance does not have a parameter listed in the config file.

  • required (bool) – True if the action must always be specified at the command line. This is only meaningful for optional command-line arguments.

  • help (Optional[str]) – The help string describing the argument.

  • metavar (Optional[str]) – The name to be used for the option’s argument with the help string. If None, the dest value will be used as the name.

  • nargs (Union[str, int, None]) – The number of command line arguments to be consumed. When more than one argument is specified, each will be deserialized in the order that they were presented on the command line. Thus, later config values will clobber earlier ones

  • const (Optional[str]) – If nargs is '?' but the flag is present on the command line, this value will be supplied as the missing argument

See also

pydrobert.param.serialization.deserialize_from_dict

For more information on how values are deserialized from the config

abstract deserialize(fp)[source]

Read the file pointer into parameterized objects

Called during the callable section of this class. Implemented by subclasses.

class pydrobert.param.argparse.ParameterizedIniPrintAction(option_strings, dest, parameterized=None, type=None, serializer_name_dict=None, serializer_type_dict=None, only=None, on_missing='raise', include_help=True, help=None, out_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, help_prefix='#', one_param_section=None)[source]

Bases: ParameterizedPrintAction

Print parameters as INI and exit

Parameters

See also

ParameterizedPrintAction

A full description of the parameters and behaviour of like actions

pydrobert.param.serialization.serialize_to_ini

A description of the serialization process and of the additional parameters

class pydrobert.param.argparse.ParameterizedIniReadAction(option_strings, dest, parameterized=None, type=None, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn', required=False, help=None, metavar=None, nargs=None, const=None, defaults=None, comment_prefixes=('#', ';'), inline_comment_prefixes=(';',), one_param_section=None)[source]

Bases: ParameterizedFileReadAction

Deserialize an INI file into a parameterized object

Parameters

See also

ParameterizedFileReadAction

A full description of the parameters and behaviour of like actions.

pydrobert.param.serialization.deserialize_from_ini

A description of the deserialization process and of the additional parameters.

class pydrobert.param.argparse.ParameterizedJsonPrintAction(option_strings, dest, parameterized=None, type=None, serializer_name_dict=None, serializer_type_dict=None, only=None, on_missing='raise', help=None, out_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, indent=2)[source]

Bases: ParameterizedPrintAction

Print parameters as JSON and exit

Parameters

See also

ParameterizedPrintAction

A full description of the parameters and behaviour of like actions

pydrobert.param.serialization.serialize_to_json

A description of the serialization process and of the additional parameters

class pydrobert.param.argparse.ParameterizedJsonReadAction(option_strings, dest, parameterized=None, type=None, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn', required=False, help=None, metavar=None, nargs=None, const=None)[source]

Bases: ParameterizedFileReadAction

Deserialize a JSON file into a parameterized object

Parameters

See also

ParameterizedFileReadAction

A full description of the parameters and behaviour of like actions.

pydrobert.param.serialization.deserialize_from_json

A description of the deserialization process.

class pydrobert.param.argparse.ParameterizedPrintAction(option_strings, dest, parameterized=None, type=None, serializer_name_dict=None, serializer_type_dict=None, only=None, on_missing='raise', include_help=True, help=None, out_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]

Bases: Action

Base class for printing parameters to stdout and exiting

Subclasses of this class can be added as the ‘action’ keyword to an argparse.ArgumentParser.add_argument() call. Like the --help flag, after this action is called, the program will try to exit, but not before printing out parameters.

There are three ways to specify what parameters to print, analogous to how they are specified in ParameterizedFileReadAction:

  1. Set the keyword type with a subclass of param.parameterized.Parameterized. A new instance of that type will be created to be printed. Its name will be type.__name__

  2. Set the keyword parameterized with an instance of param.parameterized.Parameterized. That instance will be printed.

  3. Set the keyword parameterized as a hierarchical dictionary of param.parameterized.Parameterized instances. The leaves of the dictionary will be populated according to the “hierarchical mode” specified in the documentation of pydrobert.param.serialization.serialize_to_dict()

Note that if a ParameterizedFileReadAction has been called on the command line prior to the print that shares the same parameterized value as in 2. or 3., parameterized will be populated by that file’s contents.

Parameters

  • option_strings (List[str]) – A list of command-line option strings which should be associated with this action.

  • dest (str) – Ignored

  • parameterized (Union[Parameterized, dict, None]) –

  • type (Optional[Type[Parameterized]]) –

  • serializer_name_dict (Optional[dict]) – Use specific serializers for parameters with specific names

  • serializer_type_dict (Optional[dict]) – Use specific serializers for parameters with exactly matching types

  • only (Optional[Collection[str]]) – If specified, only the parameters with their names in this set will be printed

  • on_missing (Literal[‘ignore’, ‘warn’, ‘raise’]) – What to do if the parameterized instance does not have a parameter listed in only

  • include_help (bool) – Whether to print parameter help when printing parameters

  • help (Optional[str]) – The help string describing the argument

  • out_stream (TextIO) – Where to print the parameters to

abstract print_parameters()[source]

Print the parameters

Called during the callable section of this class. Should print to the attribute out_stream

class pydrobert.param.argparse.ParameterizedYamlPrintAction(option_strings, dest, parameterized=None, type=None, serializer_name_dict=None, serializer_type_dict=None, only=None, on_missing='raise', include_help=True, help=None, out_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]

Bases: ParameterizedPrintAction

Print parameters as YAML and exit

Parameters

See also

ParameterizedPrintAction

A full description of the parameters and behaviour of like actions

pydrobert.param.serialization.serialize_to_yaml

A description of the serialization process and of the additional parameters

class pydrobert.param.argparse.ParameterizedYamlReadAction(option_strings, dest, parameterized=None, type=None, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn', required=False, help=None, metavar=None, nargs=None, const=None)[source]

Bases: ParameterizedFileReadAction

Deserialize a YAML file into a parameterized object

Parameters

See also

ParameterizedFileReadAction

A full description of the parameters and behaviour of like actions

pydrobert.param.serialization.deserialize_from_yaml

A description of the deserialization process.

pydrobert.param.argparse.add_parameterized_print_group(parser, type=None, parameterized=None, include_yaml=None, ini_option_strings=('--print-ini',), json_option_strings=('--print-json',), yaml_option_strings=('--print-yaml',), ini_kwargs={}, json_kwargs={}, yaml_kwargs={})[source]

Add flags to print parameters as INI, JSON, or YAML

This convenience function adds a group of print actions to parser to print parameters and exit in one of INI, JSON, or YAML format.

What to print is determined by the keyword args type or parameterized.

  1. If type is specified, it will be instantiated and printed with whatever defaults it has. The instance will have the name type.__name__

  2. If parameterized is a param.parameterized.Parameterized instance, that instance will be printed

  3. If parameterized is a dictionary of param.parameterized.Parameterized instances, those instances will be serialized to dictionaries, then the dictionary of dictionaries will be printed. parameterized can contain nested dictionaries of param.parameterized.Parameterized instances, but it will be unable to be printed as an INI file, only JSON or YAML

Parameters

  • parser (ArgumentParser) –

  • type (Optional[Type[Parameterized]]) –

  • parametrized –

  • include_yaml (Optional[bool]) – Whether to include the YAML print flags. YAML requires one of ruamel.yaml or yaml to be installed. If unset, we will include the flags if it is possible to import a YAML module.

  • ini_option_strings (Sequence[str]) – Zero or more option strings specifying that INI format should be printed. If no option strings are specified, INI printing is disabled

  • json_option_strings (Sequence[str]) – Zero or more option strings specifying that JSON format should be printed. If no option strings are specified, JSON printing is disabled

  • yaml_option_strings (Sequence[str]) – Zero or more option strings specifying that YAML format should be printed. If no option strings are specified, YAML printing is disabled

  • ini_kwargs (dict) – Additional keyword arguments to use when creating the INI flag. See ParameterizedIniPrintAction for more info

  • json_kwargs (dict) – Additional keyword arguments to use when creating the JSON flag. See ParameterizedJsonPrintAction for more info

  • yaml_kwargs (dict) – Additional keyword arguments to use when creating the YAML flag. See ParameterizedYamlPrintAction for more info

Returns

group (obj) – The group containing the flags

Examples

>>> import param, argparse
>>> class MyParams(param.Parameterized):
...     an_int = param.Integer(1)
...     a_bool = param.Boolean(True)
>>> parser = argparse.ArgumentParser()
>>> add_parameterized_print_group(parser, type=MyParams)
>>> try:
...     parser.parse_args(['--print-ini'])
... except SystemExit:
...     pass
[MyParams]
a_bool = true
an_int = 1
>>> try:
...     # only works if ruamel.yaml/ruamel_yaml or pyyaml installed
...     parser.parse_args(['--print-yaml'])
... except SystemExit:
...     pass
a_bool: true
an_int: 1

>>> import param, argparse
>>> class A(param.Parameterized):
...     something = param.Integer(None)
...     else_ = param.List([1, 2])
>>> class B(param.Parameterized):
...     float_ = param.Number(3.14)
>>> parameterized = {'A': {'AA': A()}, 'B': B()}
>>> parser = argparse.ArgumentParser()
>>> add_parameterized_print_group(
...     parser, parameterized=parameterized, json_kwargs={'indent': None})
>>> try:
...     parser.parse_args(['--print-json'])
... except SystemExit:
...     pass
{"A": {"AA": {"else_": [1, 2], "something": null}}, "B": {"float_": 3.14}}

Notes

The returned group is technically mutally exclusive. However, since the print action ends with a sys.exit() call, mutual exclusivity will never be enforced

pydrobert.param.argparse.add_parameterized_read_group(parser, parameterized=None, type=None, include_yaml=None, ini_option_strings=('--read-ini',), json_option_strings=('--read-json',), yaml_option_strings=('--read-yaml',), dest='params', ini_kwargs={}, json_kwargs={}, yaml_kwargs={})[source]

Add flags to read configs from INI, JSON, or YAML sources

This convenience function adds a mutually exclusive group of read actions to parser to read in parameters from 3 file types: INI, JSON, or YAML.

What to read into is determined by the keyword args type or parameterized.

  1. If type is specified, it will be instantiated and populated. Its name will match type.__name__

  2. If parameterized is specified and is a param.parameterized.Parameterized instance, it will be populated directly.

  3. If parameterized is a dictionary whose leaves are param.parameterized.Parameterized, sections of the config whose keys match the keys of the dictionary will populate the corresponding param.parameterized.Parameterized instances. parameterized can nest those instances repeatedly, but only a shallow dict will be able to be parsed from an INI file

Parameters

  • parser (ArgumentParser) –

  • type (Optional[Type[Parameterized]]) –

  • parametrized –

  • include_yaml (Optional[bool]) – Whether to include the YAML config flags. YAML requires one of ruamel.yaml or yaml to be installed. If unset, we will include the flags if it is possible to import a YAML module.

  • ini_option_strings (Sequence[str]) – Zero or more option strings specifying that the next argument is an INI file to be read. If no option strings are specified, INI reading is disabled

  • json_option_strings (Sequence[str]) – Zero or more option strings specifying that the next argument is an JSON file to be read. If no option strings are specified, JSON reading is disabled

  • yaml_option_strings (Sequence[str]) – Zero or more option strings specifying that the next argument is an YAML file to be read. If no option strings are specified, YAML reading is disabled

  • dest (str) – Under what name to store parameters in the returned namespace of parser.parse_args(...)

  • ini_kwargs (dict) – Additional keyword arguments to use when creating the INI flag. See ParameterizedIniReadAction for more info

  • json_kwargs (dict) – Additional keyword arguments to use when creating the JSON flag. See :class`ParameterizedJsonReadAction` for more info

  • yaml_kwargs (dict) – Additional keyword arguments to use when creating the YAML flag. See :class`ParameterizedYamlReadAction` for more info

Returns

group (obj) – The mutually exclusive group containing the flags

Examples

>>> # write some configs
>>> with open('config.ini', 'w') as f:
>>>     f.write('[DEFAULT]\nfoo = a\n')
>>> with open('config.json', 'w') as f:
>>>     f.write('{"foo": "b"}\n')
>>> # make our Parameterized type
>>> import param, argparse
>>> class MyParams(param.Parameterized):
>>>     foo = param.String(None)
>>> # make our parser
>>> parser = argparse.ArgumentParser()
>>> add_parameterized_read_group(parser, type=MyParams)
>>> # parse an INI
>>> options = parser.parse_args(['--read-ini', 'config.ini'])
>>> assert options.params.foo == "a"
>>> # parse a JSON
>>> options = parser.parse_args(['--read-json', 'config.json'])
>>> assert options.params.foo == "b"

>>> # write a hierarchical config
>>> with open('config.yaml', 'w') as f:
>>>     f.write("""
... A:
...   foo: bar
...   baz: 1
... B:
...   B.1:
...     me: I may
...   B.2:
...     me: me me mee
... """)
>>> # make our Parameterized types
>>> class A(param.Parameterized):
>>>     foo = param.String(None)
>>>     bar = param.Integer(None)
>>> class B(param.Parameterized):
>>>     me = param.String(None)
>>> parameterized = {'A': A(), 'B': {'B.1': B(), 'B.2': B()}}
>>> # make our parser
>>> parser = argparse.ArgumentParser()
>>> add_parameterized_read_group(parser, parameterized=parameterized)
>>> # parse YAML (requires package ruamel.yaml/ruamel_yaml or pyyaml)
>>> parser.parse_args(['--read-yaml', 'config.yaml'])
>>> assert parameterized['A'].baz == 1
>>> assert parameterized['B']['B.2'].me == 'me me mee'