powercli.args

Argument classes that can be used to create flags and positionals.

Module Contents

Classes

Argument

Base class for arguments.

Flag

A flag is usually an optional option that toggles some feature.

Positional

A positional is usually a required value of a command.

VariadicPositional

A positional that accepts a variadic amount of values.

API

class powercli.args.Argument

Base class for arguments.

You should not subclass this class as the parser only knows how to handle powercli.args.Flags and powercli.args.Positionals. Create a subclass of either of those.

identifier: powercli.typedefs.Identifier

‘field(…)’

A unique identifier which can be used for queries and validation.

Defaults to the ID of the created instance.

dependencies: set[powercli.typedefs.Identifier]

‘Factory(…)’

Argument this argument depends on at parse time.

This must be a set of all argument IDs that are required to evaluated the default value and for flags whether it is required. Arguments needed to evaluate whether a flag is allowed are not dependencies.

See also

class powercli.args.Flag

Bases: powercli.args.Argument

A flag is usually an optional option that toggles some feature.

Flags can also accept values, be repeated and much more.

short: str | None

None

A one character long name of the flag.

long: str | None

None

The long name of the flag.

This flag can be of any length including 0 and 1.

short_aliases: set[str]

‘Factory(…)’

A set of aliases for the short name.

long_aliases: set[str]

‘Factory(…)’

A set of aliases for the long name.

short_hidden_aliases: set[str]

‘Factory(…)’

A set of hidden aliases for the short name.

long_hidden_aliases: set[str]

‘Factory(…)’

A set of hidden aliases for the long name.

description: str | None

None

A short one-sentence description of the flag.

long_description: str | None

None

A long description of the flag.

values: collections.abc.Sequence[tuple[str, powercli.typedefs.Converter[powercli.args.Flag.T]] | types.EllipsisType]

‘Factory(…)’

Values the flag takes.

Examples

from powercli import Flag

Flag(
    # ...
    values=[("X", float), ..., ("Y", int), ...],
    # parse as much `float`s as possible, then as much `int`s as possible
)

Tip

Avoid using a flag that accepts a variable amount of string or something similar as it consumes potential flags as well. For example:

from powercli import Flag

Flag(
    # ...
    short="f",
    values=[("X", str), ...],
    # parse as much `float`s as possible
)

If we add this flag to a command and input something like -f --hey --ho, then --hey and --ho will be parsed as values of the flag -f instead of separate flags --hey and --ho.

This may be useful however if you want to consume all arguments without parsing them for example when passing them to an external program. Usually such flag has an empty long name and no short name:

from powercli import Flag

Flag(
    # ...
    short=None,
    long="",
    values=[("ARGS", str), ...],
)
default: powercli.typedefs.WithContext[powercli.args.Flag.FV, powercli.args.Flag.PV, collections.abc.Collection[powercli.args.Flag.T]] | None

None

Default values for the flag.

Examples

from powercli import Flag, Static

Flag(
    # ...
    values=[("X", float), ("Y", int)],
    default=Static([1.5, 42]),
)
method: powercli.methods.Method

‘Factory(…)’

The method of the flag that influences the parsing behavior.

required: powercli.typedefs.WithContext[powercli.args.Flag.FV, powercli.args.Flag.PV, bool | str]

‘Static(…)’

Whether the flag is required.

allowed: powercli.typedefs.WithContext[powercli.args.Flag.FV, powercli.args.Flag.PV, bool | str]

‘Static(…)’

Whether the flag is allowed.

deprecation: powercli.typedefs.WithContext[powercli.args.Flag.FV, powercli.args.Flag.PV, bool | powercli.deprecation.Deprecation | None]

‘Static(…)’

Whether the flag is deprecated.

The flag should not be considered deprecated when required evaluates True. When the user makes use of a flag that is considered deprecated a DeprecationWarning will be emitted.

Examples

from powercli import Flag

Flag(
  identifier="f",
  # ...
  deprecation=lambda ctx: Deprecation("using flag f when flag g is 1 is deprecated") if ctx.value_of("g") == [1] else None
)
category: powercli.category.Category | None

None

The optional category of this flag.

names() → collections.abc.Generator[str, None, None]

Yields all names this flag can be specified with.

visible_short_names() → collections.abc.Generator[str, None, None]

Yields all non-hidden short names this flag can be specified with.

visible_long_names() → collections.abc.Generator[str, None, None]

Yields all non-hidden long names this flag can be specified with.

has_short_name() → bool

Returns True if this flag has a short name.

has_long_name() → bool

Returns True if this flag has a long name.

class powercli.args.Positional

Bases: powercli.args.Argument

A positional is usually a required value of a command.

Positionals cannot be mixed with subcommands.

name: str

None

The name of the positional.

description: str | None

None

A short one-sentence description of the positional.

long_description: str | None

None

A long description of the positional.

into: powercli.typedefs.Converter[powercli.args.Positional.T] | powercli.typedefs.Converter[str]

None

A function that converts the input.

default: powercli.typedefs.WithContext[powercli.args.Positional.FV, powercli.args.Positional.PV, powercli.args.Positional.T] | None

None

A default value for this positional.

property required: bool

Whether the positional is required.

class powercli.args.VariadicPositional

Bases: powercli.args.Positional[powercli.args.VariadicPositional.FV, powercli.args.VariadicPositional.PV, powercli.args.VariadicPositional.T]

A positional that accepts a variadic amount of values.

Positionals cannot be mixed with subcommands.

name: str

None

The name of the positional.

description: str | None

None

A short one-sentence description of the positional.

long_description: str | None

None

A long description of the positional.

into: powercli.typedefs.Converter[powercli.args.VariadicPositional.T] | powercli.typedefs.Converter[str]

None

A function that convert each input value.

min: int

0

The minimum amount of values required.

property required: bool

Whether the positional is required.