GitHub

API reference for param.

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

AttributeTypeDescription
FLAGKind = 'flag'
ARGUMENTKind = 'argument'

Types

TypeDefinitionDescription
Kindtype Kind = Literal['flag', 'argument']
Parsedtype Parsed[A] = Effect[tuple[tuple[str, ...], A], CliError, Environment]

The positional arguments left and the value.

Parsetype Parse[A] = Callable[[ParsedArgs], Parsed[A]]
Alternativetype 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.

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

ParameterTypeDescription
paramParam[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) -> ParamMetadata

Whether the tree is optional or variadic, and its bounds.

ParameterTypeDescription
paramParam[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]
ParameterTypeDescription
paramParam[A]
aliasstr

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]
ParameterTypeDescription
paramParam[A]
descriptionstr

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]
ParameterTypeDescription
paramParam[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]
ParameterTypeDescription
paramParam[A]
metavarstr

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]
ParameterTypeDescription
paramParam[A]
valuestr

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]
ParameterTypeDescription
paramParam[A]
namestr | 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]
ParameterTypeDescription
paramParam[X]
fCallable[[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]
ParameterTypeDescription
paramParam[X]
fCallable[[X], A]
on_errorCallable[[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]
ParameterTypeDescription
paramParam[X]
fCallable[[X], Some[A] | None]
on_noneCallable[[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]
ParameterTypeDescription
paramParam[A]
defaultobject

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]
ParameterTypeDescription
paramParam[A]
configconfig_.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
ParameterTypeDescription
valueobject
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]
ParameterTypeDescription
paramParam[A]
promptPrompt[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, ...]]
ParameterTypeDescription
paramParam[A]
minint | None = None
maxint | 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, ...]]
ParameterTypeDescription
paramParam[A]
minint
maxint

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

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, ...]]
ParameterTypeDescription
paramParam[A]
minint

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]
ParameterTypeDescription
paramParam[A]
alternativeCallable[[], 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]]
ParameterTypeDescription
paramParam[A]
alternativeCallable[[], 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]
ParameterTypeDescription
paramParam[A]
predicateCallable[[A], bool]
on_falseCallable[[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]
ParameterTypeDescription
paramParam[A]
schemaCodec[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]
ParameterTypeDescription
paramParam[X]
fCallable[[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]
ParameterTypeDescription
paramParam[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]
ParameterTypeDescription
kindKind
namestr
primitivePrimitive[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]
ParameterTypeDescription
kindKind
namestr

Returns Param[str]

def string(kind: Kind, name: str) -> Param[str]:
    return Single(kind, name, primitive_.string)

boolean

boolean(kind, name) -> Param[bool]
ParameterTypeDescription
kindKind
namestr

Returns Param[bool]

def boolean(kind: Kind, name: str) -> Param[bool]:
    return Single(kind, name, primitive_.boolean)

integer

integer(kind, name) -> Param[int]
ParameterTypeDescription
kindKind
namestr

Returns Param[int]

def integer(kind: Kind, name: str) -> Param[int]:
    return Single(kind, name, primitive_.integer)

finite

finite(kind, name) -> Param[float]
ParameterTypeDescription
kindKind
namestr

Returns Param[float]

def finite(kind: Kind, name: str) -> Param[float]:
    return Single(kind, name, primitive_.finite)

date

date(kind, name) -> Param[datetime]
ParameterTypeDescription
kindKind
namestr

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

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

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

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

Returns Param[Never]

def never(kind: Kind) -> Param[Never]:
    return Single(kind, "__never__", primitive_.never)