GitHub

Argument

API reference for Argument.

class Argument[A]

A positional argument 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) -> Argument[str]
ParameterTypeDescription
namestr

Returns Argument[str]

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

integer

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

Returns Argument[int]

@staticmethod
def integer(name: str) -> Argument[int]:
    return Argument(p.integer(p.ARGUMENT, name))

finite

finite(name) -> Argument[float]

A float (129.99, -1e3); nan and inf are refused.

ParameterTypeDescription
namestr

Returns Argument[float]

@staticmethod
def finite(name: str) -> Argument[float]:
    """A float (``129.99``, ``-1e3``); ``nan`` and ``inf`` are refused."""
    return Argument(p.finite(p.ARGUMENT, name))

date

date(name) -> Argument[datetime]
ParameterTypeDescription
namestr

Returns Argument[datetime]

@staticmethod
def date(name: str) -> Argument[datetime]:
    return Argument(p.date(p.ARGUMENT, name))

choice_with_value

choice_with_value[B](name, choices) -> Argument[B]
ParameterTypeDescription
namestr
choicesSequence[tuple[str, B]]

Returns Argument[B]

@staticmethod
def choice_with_value[B](name: str, choices: Sequence[tuple[str, B]]) -> Argument[B]:
    return Argument(p.choice_with_value(p.ARGUMENT, name, choices))

literals

literals[L: str](name, choices) -> Argument[L]

One of choices; a tuple (("text", "json")) keeps the literal type, a list widens it to str.

ParameterTypeDescription
namestr
choicesSequence[L]

Returns Argument[L]

@staticmethod
def literals[L: str](name: str, choices: Sequence[L]) -> Argument[L]:
    """One of ``choices``; a tuple (``("text", "json")``) keeps the
    literal type, a list widens it to ``str``."""
    return Argument(p.literals(p.ARGUMENT, name, choices))

path

path(name, *, path_type='either', must_exist=False, type_name=None) -> Argument[str]
ParameterTypeDescription
namestr
path_typePathType = 'either'
must_existbool = False
type_namestr | None = None

Returns Argument[str]

@staticmethod
def path(
    name: str,
    *,
    path_type: PathType = "either",
    must_exist: bool = False,
    type_name: str | None = None,
) -> Argument[str]:
    return Argument(
        p.path(
            p.ARGUMENT, name, path_type=path_type, must_exist=must_exist, type_name=type_name
        )
    )

file

file(name, *, must_exist=False) -> Argument[str]
ParameterTypeDescription
namestr
must_existbool = False

Returns Argument[str]

@staticmethod
def file(name: str, *, must_exist: bool = False) -> Argument[str]:
    return Argument(p.file(p.ARGUMENT, name, must_exist=must_exist))

directory

directory(name, *, must_exist=False) -> Argument[str]
ParameterTypeDescription
namestr
must_existbool = False

Returns Argument[str]

@staticmethod
def directory(name: str, *, must_exist: bool = False) -> Argument[str]:
    return Argument(p.directory(p.ARGUMENT, name, must_exist=must_exist))

redacted

redacted(name) -> Argument[Redacted[str]]
ParameterTypeDescription
namestr

Returns Argument[Redacted[str]]

@staticmethod
def redacted(name: str) -> Argument[Redacted[str]]:
    return Argument(p.redacted(p.ARGUMENT, name))

file_text

file_text(name) -> Argument[str]
ParameterTypeDescription
namestr

Returns Argument[str]

@staticmethod
def file_text(name: str) -> Argument[str]:
    return Argument(p.file_text(p.ARGUMENT, name))

file_parse

file_parse(name, *, format=None) -> Argument[object]
ParameterTypeDescription
namestr
formatFileFormat | None = None

Returns Argument[object]

@staticmethod
def file_parse(name: str, *, format: FileFormat | None = None) -> Argument[object]:
    return Argument(p.file_parse(p.ARGUMENT, name, format=format))

file_schema

file_schema[B](name, schema, *, format=None, error_formatter=None) -> Argument[B]
ParameterTypeDescription
namestr
schemaCodec[B, object, Environment, object]
formatFileFormat | None = None
error_formatterCallable[[Issue], str] | None = None

Returns Argument[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,
) -> Argument[B]:
    return Argument(
        p.file_schema(p.ARGUMENT, name, schema, format=format, error_formatter=error_formatter)
    )

never

never() -> Argument[Never]

An argument that never parses.

Returns Argument[Never]

@staticmethod
def never() -> Argument[Never]:
    """An argument that never parses."""
    return Argument(p.never(p.ARGUMENT))

with_description

with_description(description) -> Argument[A]
ParameterTypeDescription
descriptionstr

Returns Argument[A]

def with_description(self, description: str) -> Argument[A]:
    return Argument(p.with_description(self.param, description))

with_metavar

with_metavar(metavar) -> Argument[A]

The value's name in help, in place of its type.

ParameterTypeDescription
metavarstr

Returns Argument[A]

def with_metavar(self, metavar: str) -> Argument[A]:
    """The value's name in help, in place of its type."""
    return Argument(p.with_metavar(self.param, metavar))

optional

optional() -> Argument[A | None]

Returns Argument[A | None]

def optional(self) -> Argument[A | None]:
    return Argument(p.optional(self.param))

with_default

with_default(default: Effect[A, CliError, Environment]) -> Argument[A]
with_default(default: A) -> Argument[A]
with_default[B](default: Effect[B, CliError, Environment]) -> Argument[A | B]
with_default[B](default: B) -> Argument[A | B]

