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#
- From
pyfect.cli:Command,CommandContext,Config,group,SubcommandGroup - From
pyfect.cli.cli_error:CliError - From
pyfect.terminal:QuitError
Types#
| Type | Definition | Description |
|---|---|---|
AnyCommand | type AnyCommand = Command[Any, Any, Any, Any] | |
Example | type 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)).
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
command | Command[In, C, EE, RR] | |
effect | Effect[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)).
| Parameter | Type | Description |
|---|---|---|
flags | TagLike[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.
| Parameter | Type | Description |
|---|---|---|
command | Command[In, C, E, R] | |
version | str | |
render_errors | bool = 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.runrun#
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.
| Parameter | Type | Description |
|---|---|---|
command | Command[In, C, E, R] | |
version | str | |
render_errors | bool = 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).
| Parameter | Type | Description |
|---|---|---|
command | Command[In, C, E, R] | |
prefix | Sequence[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).
| Parameter | Type | Description |
|---|---|---|
command | AnyCommand | |
path | Sequence[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.
| Parameter | Type | Description |
|---|---|---|
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),
)
)