The parameter tree behind flags and arguments (Effect's Param).
A Param[A] parses an A out of a command line's ParsedArgs: the
flag values by flag name and the positional arguments left. Single is
one named flag or argument; Mapped, Transformed, Optional and
Variadic wrap it. Programs use Flag and Argument, which are
typed views of these trees; help, completions and the parser read the
Single nodes through extract_single_params.
Values#
| Attribute | Type | Description |
|---|---|---|
FLAG | Kind = 'flag' | |
ARGUMENT | Kind = 'argument' |
Types#
| Type | Definition | Description |
|---|---|---|
Kind | type Kind = Literal['flag', 'argument'] | |
Parsed | type Parsed[A] = Effect[tuple[tuple[str, ...], A], CliError, Environment] | The positional arguments left and the value. |
Parse | type Parse[A] = Callable[[ParsedArgs], Parsed[A]] | |
Alternative | type Alternative = Callable[[], Param[Any]] |
Classes#
Functions#
extract_single_params#
extract_single_params(param) -> list[Single[Any]]Every Single in the tree, alternatives included, in order.
| Parameter | Type | Description |
|---|---|---|
param | Param[Any] |
Returns list[Single[Any]]
def extract_single_params(param: Param[Any]) -> list[Single[Any]]:
"""Every ``Single`` in the tree, alternatives included, in order."""
return param.singles()get_underlying_single_or_throw#
get_underlying_single_or_throw(param) -> Single[Any]The tree's one Single; raises ValueError for none or several.
| Parameter | Type | Description |
|---|---|---|
param | Param[Any] |
Returns Single[Any]
def get_underlying_single_or_throw(param: Param[Any]) -> Single[Any]:
"""The tree's one ``Single``; raises ``ValueError`` for none or several."""
singles = extract_single_params(param)
if not singles:
raise ValueError("No Single param found in param structure")
if len(singles) > 1:
raise ValueError(f"Multiple Single params found: {', '.join(s.name for s in singles)}")
return singles[0]get_param_metadata#
get_param_metadata(param) -> ParamMetadataWhether the tree is optional or variadic, and its bounds.
| Parameter | Type | Description |
|---|---|---|
param | Param[Any] |
Returns ParamMetadata
def get_param_metadata(param: Param[Any]) -> ParamMetadata:
"""Whether the tree is optional or variadic, and its bounds."""
return param.metadata()with_alias#
with_alias[A](param, alias) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
alias | str |
Returns Param[A]
def with_alias[A](param: Param[A], alias: str) -> Param[A]:
stripped = _DASHES.sub("", alias)
return param.map_singles(lambda s: replace(s, aliases=(*s.aliases, stripped)))with_description#
with_description[A](param, description) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
description | str |
Returns Param[A]
def with_description[A](param: Param[A], description: str) -> Param[A]:
return param.map_singles(lambda s: replace(s, description=description))with_hidden#
with_hidden[A](param) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] |
Returns Param[A]
def with_hidden[A](param: Param[A]) -> Param[A]:
return param.map_singles(lambda s: replace(s, hidden=True))with_metavar#
with_metavar[A](param, metavar) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
metavar | str |
Returns Param[A]
def with_metavar[A](param: Param[A], metavar: str) -> Param[A]:
return param.map_singles(lambda s: replace(s, type_name=metavar))with_optional_value#
with_optional_value[A](param, value) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
value | str |
Returns Param[A]
def with_optional_value[A](param: Param[A], value: str) -> Param[A]:
return param.map_singles(lambda s: replace(s, optional_value=value))with_negation#
with_negation[A](param, name) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
name | str | Literal[False] |
Returns Param[A]
def with_negation[A](param: Param[A], name: str | Literal[False]) -> Param[A]:
return param.map_singles(lambda s: replace(s, negation=name))map_effect#
map_effect[X, A](param, f) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[X] | |
f | Callable[[X], Effect[A, CliError, Environment]] |
Returns Param[A]
def map_effect[X, A](
param: Param[X], f: Callable[[X], Effect[A, CliError, Environment]]
) -> Param[A]:
def make(parse: Parse[X], _: object) -> Parse[A]:
def run(args: ParsedArgs) -> Parsed[A]:
return parse(args).flat_map(
lambda parsed: f(parsed[1]).map(lambda value: (parsed[0], value))
)
return run
return Transformed(param, make)map_try_catch#
map_try_catch[X, A](param, f, on_error) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[X] | |
f | Callable[[X], A] | |
on_error | Callable[[Exception], str] |
Returns Param[A]
def map_try_catch[X, A](
param: Param[X], f: Callable[[X], A], on_error: Callable[[Exception], str]
) -> Param[A]:
single = get_underlying_single_or_throw(param)
def apply(value: X) -> Effect[A, CliError, Environment]:
try:
return succeed(f(value))
except Exception as error:
return fail(_invalid(single, value, on_error(error)))
return map_effect(param, apply)filter_map#
filter_map[X, A](param, f, on_none) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[X] | |
f | Callable[[X], Some[A] | None] | |
on_none | Callable[[X], str] |
Returns Param[A]
def filter_map[X, A](
param: Param[X], f: Callable[[X], Some[A] | None], on_none: Callable[[X], str]
) -> Param[A]:
def apply(value: X) -> Effect[A, CliError, Environment]:
result = f(value)
if result is not None:
return succeed(result.value)
return fail(_invalid(get_underlying_single_or_throw(param), value, on_none(value)))
return map_effect(param, apply)with_default#
with_default[A](param, default) -> Param[Any]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
default | object |
Returns Param[Any]
def with_default[A](param: Param[A], default: object) -> Param[Any]:
optional = Optional(param)
if isinstance(default, Effect):
fallback = cast("Effect[Any, CliError, Environment]", default)
return map_effect(optional, lambda value: fallback if value is None else succeed(value))
return Mapped(optional, lambda value: default if value is None else value)with_fallback_config#
with_fallback_config[A](param, config) -> Param[Any]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
config | config_.Config[Any] |
Returns Param[Any]
def with_fallback_config[A](param: Param[A], config: config_.Config[Any]) -> Param[Any]:
def recover(error: MissingOption | MissingArgument, args: ParsedArgs) -> Parsed[Any]:
name, kind = _missing_name(error)
return (
config_.option(config)
.map_error(
lambda config_error: cast(
"CliError", InvalidValue(name, "config", config_error.message, kind)
)
)
.flat_map(
lambda found: (
succeed((args.arguments, found.value))
if isinstance(found, Some)
else cast("Parsed[Any]", fail(error))
)
)
)
return _on_missing(param, recover)require_prompt#
require_prompt(value) -> None| Parameter | Type | Description |
|---|---|---|
value | object |
def require_prompt(value: object) -> None:
from pyfect.cli import prompt as prompt_
if not isinstance(value, (prompt_.Prompt, EffectBase)):
hint = "to ask, pass a Prompt such as prompt.string(message)"
raise TypeError(wrong_argument(value, "prompt", "an Effect or a Prompt", hint))with_fallback_prompt#
with_fallback_prompt[A](param, prompt) -> Param[Any]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
prompt | Prompt[Any] | Effect[Prompt[Any], CliError, Environment] |
Returns Param[Any]
def with_fallback_prompt[A](
param: Param[A], prompt: Prompt[Any] | Effect[Prompt[Any], CliError, Environment]
) -> Param[Any]:
from pyfect.cli import prompt as prompt_
require_prompt(prompt)
def recover(error: MissingOption | MissingArgument, args: ParsedArgs) -> Parsed[Any]:
def body():
capabilities = yield from TerminalCapabilities()
if not capabilities.can_prompt:
return (yield from fail(error))
built = prompt if isinstance(prompt, prompt_.Prompt) else (yield from prompt)
value = yield from prompt_.run(built).catch_all(
lambda _: cast("Effect[Never, CliError]", fail(error))
)
return args.arguments, value
return gen(body)
return _on_missing(param, recover)variadic#
variadic[A](param, min=None, max=None) -> Param[tuple[A, ...]]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
min | int | None = None | |
max | int | None = None |
Returns Param[tuple[A, ...]]
def variadic[A](
param: Param[A], min: int | None = None, max: int | None = None
) -> Param[tuple[A, ...]]:
get_underlying_single_or_throw(param)
return Variadic(param, min, max)between#
between[A](param, min, max) -> Param[tuple[A, ...]]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
min | int | |
max | int |
Returns Param[tuple[A, ...]]
def between[A](param: Param[A], min: int, max: int) -> Param[tuple[A, ...]]:
if min < 0:
raise ValueError("between: min must be non-negative")
if max < min:
raise ValueError("between: max must be greater than or equal to min")
return variadic(param, min, max)at_most#
at_most[A](param, max) -> Param[tuple[A, ...]]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
max | int |
Returns Param[tuple[A, ...]]
def at_most[A](param: Param[A], max: int) -> Param[tuple[A, ...]]:
if max < 0:
raise ValueError("atMost: max must be non-negative")
return variadic(param, max=max)at_least#
at_least[A](param, min) -> Param[tuple[A, ...]]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
min | int |
Returns Param[tuple[A, ...]]
def at_least[A](param: Param[A], min: int) -> Param[tuple[A, ...]]:
if min < 0:
raise ValueError("atLeast: min must be non-negative")
return variadic(param, min=min)or_else#
or_else[A, B](param, alternative) -> Param[A | B]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
alternative | Callable[[], Param[B]] |
Returns Param[A | B]
def or_else[A, B](param: Param[A], alternative: Callable[[], Param[B]]) -> Param[A | B]:
def make(parse: Parse[A], alternatives: tuple[Callable[[], Parse[Any]], ...]) -> Parse[A | B]:
def run(args: ParsedArgs) -> Parsed[A | B]:
return parse(args).catch_all(lambda _: alternatives[0]()(args))
return run
return Transformed(param, make, (alternative,))or_else_result#
or_else_result[A, B](param, alternative) -> Param[Result[A, B]]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
alternative | Callable[[], Param[B]] |
Returns Param[Result[A, B]]
def or_else_result[A, B](
param: Param[A], alternative: Callable[[], Param[B]]
) -> Param[Result[A, B]]:
def make(
parse: Parse[A], alternatives: tuple[Callable[[], Parse[Any]], ...]
) -> Parse[Result[A, B]]:
def run(args: ParsedArgs) -> Parsed[Result[A, B]]:
return (
parse(args)
.map(lambda parsed: (parsed[0], cast("Result[A, B]", Ok(parsed[1]))))
.catch_all(
lambda _: alternatives[0]()(args).map(
lambda parsed: (parsed[0], cast("Result[A, B]", Err(parsed[1])))
)
)
)
return run
return Transformed(param, make, (alternative,))filter#
filter[A](param, predicate, on_false) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
predicate | Callable[[A], bool] | |
on_false | Callable[[A], str] |
Returns Param[A]
def filter[A](
param: Param[A], predicate: Callable[[A], bool], on_false: Callable[[A], str]
) -> Param[A]:
return filter_map(param, lambda value: Some(value) if predicate(value) else None, on_false)with_schema#
with_schema[A, B](param, schema) -> Param[B]| Parameter | Type | Description |
|---|---|---|
param | Param[A] | |
schema | Codec[B, A, Environment, object] |
Returns Param[B]
def with_schema[A, B](param: Param[A], schema: Codec[B, A, Environment, object]) -> Param[B]:
decode = S.decode_unknown_effect(schema)
def apply(value: A) -> Effect[B, CliError, Environment]:
single = get_underlying_single_or_throw(param)
return decode(value).map_error(
lambda error: cast(
"CliError",
InvalidValue(
single.name,
_js_string(value),
f"Schema validation failed: {error.message}",
single.kind,
),
)
)
return map_effect(param, apply)map#
map[X, A](param, f) -> Param[A]| Parameter | Type | Description |
|---|---|---|
param | Param[X] | |
f | Callable[[X], A] |
Returns Param[A]
def map[X, A](param: Param[X], f: Callable[[X], A]) -> Param[A]:
return Mapped(param, f)optional#
optional[A](param) -> Param[A | None]| Parameter | Type | Description |
|---|---|---|
param | Param[A] |
Returns Param[A | None]
def optional[A](param: Param[A]) -> Param[A | None]:
return Optional(param)single#
single[A](kind, name, primitive) -> Param[A]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
primitive | Primitive[A] |
Returns Param[A]
def single[A](kind: Kind, name: str, primitive: Primitive[A]) -> Param[A]:
return Single(kind, name, primitive)string#
string(kind, name) -> Param[str]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[str]
def string(kind: Kind, name: str) -> Param[str]:
return Single(kind, name, primitive_.string)boolean#
boolean(kind, name) -> Param[bool]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[bool]
def boolean(kind: Kind, name: str) -> Param[bool]:
return Single(kind, name, primitive_.boolean)integer#
integer(kind, name) -> Param[int]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[int]
def integer(kind: Kind, name: str) -> Param[int]:
return Single(kind, name, primitive_.integer)finite#
finite(kind, name) -> Param[float]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[float]
def finite(kind: Kind, name: str) -> Param[float]:
return Single(kind, name, primitive_.finite)date#
date(kind, name) -> Param[datetime]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[datetime]
def date(kind: Kind, name: str) -> Param[datetime]:
return Single(kind, name, primitive_.date_)choice_with_value#
choice_with_value[A](kind, name, choices) -> Param[A]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
choices | Sequence[tuple[str, A]] |
Returns Param[A]
def choice_with_value[A](kind: Kind, name: str, choices: Sequence[tuple[str, A]]) -> Param[A]:
return Single(kind, name, primitive_.choice(choices))literals#
literals[L: str](kind, name, choices) -> Param[L]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
choices | Sequence[L] |
Returns Param[L]
def literals[L: str](kind: Kind, name: str, choices: Sequence[L]) -> Param[L]:
return choice_with_value(kind, name, [(value, value) for value in choices])path#
path(kind, name, *, path_type='either', must_exist=False, type_name=None) -> Param[str]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
path_type | PathType = 'either' | |
must_exist | bool = False | |
type_name | str | None = None |
Returns Param[str]
def path(
kind: Kind,
name: str,
*,
path_type: PathType = "either",
must_exist: bool = False,
type_name: str | None = None,
) -> Param[str]:
return Single(kind, name, primitive_.path(path_type, must_exist), type_name=type_name)directory#
directory(kind, name, *, must_exist=False) -> Param[str]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
must_exist | bool = False |
Returns Param[str]
def directory(kind: Kind, name: str, *, must_exist: bool = False) -> Param[str]:
return path(kind, name, path_type="directory", must_exist=must_exist, type_name="directory")file#
file(kind, name, *, must_exist=False) -> Param[str]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
must_exist | bool = False |
Returns Param[str]
def file(kind: Kind, name: str, *, must_exist: bool = False) -> Param[str]:
return path(kind, name, path_type="file", must_exist=must_exist, type_name="file")redacted#
redacted(kind, name) -> Param[Redacted[str]]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[Redacted[str]]
def redacted(kind: Kind, name: str) -> Param[Redacted[str]]:
return Single(kind, name, primitive_.redacted)file_text#
file_text(kind, name) -> Param[str]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[str]
def file_text(kind: Kind, name: str) -> Param[str]:
return Single(kind, name, primitive_.file_text)file_parse#
file_parse(kind, name, *, format=None) -> Param[object]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
format | FileFormat | None = None |
Returns Param[object]
def file_parse(kind: Kind, name: str, *, format: FileFormat | None = None) -> Param[object]:
return Single(kind, name, primitive_.file_parse(format))file_schema#
file_schema[A](kind, name, schema, *, format=None, error_formatter=None) -> Param[A]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str | |
schema | Codec[A, object, Environment, object] | |
format | FileFormat | None = None | |
error_formatter | Callable[[Issue], str] | None = None |
Returns Param[A]
def file_schema[A](
kind: Kind,
name: str,
schema: Codec[A, object, Environment, object],
*,
format: FileFormat | None = None,
error_formatter: Callable[[Issue], str] | None = None,
) -> Param[A]:
return Single(
kind,
name,
primitive_.file_schema(schema, format=format, error_formatter=error_formatter),
)key_value_pair#
key_value_pair(kind, name) -> Param[dict[str, str]]| Parameter | Type | Description |
|---|---|---|
kind | Kind | |
name | str |
Returns Param[dict[str, str]]
def key_value_pair(kind: Kind, name: str) -> Param[dict[str, str]]:
def merge(pairs: tuple[dict[str, str], ...]) -> dict[str, str]:
return {key: value for pair in pairs for key, value in pair.items()}
return Mapped(variadic(Single(kind, name, primitive_.key_value_pair), min=1), merge)never#
never(kind) -> Param[Never]| Parameter | Type | Description |
|---|---|---|
kind | Kind |
Returns Param[Never]
def never(kind: Kind) -> Param[Never]:
return Single(kind, "__never__", primitive_.never)On This Page
ValuesTypesClassesFunctionsextract_single_paramsget_underlying_single_or_throwget_param_metadatawith_aliaswith_descriptionwith_hiddenwith_metavarwith_optional_valuewith_negationmap_effectmap_try_catchfilter_mapwith_defaultwith_fallback_configrequire_promptwith_fallback_promptvariadicbetweenat_mostat_leastor_elseor_else_resultfilterwith_schemamapoptionalsinglestringbooleanintegerfinitedatechoice_with_valueliteralspathdirectoryfileredactedfile_textfile_parsefile_schemakey_value_pairnever