GitHub

API reference for command.

Commands and running them (Effect's Command).

make(name, Config, handler) builds a command; with_subcommands, with_shared_flags and the other methods refine it; run parses the process arguments (from Stdio) and runs the chosen handler, showing help and errors the way Effect's CLI does::

class Greet(Config):
    name = Argument.string("name")

greet = command.make("greet", Greet, lambda c: console.log(f"Hello, {c.name}"))
program = command.run(greet, version="1.0.0")

Combinators that remove services from a command's requirements are curried, for .pipe: provide, provide_sync, provide_effect and with_global_flags.

Re-exports

Types

TypeDefinitionDescription
AnyCommandtype AnyCommand = Command[Any, Any, Any, Any]
Exampletype Example = ExampleDoc

Classes

Functions

provide

provide[In, LA, LE = Never, LR = Never](layer: Callable[[In], Layer[LA, LE, LR]], *, local: bool = False) -> _Provide[In, LA, LE, LR]
provide[LA, LE = Never, LR = Never](layer: Layer[LA, LE, LR], *, local: bool = False) -> _ProvideAny[LA, LE, LR]

Provides layer (or the layer built from the parsed config) to the handler: command.pipe(provide(database_layer)).

ParameterTypeDescription
layer
local= False
@overload
def provide[In, LA, LE = Never, LR = Never](
    layer: Callable[[In], Layer[LA, LE, LR]], *, local: bool = False
) -> _Provide[In, LA, LE, LR]: ...
@overload
def provide[LA, LE = Never, LR = Never](
    layer: Layer[LA, LE, LR], *, local: bool = False
) -> _ProvideAny[LA, LE, LR]: ...
def provide(
    layer: Layer[Any, Any, Any] | Callable[[Any], Layer[Any, Any, Any]], *, local: bool = False
) -> _Provide[Any, Any, Any, Any] | _ProvideAny[Any, Any, Any]:
    """Provides ``layer`` (or the layer built from the parsed config) to
    the handler: ``command.pipe(provide(database_layer))``."""

    def wrap(handler: Effect[None, Any, Any], value: Any) -> Effect[None, Any, Any]:
        built = layer(value) if callable(layer) else layer
        return handler.pipe(layer_provide(built, local=local))

    return _Provide(wrap) if callable(layer) else _ProvideAny(wrap)

provide_sync

provide_sync[S, T, In](tag: TagLike[S, T], service: Callable[[In], S]) -> _Provide[In, T, Never, Never]
provide_sync[S, T](tag: TagLike[S, T], service: S) -> _ProvideAny[T, Never, Never]

Provides service (or the one built from the parsed config) as tag's service to the handler.

ParameterTypeDescription
tag
service
@overload
def provide_sync[S, T, In](
    tag: TagLike[S, T], service: Callable[[In], S]
) -> _Provide[In, T, Never, Never]: ...
@overload
def provide_sync[S, T](tag: TagLike[S, T], service: S) -> _ProvideAny[T, Never, Never]: ...
def provide_sync(
    tag: TagLike[Any, Any], service: object
) -> _Provide[Any, Any, Never, Never] | _ProvideAny[Any, Never, Never]:
    """Provides ``service`` (or the one built from the parsed config) as
    ``tag``'s service to the handler."""

    def wrap(handler: Effect[None, Any, Any], value: Any) -> Effect[None, Any, Any]:
        built = service(value) if callable(service) else service
        return handler.pipe(provide_service(tag, built))

    return _Provide(wrap) if callable(service) else _ProvideAny(wrap)

provide_effect

provide_effect[S, T, In, E2 = Never, R2 = Never](tag: TagLike[S, T], effect: Callable[[In], Effect[S, E2, R2]]) -> _Provide[In, T, E2, R2]
provide_effect[S, T, E2 = Never, R2 = Never](tag: TagLike[S, T], effect: Effect[S, E2, R2]) -> _ProvideAny[T, E2, R2]

Runs effect (or the one built from the parsed config) and provides its value as tag's service to the handler.

ParameterTypeDescription
tag
effect
@overload
def provide_effect[S, T, In, E2 = Never, R2 = Never](
    tag: TagLike[S, T], effect: Callable[[In], Effect[S, E2, R2]]
) -> _Provide[In, T, E2, R2]: ...
@overload
def provide_effect[S, T, E2 = Never, R2 = Never](
    tag: TagLike[S, T], effect: Effect[S, E2, R2]
) -> _ProvideAny[T, E2, R2]: ...
def provide_effect(
    tag: TagLike[Any, Any], effect: Effect[Any, Any, Any] | Callable[[Any], Effect[Any, Any, Any]]
) -> _Provide[Any, Any, Any, Any] | _ProvideAny[Any, Any, Any]:
    """Runs ``effect`` (or the one built from the parsed config) and
    provides its value as ``tag``'s service to the handler."""

    def wrap(handler: Effect[None, Any, Any], value: Any) -> Effect[None, Any, Any]:
        acquire = effect(value) if callable(effect) else effect
        return acquire.flat_map(lambda built: handler.pipe(provide_service(tag, built)))

    return _Provide(wrap) if callable(effect) else _ProvideAny(wrap)

provide_effect_discard

provide_effect_discard[In, C, EE, RR](command, effect) -> Command[In, C, EE, RR]

Runs effect (or the one built from the parsed config) before the handler. Removes nothing, so it takes the command directly.

ParameterTypeDescription
commandCommand[In, C, EE, RR]
effectEffect[object, EE, RR] | Callable[[In], Effect[object, EE, RR]]

Returns Command[In, C, EE, RR]

def provide_effect_discard[In, C, EE, RR](
    command: Command[In, C, EE, RR],
    effect: Effect[object, EE, RR] | Callable[[In], Effect[object, EE, RR]],
) -> Command[In, C, EE, RR]:
    """Runs ``effect`` (or the one built from the parsed config) before the
    handler. Removes nothing, so it takes the command directly."""

    def wrap(handler: Effect[None, Any, Any], value: Any) -> Effect[None, Any, Any]:
        before = effect(value) if callable(effect) else effect
        return before.and_then(handler)

    return _map_handle(command, wrap)

with_global_flags

with_global_flags[T = Never](*flags) -> _WithGlobalFlags[T]

Global flags for the command and its subcommands: Setting classes, provided to the handlers (and removed from R), and Actions. cmd.pipe(with_global_flags(Region, Verbose)).

ParameterTypeDescription
flagsTagLike[Any, T] | Action[Any] = ()

Returns _WithGlobalFlags[T]

def with_global_flags[T = Never](*flags: TagLike[Any, T] | Action[Any]) -> _WithGlobalFlags[T]:
    """Global flags for the command and its subcommands: ``Setting``
    classes, provided to the handlers (and removed from ``R``), and
    ``Action``s. ``cmd.pipe(with_global_flags(Region, Verbose))``."""
    for flag in flags:
        if not isinstance(flag, Action) and not (
            isinstance(flag, type) and issubclass(flag, Setting)
        ):
            raise TypeError(f"{flag!r} is neither a Setting class nor an Action")
    return _WithGlobalFlags(cast("tuple[GlobalFlag, ...]", flags))

run_with

run_with[In, C, E, R](command, *, version, render_errors=True) -> Callable[[Sequence[str]], Effect[None, E | CliError, R | Environment]]

Runs the command on the given arguments (without the program name). Help and parse errors are shown and fail with ShowHelp; an error with a user message is printed (unless render_errors is off); a QuitError from a prompt interrupts.

ParameterTypeDescription
commandCommand[In, C, E, R]
versionstr
render_errorsbool = True

Returns Callable[[Sequence[str]], Effect[None, E | CliError, R | Environment]]

def run_with[In, C, E, R](
    command: Command[In, C, E, R], *, version: str, render_errors: bool = True
) -> Callable[[Sequence[str]], Effect[None, E | CliError, R | Environment]]:
    """Runs the command on the given arguments (without the program name).
    Help and parse errors are shown and fail with ``ShowHelp``; an error with
    a user message is printed (unless ``render_errors`` is off); a
    ``QuitError`` from a prompt interrupts."""
    runner = _Runner(command, version, render_errors)
    return runner.run

run

run[In, C, E, R](command, *, version, render_errors=True) -> Effect[None, E | CliError, R | Environment]

run_with on the process's arguments, read from Stdio.

ParameterTypeDescription
commandCommand[In, C, E, R]
versionstr
render_errorsbool = True

Returns Effect[None, E | CliError, R | Environment]

def run[In, C, E, R](
    command: Command[In, C, E, R], *, version: str, render_errors: bool = True
) -> Effect[None, E | CliError, R | Environment]:
    """``run_with`` on the process's arguments, read from ``Stdio``."""
    runner = run_with(command, version=version, render_errors=render_errors)

    def body():
        stdio = yield from Stdio()
        args = yield from stdio.args
        return (yield from runner(args))

    return gen(body)

wizard

wizard[In, C, E, R](command, *, prefix=None) -> Effect[tuple[str, ...], CliError | QuitError, Environment]

Asks for the command's flags, arguments and subcommands; gives the command line (with the program name).

ParameterTypeDescription
commandCommand[In, C, E, R]
prefixSequence[str] | None = None

Returns Effect[tuple[str, ...], CliError | QuitError, Environment]

def wizard[In, C, E, R](
    command: Command[In, C, E, R], *, prefix: Sequence[str] | None = None
) -> Effect[tuple[str, ...], CliError | QuitError, Environment]:
    """Asks for the command's flags, arguments and subcommands; gives the
    command line (with the program name)."""
    return wizard_.run(command, prefix=None if prefix is None else tuple(prefix)).map(
        lambda result: result.args
    )

show_help

show_help(command, path=None) -> Effect[None]

Presents the help of path (default: the command itself).

ParameterTypeDescription
commandAnyCommand
pathSequence[str] | None = None

Returns Effect[None]

def show_help(command: AnyCommand, path: Sequence[str] | None = None) -> Effect[None]:
    """Presents the help of ``path`` (default: the command itself)."""
    return _show_help(command, ShowHelp(tuple(path or (command.name,))), True)

make

make(name: str) -> Command[Config, Config]
make[Cfg: Config](name: str, config: type[Cfg]) -> Command[Cfg, Config]
make[Cfg: Config, EH = Never](name: str, config: type[Cfg], handler: Callable[[Cfg], Effect[object, EH, LogLevel]]) -> Command[Cfg, Config, EH, Never]
make[Cfg: Config, EH = Never, RH = Never](name: str, config: type[Cfg], handler: Callable[[Cfg], Effect[object, EH, LogLevel | RH]]) -> Command[Cfg, Config, EH, RH]

A command named name parsing config's params; without a handler, running it shows its help.

ParameterTypeDescription
name
config= Config
handler= None
@overload
def make(name: str) -> Command[Config, Config]: ...
@overload
def make[Cfg: Config](name: str, config: type[Cfg]) -> Command[Cfg, Config]: ...
@overload
def make[Cfg: Config, EH = Never](
    name: str, config: type[Cfg], handler: Callable[[Cfg], Effect[object, EH, LogLevel]]
) -> Command[Cfg, Config, EH, Never]: ...
@overload
def make[Cfg: Config, EH = Never, RH = Never](
    name: str, config: type[Cfg], handler: Callable[[Cfg], Effect[object, EH, LogLevel | RH]]
) -> Command[Cfg, Config, EH, RH]: ...
def make(
    name: str,
    config: type[Config] = Config,
    handler: Callable[[Any], Effect[object, Any, Any]] | None = None,
) -> Command[Any, Any, Any, Any]:
    """A command named ``name`` parsing ``config``'s params; without a
    handler, running it shows its help."""
    return Command(
        State(
            name=name,
            config=parse_config(config),
            service=_context_tag(name),
            parse=_own_parse,
            handle=_show_help if handler is None else _run_handler(handler),
        )
    )