default (or the effect's value) when the argument is missing.

ParameterTypeDescription
default
@overload
def with_default(self, default: Effect[A, CliError, Environment]) -> Argument[A]: ...
@overload
def with_default(self, default: A) -> Argument[A]: ...
@overload
def with_default[B](self, default: Effect[B, CliError, Environment]) -> Argument[A | B]: ...
@overload
def with_default[B](self, default: B) -> Argument[A | B]: ...
def with_default(self, default: Any) -> Argument[Any]:
    """``default`` (or the effect's value) when the argument is missing."""
    return Argument(p.with_default(self.param, default))

with_fallback_config

with_fallback_config[B](config) -> Argument[A | B]
ParameterTypeDescription
configconfig_.Config[B]

Returns Argument[A | B]

def with_fallback_config[B](self, config: config_.Config[B]) -> Argument[A | B]:
    return Argument(p.with_fallback_config(self.param, config))

with_fallback_prompt

with_fallback_prompt[B](prompt) -> Argument[A | B]
ParameterTypeDescription
promptPrompt[B] | Effect[Prompt[B], CliError, Environment]

Returns Argument[A | B]

def with_fallback_prompt[B](
    self, prompt: Prompt[B] | Effect[Prompt[B], CliError, Environment]
) -> Argument[A | B]:
    p.require_prompt(prompt)
    return Argument(p.with_fallback_prompt(self.param, prompt))

variadic

variadic(*, min=None, max=None) -> Argument[tuple[A, ...]]

Every remaining value (between min and max of them).

ParameterTypeDescription
minint | None = None
maxint | None = None

Returns Argument[tuple[A, ...]]

def variadic(
    self, *, min: int | None = None, max: int | None = None
) -> Argument[tuple[A, ...]]:
    """Every remaining value (between ``min`` and ``max`` of them)."""
    return Argument(p.variadic(self.param, min, max))

at_least

at_least(min) -> Argument[tuple[A, ...]]
ParameterTypeDescription
minint

Returns Argument[tuple[A, ...]]

def at_least(self, min: int) -> Argument[tuple[A, ...]]:
    return Argument(p.at_least(self.param, min))

at_most

at_most(max) -> Argument[tuple[A, ...]]
ParameterTypeDescription
maxint

Returns Argument[tuple[A, ...]]

def at_most(self, max: int) -> Argument[tuple[A, ...]]:
    return Argument(p.at_most(self.param, max))

between

between(min, max) -> Argument[tuple[A, ...]]
ParameterTypeDescription
minint
maxint

Returns Argument[tuple[A, ...]]

def between(self, min: int, max: int) -> Argument[tuple[A, ...]]:
    return Argument(p.between(self.param, min, max))

map

map[B](f) -> Argument[B]
ParameterTypeDescription
fCallable[[A], B]

Returns Argument[B]

def map[B](self, f: Callable[[A], B]) -> Argument[B]:
    return Argument(p.map(self.param, f))

map_effect

map_effect[B](f) -> Argument[B]
ParameterTypeDescription
fCallable[[A], Effect[B, CliError, Environment]]

Returns Argument[B]

def map_effect[B](self, f: Callable[[A], Effect[B, CliError, Environment]]) -> Argument[B]:
    return Argument(p.map_effect(self.param, f))

map_try_catch

map_try_catch[B](f, on_error) -> Argument[B]
ParameterTypeDescription
fCallable[[A], B]
on_errorCallable[[Exception], str]

Returns Argument[B]

def map_try_catch[B](
    self, f: Callable[[A], B], on_error: Callable[[Exception], str]
) -> Argument[B]:
    return Argument(p.map_try_catch(self.param, f, on_error))

filter_map

filter_map[B](f, on_none) -> Argument[B]
ParameterTypeDescription
fCallable[[A], Some[B] | None]
on_noneCallable[[A], str]

Returns Argument[B]

def filter_map[B](
    self, f: Callable[[A], Some[B] | None], on_none: Callable[[A], str]
) -> Argument[B]:
    return Argument(p.filter_map(self.param, f, on_none))

filter

filter(predicate, on_false) -> Argument[A]
ParameterTypeDescription
predicateCallable[[A], bool]
on_falseCallable[[A], str]

Returns Argument[A]

def filter(self, predicate: Callable[[A], bool], on_false: Callable[[A], str]) -> Argument[A]:
    return Argument(p.filter(self.param, predicate, on_false))

with_schema

with_schema[B](schema) -> Argument[B]
ParameterTypeDescription
schemaCodec[B, A, Environment, object]

Returns Argument[B]

def with_schema[B](self, schema: Codec[B, A, Environment, object]) -> Argument[B]:
    return Argument(p.with_schema(self.param, schema))

or_else

or_else[B](alternative) -> Argument[A | B]
ParameterTypeDescription
alternativeCallable[[], Argument[B]]

Returns Argument[A | B]

def or_else[B](self, alternative: Callable[[], Argument[B]]) -> Argument[A | B]:
    return Argument(p.or_else(self.param, lambda: alternative().param))

or_else_result

or_else_result[B](alternative) -> Argument[Result[A, B]]
ParameterTypeDescription
alternativeCallable[[], Argument[B]]

Returns Argument[Result[A, B]]

def or_else_result[B](self, alternative: Callable[[], Argument[B]]) -> Argument[Result[A, B]]:
    return Argument(p.or_else_result(self.param, lambda: alternative().param))