class Flag[A]
A flag parsing an A. Read on a parsed Config it is the value.
Attributes#
| Attribute | Type | Description |
|---|---|---|
param | p.Param[A] |
Functions#
__init__#
__init__(param) -> None| Parameter | Type | Description |
|---|---|---|
param | p.Param[A] |
parse#
parse(args) -> p.Parsed[A]| Parameter | Type | Description |
|---|---|---|
args | p.ParsedArgs |
Returns p.Parsed[A]
def parse(self, args: p.ParsedArgs) -> p.Parsed[A]:
return self.param.parse(args)string#
string(name) -> Flag[str]| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[str]
@staticmethod
def string(name: str) -> Flag[str]:
return Flag(p.string(p.FLAG, name))boolean#
boolean(name) -> Flag[bool]| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[bool]
@staticmethod
def boolean(name: str) -> Flag[bool]:
return Flag(p.boolean(p.FLAG, name))integer#
integer(name) -> Flag[int]| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[int]
@staticmethod
def integer(name: str) -> Flag[int]:
return Flag(p.integer(p.FLAG, name))finite#
finite(name) -> Flag[float]A float (129.99, -1e3); nan and inf are refused.
| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[float]
@staticmethod
def finite(name: str) -> Flag[float]:
"""A float (``129.99``, ``-1e3``); ``nan`` and ``inf`` are refused."""
return Flag(p.finite(p.FLAG, name))date#
date(name) -> Flag[datetime]| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[datetime]
@staticmethod
def date(name: str) -> Flag[datetime]:
return Flag(p.date(p.FLAG, name))choice_with_value#
choice_with_value[B](name, choices) -> Flag[B]| Parameter | Type | Description |
|---|---|---|
name | str | |
choices | Sequence[tuple[str, B]] |
Returns Flag[B]
@staticmethod
def choice_with_value[B](name: str, choices: Sequence[tuple[str, B]]) -> Flag[B]:
return Flag(p.choice_with_value(p.FLAG, name, choices))literals#
literals[L: str](name, choices) -> Flag[L]One of choices; a tuple (("text", "json")) keeps the
literal type, a list widens it to str.
| Parameter | Type | Description |
|---|---|---|
name | str | |
choices | Sequence[L] |
Returns Flag[L]
@staticmethod
def literals[L: str](name: str, choices: Sequence[L]) -> Flag[L]:
"""One of ``choices``; a tuple (``("text", "json")``) keeps the
literal type, a list widens it to ``str``."""
return Flag(p.literals(p.FLAG, name, choices))path#
path(name, *, path_type='either', must_exist=False, type_name=None) -> Flag[str]| Parameter | Type | Description |
|---|---|---|
name | str | |
path_type | PathType = 'either' | |
must_exist | bool = False | |
type_name | str | None = None |
Returns Flag[str]
@staticmethod
def path(
name: str,
*,
path_type: PathType = "either",
must_exist: bool = False,
type_name: str | None = None,
) -> Flag[str]:
return Flag(
p.path(p.FLAG, name, path_type=path_type, must_exist=must_exist, type_name=type_name)
)file#
file(name, *, must_exist=False) -> Flag[str]| Parameter | Type | Description |
|---|---|---|
name | str | |
must_exist | bool = False |
Returns Flag[str]
@staticmethod
def file(name: str, *, must_exist: bool = False) -> Flag[str]:
return Flag(p.file(p.FLAG, name, must_exist=must_exist))directory#
directory(name, *, must_exist=False) -> Flag[str]| Parameter | Type | Description |
|---|---|---|
name | str | |
must_exist | bool = False |
Returns Flag[str]
@staticmethod
def directory(name: str, *, must_exist: bool = False) -> Flag[str]:
return Flag(p.directory(p.FLAG, name, must_exist=must_exist))redacted#
redacted(name) -> Flag[Redacted[str]]| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[Redacted[str]]
@staticmethod
def redacted(name: str) -> Flag[Redacted[str]]:
return Flag(p.redacted(p.FLAG, name))file_text#
file_text(name) -> Flag[str]| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[str]
@staticmethod
def file_text(name: str) -> Flag[str]:
return Flag(p.file_text(p.FLAG, name))file_parse#
file_parse(name, *, format=None) -> Flag[object]| Parameter | Type | Description |
|---|---|---|
name | str | |
format | FileFormat | None = None |
Returns Flag[object]
@staticmethod
def file_parse(name: str, *, format: FileFormat | None = None) -> Flag[object]:
return Flag(p.file_parse(p.FLAG, name, format=format))file_schema#
file_schema[B](name, schema, *, format=None, error_formatter=None) -> Flag[B]| Parameter | Type | Description |
|---|---|---|
name | str | |
schema | Codec[B, object, Environment, object] | |
format | FileFormat | None = None | |
error_formatter | Callable[[Issue], str] | None = None |
Returns Flag[B]
@staticmethod
def file_schema[B](
name: str,
schema: Codec[B, object, Environment, object],
*,
format: FileFormat | None = None,
error_formatter: Callable[[Issue], str] | None = None,
) -> Flag[B]:
return Flag(
p.file_schema(p.FLAG, name, schema, format=format, error_formatter=error_formatter)
)key_value_pair#
key_value_pair(name) -> Flag[dict[str, str]]--name key=value given one or more times, merged.
| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[dict[str, str]]
@staticmethod
def key_value_pair(name: str) -> Flag[dict[str, str]]:
"""``--name key=value`` given one or more times, merged."""
return Flag(p.key_value_pair(p.FLAG, name))never#
never() -> Flag[Never]A flag that never parses.
Returns Flag[Never]
@staticmethod
def never() -> Flag[Never]:
"""A flag that never parses."""
return Flag(p.never(p.FLAG))with_alias#
with_alias(alias) -> Flag[A]Another name, given with or without dashes ("f" is -f).
| Parameter | Type | Description |
|---|---|---|
alias | str |
Returns Flag[A]
def with_alias(self, alias: str) -> Flag[A]:
"""Another name, given with or without dashes (``"f"`` is ``-f``)."""
return Flag(p.with_alias(self.param, alias))with_description#
with_description(description) -> Flag[A]| Parameter | Type | Description |
|---|---|---|
description | str |
Returns Flag[A]
def with_description(self, description: str) -> Flag[A]:
return Flag(p.with_description(self.param, description))with_optional_value#
with_optional_value(value) -> Flag[A]The value --name takes when given alone.
| Parameter | Type | Description |
|---|---|---|
value | str |
Returns Flag[A]
def with_optional_value(self, value: str) -> Flag[A]:
"""The value ``--name`` takes when given alone."""
return Flag(p.with_optional_value(self.param, value))with_negation#
with_negation(name) -> Flag[A]A boolean flag's negated name, in place of no-<name>.
| Parameter | Type | Description |
|---|---|---|
name | str |
Returns Flag[A]
def with_negation(self, name: str) -> Flag[A]:
"""A boolean flag's negated name, in place of ``no-<name>``."""
return Flag(p.with_negation(self.param, name))without_negation#
without_negation() -> Flag[A]A boolean flag with no negated form.
Returns Flag[A]
def without_negation(self) -> Flag[A]:
"""A boolean flag with no negated form."""
return Flag(p.with_negation(self.param, False))with_metavar#
with_metavar(metavar) -> Flag[A]The value's name in help, in place of its type.
| Parameter | Type | Description |
|---|---|---|
metavar | str |
Returns Flag[A]
def with_metavar(self, metavar: str) -> Flag[A]:
"""The value's name in help, in place of its type."""
return Flag(p.with_metavar(self.param, metavar))with_hidden#
with_hidden() -> Flag[A]Parsed, but left out of help, completions and suggestions.
Returns Flag[A]
def with_hidden(self) -> Flag[A]:
"""Parsed, but left out of help, completions and suggestions."""
return Flag(p.with_hidden(self.param))optional#
optional() -> Flag[A | None]Returns Flag[A | None]
def optional(self) -> Flag[A | None]:
return Flag(p.optional(self.param))with_default#
with_default(default: Effect[A, CliError, Environment]) -> Flag[A]
with_default(default: A) -> Flag[A]
with_default[B](default: Effect[B, CliError, Environment]) -> Flag[A | B]
with_default[B](default: B) -> Flag[A | B]default (or the effect's value) when the flag is not given.
| Parameter | Type | Description |
|---|---|---|
default |
@overload
def with_default(self, default: Effect[A, CliError, Environment]) -> Flag[A]: ...
@overload
def with_default(self, default: A) -> Flag[A]: ...
@overload
def with_default[B](self, default: Effect[B, CliError, Environment]) -> Flag[A | B]: ...
@overload
def with_default[B](self, default: B) -> Flag[A | B]: ...
def with_default(self, default: Any) -> Flag[Any]:
"""``default`` (or the effect's value) when the flag is not given."""
return Flag(p.with_default(self.param, default))with_fallback_config#
with_fallback_config[B](config) -> Flag[A | B]The config's value when the flag is not given.
| Parameter | Type | Description |
|---|---|---|
config | config_.Config[B] |
Returns Flag[A | B]
def with_fallback_config[B](self, config: config_.Config[B]) -> Flag[A | B]:
"""The config's value when the flag is not given."""
return Flag(p.with_fallback_config(self.param, config))with_fallback_prompt#
with_fallback_prompt[B](prompt) -> Flag[A | B]Asks with prompt when the flag is not given and the terminal
can prompt.
| Parameter | Type | Description |
|---|---|---|
prompt | Prompt[B] | Effect[Prompt[B], CliError, Environment] |
Returns Flag[A | B]
def with_fallback_prompt[B](
self, prompt: Prompt[B] | Effect[Prompt[B], CliError, Environment]
) -> Flag[A | B]:
"""Asks with ``prompt`` when the flag is not given and the terminal
can prompt."""
p.require_prompt(prompt)
return Flag(p.with_fallback_prompt(self.param, prompt))map#
map[B](f) -> Flag[B]| Parameter | Type | Description |
|---|---|---|
f | Callable[[A], B] |
Returns Flag[B]
def map[B](self, f: Callable[[A], B]) -> Flag[B]:
return Flag(p.map(self.param, f))map_effect#
map_effect[B](f) -> Flag[B]| Parameter | Type | Description |
|---|---|---|
f | Callable[[A], Effect[B, CliError, Environment]] |
Returns Flag[B]
def map_effect[B](self, f: Callable[[A], Effect[B, CliError, Environment]]) -> Flag[B]:
return Flag(p.map_effect(self.param, f))map_try_catch#
map_try_catch[B](f, on_error) -> Flag[B]f's result; an exception it raises becomes an invalid value
with on_error's message.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[A], B] | |
on_error | Callable[[Exception], str] |
Returns Flag[B]
def map_try_catch[B](
self, f: Callable[[A], B], on_error: Callable[[Exception], str]
) -> Flag[B]:
"""``f``'s result; an exception it raises becomes an invalid value
with ``on_error``'s message."""
return Flag(p.map_try_catch(self.param, f, on_error))filter_map#
filter_map[B](f, on_none) -> Flag[B]| Parameter | Type | Description |
|---|---|---|
f | Callable[[A], Some[B] | None] | |
on_none | Callable[[A], str] |
Returns Flag[B]
def filter_map[B](
self, f: Callable[[A], Some[B] | None], on_none: Callable[[A], str]
) -> Flag[B]:
return Flag(p.filter_map(self.param, f, on_none))filter#
filter(predicate, on_false) -> Flag[A]| Parameter | Type | Description |
|---|---|---|
predicate | Callable[[A], bool] | |
on_false | Callable[[A], str] |
Returns Flag[A]
def filter(self, predicate: Callable[[A], bool], on_false: Callable[[A], str]) -> Flag[A]:
return Flag(p.filter(self.param, predicate, on_false))with_schema#
with_schema[B](schema) -> Flag[B]The value decoded by schema.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[B, A, Environment, object] |
Returns Flag[B]
def with_schema[B](self, schema: Codec[B, A, Environment, object]) -> Flag[B]:
"""The value decoded by ``schema``."""
return Flag(p.with_schema(self.param, schema))at_least#
at_least(min) -> Flag[tuple[A, ...]]Given min or more times.
| Parameter | Type | Description |
|---|---|---|
min | int |
Returns Flag[tuple[A, ...]]
def at_least(self, min: int) -> Flag[tuple[A, ...]]:
"""Given ``min`` or more times."""
return Flag(p.at_least(self.param, min))at_most#
at_most(max) -> Flag[tuple[A, ...]]| Parameter | Type | Description |
|---|---|---|
max | int |
Returns Flag[tuple[A, ...]]
def at_most(self, max: int) -> Flag[tuple[A, ...]]:
return Flag(p.at_most(self.param, max))between#
between(min, max) -> Flag[tuple[A, ...]]| Parameter | Type | Description |
|---|---|---|
min | int | |
max | int |
Returns Flag[tuple[A, ...]]
def between(self, min: int, max: int) -> Flag[tuple[A, ...]]:
return Flag(p.between(self.param, min, max))or_else#
or_else[B](alternative) -> Flag[A | B]This flag, or else the alternative's (both are recognized).
| Parameter | Type | Description |
|---|---|---|
alternative | Callable[[], Flag[B]] |
Returns Flag[A | B]
def or_else[B](self, alternative: Callable[[], Flag[B]]) -> Flag[A | B]:
"""This flag, or else the alternative's (both are recognized)."""
return Flag(p.or_else(self.param, lambda: alternative().param))or_else_result#
or_else_result[B](alternative) -> Flag[Result[A, B]]Ok with this flag's value, or else Err with the
alternative's.
| Parameter | Type | Description |
|---|---|---|
alternative | Callable[[], Flag[B]] |
Returns Flag[Result[A, B]]
def or_else_result[B](self, alternative: Callable[[], Flag[B]]) -> Flag[Result[A, B]]:
"""``Ok`` with this flag's value, or else ``Err`` with the
alternative's."""
return Flag(p.or_else_result(self.param, lambda: alternative().param))On This Page
AttributesFunctions__init__parsestringbooleanintegerfinitedatechoice_with_valueliteralspathfiledirectoryredactedfile_textfile_parsefile_schemakey_value_pairneverwith_aliaswith_descriptionwith_optional_valuewith_negationwithout_negationwith_metavarwith_hiddenoptionalwith_defaultwith_fallback_configwith_fallback_promptmapmap_effectmap_try_catchfilter_mapfilterwith_schemaat_leastat_mostbetweenor_elseor_else_result