Param¶

class Param[source]¶

Bases: configpile.arg.Arg, Generic[configpile.arg._Value_co]

Describes an argument holding a value of a given type

You’ll want to construct parameters using the static methods available:

store() to create a parameter that keeps the last value provided
append() to create a parameter that collects all the provided values into a sequence. Note that the parsed value must already be a sequence.
append1() to create a parameter that collects all the provided value into a sequence. The parsed value should not be a sequence.

For the constructions above, you can construct positional parameters by setting the Param.positional field.

config() returns a parameter that parses configuration files.

Attributes

Note: attributes inherited from parent classes are not shown here, if any

`parser`	Argument type, parser from string to value
`is_config`	Whether this represents a list of config files
`is_root_path`	Whether this represents a root path
`collector`	Argument collector
`default_value`	Default value inserted as instance
`name`	Python identifier representing the argument
`positional`	Whether this parameter can appear as a positional parameter and how
`config_key_name`	Configuration key name used in INI files
`env_var_name`	Environment variable name

Methods

`all_config_key_names`	Returns a sequence of all forms of command line options
`all_env_var_names`	Returns a sequence of all forms of command line options
`all_flags`	Returns a sequence of all forms of command line flags
`append`	Returns a newly created argument that joins parsed sequences of values
`append1`	Returns a newly created argument that appends single parsed values
`argparse_argument_kwargs`	Returns the keyword arguments for use with argparse.ArgumentParser.add_argument
`config`	Creates a parameter that parses configuration files and stores their names
`is_required`	Returns whether the argument is required
`root_path`	Creates a parameter that describes a root path
`store`	Creates a parameter that stores the last provided value
`update_dict_`	Returns updated values for this argument, used during `App` construction
`update_processor`	Updates a config processor with the processing required by this argument
`updated`	Returns a copy of this argument with some data updated from its declaration context

List of members of Param

parser: configpile.parsers.Parser[configpile.arg._Value_co]¶: Argument type, parser from string to value

is_config: bool¶: Whether this represents a list of config files

is_root_path: bool¶: Whether this represents a root path

collector: configpile.collector.Collector[configpile.arg._Value_co]¶: Argument collector

default_value: Optional[str]¶: Default value inserted as instance

name: Optional[str]¶: Python identifier representing the argument

positional: Optional[configpile.enums.Positional]¶

Whether this parameter can appear as a positional parameter and how

A positional parameter is a parameter that appears without a preceding flag

config_key_name: Optional[Union[str, configpile.enums.Derived]]¶

Configuration key name used in INI files

It is lowercase, and words are separated by hyphens.

env_var_name: Optional[Union[str, configpile.enums.Derived]]¶

Environment variable name

The environment variable name has a prefix, followed by the Python identifier in uppercase, with underscore as separator.

This prefix is provided by App.env_prefix_

update_dict_(name, help, env_prefix)[source]¶

Returns updated values for this argument, used during App construction

Parameters

name (str) – Argument field name
help (Optional[str]) – Argument docstring which describes the argument role
env_prefix (Optional[str]) – Uppercase prefix for all environment variables

Returns:

Return type: Mapping[str, Any]

all_config_key_names()[source]¶

Returns a sequence of all forms of command line options

Return type: Sequence[str]
Returns: Command line options

all_env_var_names()[source]¶

Returns a sequence of all forms of command line options

Return type: Sequence[str]
Returns: Command line options

is_required()[source]¶

Returns whether the argument is required

Return type: bool

argparse_argument_kwargs()[source]¶

Returns the keyword arguments for use with argparse.ArgumentParser.add_argument

Return type: Mapping[str, Any]
Returns: Keyword arguments mapping

update_processor(pf)[source]¶

Updates a config processor with the processing required by this argument

Parameters: pf (ProcessorFactory[TypeVar(_Config, bound= Config)]) – Processor factory
Return type: None

static store(parser, *, help=None, default_value=None, positional=None, short_flag_name=None, long_flag_name=Derived.KEBAB_CASE, config_key_name=Derived.KEBAB_CASE, env_var_name=None)[source]¶

Creates a parameter that stores the last provided value

If a default value is provided, the argument can be omitted. However, if the default_value None is given (default), then the parameter cannot be omitted.

Parameters

