params - Command Line Parameters Modelling

Parameter manipulation module.

This module provides Params which can be used to model any data structure that is meant to represent any command line parameters.

FnPtr

Type for a function taking one argument.

alias of Callable[[Any], Any]

Switch

Type for a switch parameter.

alias of Literal[True, None]

YesNoSwitch

Type for a yes/no switch parameter.

alias of Literal[True, False, None]

modify_str(*funcs: Callable[[Any], Any]) → Callable[[T], T]

Class decorator modifying the __str__ method with a function created from its arguments.

The FnPtrs fed to the decorator are executed from left to right in the arguments list order.

Parameters:: *funcs (Callable[[Any], Any]) – The functions to chain from left to right.
Returns:: The decorator.
Return type:: Callable[[T], T]

Example

@convert_str(hex_from_flag_value)
class BitMask(enum.Flag):
    A = auto()
    B = auto()

will allow BitMask to render as a hexadecimal value.

comma_separated(values: Iterable[Any]) → str

Converts an iterable into a comma-separated string.

Parameters:: values (Iterable[Any]) – An iterable of objects.
Returns:: A comma-separated list of stringified values.
Return type:: str

bracketed(value: str) → str

Adds round brackets to the input.

Parameters:: value (str) – Any string.
Returns:: A string surrounded by round brackets.
Return type:: str

str_from_flag_value(flag: Flag) → str

Returns the value from a enum.Flag as a string.

Parameters:: flag (Flag) – An instance of Flag.
Returns:: The stringified value of the given flag.
Return type:: str

hex_from_flag_value(flag: Flag) → str

Returns the value from a enum.Flag converted to hexadecimal.

Parameters:: flag (Flag) – An instance of Flag.
Returns:: The value of the given flag in hexadecimal representation.
Return type:: str

class ParamsModifier

Bases: TypedDict

Params modifiers dict compatible with the dataclasses.field() metadata parameter.

Params_short: str

Params_long: str

Params_multiple: bool

Params_convert_value: Reversible[Callable[[Any], Any]]

class Params

Bases: object

Dataclass that renders its fields into command line arguments.

The parameter name is taken from the field name by default. The following:

name: str | None = "value"

is rendered as --name=value.

Through dataclasses.field() the resulting parameter can be manipulated by applying this class’ metadata modifier functions. These return regular dictionaries which can be combined together using the pipe (OR) operator, as used in the example for multiple().

To use fields as switches, set the value to True to render them. If you use a yes/no switch you can also set False which would render a switch prefixed with --no-. Examples:

interactive: Switch = True  # renders --interactive
numa: YesNoSwitch   = False # renders --no-numa

Setting None will prevent it from being rendered. The Switch type alias is provided for regular switches, whereas YesNoSwitch is offered for yes/no ones.

An instance of a dataclass inheriting Params can also be assigned to an attribute, this helps with grouping parameters together. The attribute holding the dataclass will be ignored and the latter will just be rendered as expected.

static short(name: str) → ParamsModifier

Overrides any parameter name with the given short option.

Parameters:

name (str) – The short parameter name.

Returns:

A dictionary for the dataclasses.field metadata argument containing: the parameter short name modifier.

Return type:

ParamsModifier

Example

logical_cores: str | None = field(default="1-4", metadata=Params.short("l"))

will render as -l=1-4 instead of --logical-cores=1-4.

static long(name: str) → ParamsModifier

Overrides the inferred parameter name to the specified one.

Parameters:

name (str) – The long parameter name.

Returns:

A dictionary for the dataclasses.field metadata argument containing: the parameter long name modifier.

Return type:

ParamsModifier

Example

x_name: str | None = field(default="y", metadata=Params.long("x"))

will render as --x=y, but the field is accessed and modified through x_name.

static multiple() → ParamsModifier

Specifies that this parameter is set multiple times. The parameter type must be a list.

Returns:

A dictionary for the dataclasses.field metadata argument containing: the multiple parameters modifier.

Return type:

ParamsModifier

Example

ports: list[int] | None = field(
    default_factory=lambda: [0, 1, 2],
    metadata=Params.multiple() | Params.long("port")
)

will render as --port=0 --port=1 --port=2.

static convert_value(*funcs: Callable[[Any], Any]) → ParamsModifier

Takes in a variable number of functions to convert the value text representation.

Functions can be chained together, executed from left to right in the arguments list order.

Parameters:

*funcs (Callable[[Any], Any]) – The functions to chain from left to right.

Returns:

A dictionary for the dataclasses.field metadata argument containing: the convert value modifier.

Return type:

ParamsModifier

Example

hex_bitmask: int | None = field(
    default=0b1101,
    metadata=Params.convert_value(hex) | Params.long("mask")
)

will render as --mask=0xd.

append_str(text: str) → None

Appends a string at the end of the string representation.

Parameters:: text (str) – Any text to append at the end of the parameters string representation.

classmethod from_str(text: str) → typing_extensions.Self

Creates a plain Params object from a string.

Parameters:: text (str) – The string parameters.
Returns:: A new plain instance of Params.
Return type:: typing_extensions.Self

__init__() → None