GitHub

API reference for Flag.

class Flag[A]

A flag parsing an A. Read on a parsed Config it is the value.

Attributes

AttributeTypeDescription
paramp.Param[A]

Functions

__init__

__init__(param) -> None
ParameterTypeDescription
paramp.Param[A]

parse

parse(args) -> p.Parsed[A]
ParameterTypeDescription
argsp.ParsedArgs

Returns p.Parsed[A]

def parse(self, args: p.ParsedArgs) -> p.Parsed[A]:
    return self.param.parse(args)

string

string(name) -> Flag[str]
ParameterTypeDescription
namestr

Returns Flag[str]

@staticmethod
def string(name: str) -> Flag[str]:
    return Flag(p.string(p.FLAG, name))

boolean

boolean(name) -> Flag[bool]
ParameterTypeDescription
namestr

Returns Flag[bool]

@staticmethod
def boolean(name: str) -> Flag[bool]:
    return Flag(p.boolean(p.FLAG, name))

integer

integer(name) -> Flag[int]
ParameterTypeDescription
namestr

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.

ParameterTypeDescription
namestr

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]
ParameterTypeDescription
namestr

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]
ParameterTypeDescription
namestr
choicesSequence[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.

ParameterTypeDescription
namestr
choicesSequence[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]
ParameterTypeDescription
namestr
path_typePathType = 'either'
must_existbool = False
type_namestr | 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]
ParameterTypeDescription
namestr
must_existbool = 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]
ParameterTypeDescription
namestr
must_existbool = 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]]
ParameterTypeDescription
namestr

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]
ParameterTypeDescription
namestr

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]
ParameterTypeDescription
namestr
formatFileFormat | 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]
ParameterTypeDescription
namestr
schemaCodec[B, object, Environment, object]
formatFileFormat | None = None
error_formatterCallable[[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.

ParameterTypeDescription
namestr

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).

ParameterTypeDescription
aliasstr

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]
ParameterTypeDescription
descriptionstr

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.

ParameterTypeDescription
valuestr

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>.

ParameterTypeDescription
namestr

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.

ParameterTypeDescription
metavarstr

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.

ParameterTypeDescription
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.

ParameterTypeDescription
configconfig_.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.

ParameterTypeDescription
promptPrompt[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]
ParameterTypeDescription
fCallable[[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]
ParameterTypeDescription
fCallable[[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.

ParameterTypeDescription
fCallable[[A], B]
on_errorCallable[[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]
ParameterTypeDescription
fCallable[[A], Some[B] | None]
on_noneCallable[[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]
ParameterTypeDescription
predicateCallable[[A], bool]
on_falseCallable[[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.

ParameterTypeDescription
schemaCodec[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.

ParameterTypeDescription
minint

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, ...]]
ParameterTypeDescription
maxint

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, ...]]
ParameterTypeDescription
minint
maxint

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).

ParameterTypeDescription
alternativeCallable[[], 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.

ParameterTypeDescription
alternativeCallable[[], 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))