parser (Parser[TypeVar(_Value_co, covariant=True)]) – Parser that transforms a string into a value

Keyword Arguments

help – Help description (autodoc/docstring is used otherwise)
default_value – Default value
positional – Whether this parameter is present in positional arguments
short_flag_name –
long_flag_name – Long option name (auto. derived from fieldname by default)
config_key_name – Config key name (auto. derived from fieldname by default)
env_var_name – Environment variable name (forbidden by default)

Return type

Param[TypeVar(_Value_co, covariant=True)]

Returns

The constructed Param instance

static root_path(*, help=None, short_flag_name=None, long_flag_name=Derived.KEBAB_CASE, env_var_name=None)[source]¶

Creates a parameter that describes a root path

Keyword Arguments

help – Help description (autodoc/docstring is used otherwise)
short_flag_name – Short option name (optional)
long_flag_name – Long option name (auto. derived from fieldname by default)
env_var_name – Environment variable name (forbidden by default)

Return type

Param[Path]

Returns

A root path parameter

static config(*, help=None, short_flag_name=None, long_flag_name=Derived.KEBAB_CASE, env_var_name=None)[source]¶

Creates a parameter that parses configuration files and stores their names

Keyword Arguments

help – Help description (autodoc/docstring is used otherwise)
short_flag_name – Short option name (optional)
long_flag_name – Long option name (auto. derived from fieldname by default)
env_var_name – Environment variable name (forbidden by default)

Return type

Param[Sequence[Path]]

Returns

A configuration files parameter

static append1(parser, *, help=None, positional=None, short_flag_name=None, long_flag_name=Derived.KEBAB_CASE, config_key_name=Derived.KEBAB_CASE, env_var_name=None)[source]¶

Returns a newly created argument that appends single parsed values

While append() creates a parameter that joins sequences of values, this method creates a parameter that appends single items to a sequence.

Parameters

parser (Parser[TypeVar(_Item_co, covariant=True)]) – Parser that transforms a string into a single value item

Keyword Arguments

help – Help description (autodoc/docstring is used otherwise)
positional – Whether this argument is present in positional arguments
short_flag_name – Short option name (optional)
long_flag_name – Long option name (auto. derived from fieldname by default)
config_key_name – Config key name (auto. derived from fieldname by default)
env_var_name – Environment variable name (forbidden by default)

Return type

Param[Sequence[TypeVar(_Item_co, covariant=True)]]

static append(parser, *, help=None, positional=None, short_flag_name=None, long_flag_name=Derived.KEBAB_CASE, config_key_name=Derived.KEBAB_CASE, env_var_name=None)[source]¶

Returns a newly created argument that joins parsed sequences of values

Parameters

parser (Parser[Sequence[TypeVar(_Item_co, covariant=True)]]) – Parser that transforms a string into a sequence of values

Keyword Arguments

help – Help description (autodoc/docstring is used otherwise)
positional – Whether this argument is present in positional arguments
short_flag_name – Short option name (optional)
long_flag_name – Long option name (auto. derived from fieldname by default)
config_key_name – Config key name (auto. derived from fieldname by default)
env_var_name – Environment variable name (forbidden by default)

Return type

Param[Sequence[TypeVar(_Item_co, covariant=True)]]

__init__(help, short_flag_name, long_flag_name, parser, is_config, is_root_path, collector, default_value, name, positional, config_key_name, env_var_name)¶

static __new__(cls, *args, **kwds)¶

all_flags()¶

Returns a sequence of all forms of command line flags

Return type: Sequence[str]

updated(name, help, env_prefix)¶

Returns a copy of this argument with some data updated from its declaration context

Parameters

self (TypeVar(_Arg, bound= Arg)) –
name (str) – Identifier name
help (str) – Help string (derived from autodoc syntax)
env_prefix (Optional[str]) – Environment prefix

Return type

TypeVar(_Arg, bound= Arg)

Returns

Updated argument

help: Optional[str]¶: Help for the argument

short_flag_name: Optional[str]¶: Short option name, used in command line parsing, prefixed by a single hyphen

long_flag_name: Optional[Union[str, configpile.enums.Derived]]¶

Long option name used in command line argument parsing

It is in general lowercase, prefixed with -- and words are separated by hyphens.,

If set to