coma

Configurable command management for humans.

Sub-Modules

Module Attributes

SENTINEL = <object object>

A convenient sentinel for general use.

initiate(*configs: typing.Any, parser: typing.Optional[argparse.ArgumentParser] = None, parser_hook: typing.Optional[typing.Callable] = <function multi_config>, pre_config_hook: typing.Optional[typing.Callable] = None, config_hook: typing.Optional[typing.Callable] = <function multi_load_and_write_factory.<locals>._hook>, post_config_hook: typing.Optional[typing.Callable] = <function multi_cli_override_factory.<locals>._hook>, pre_init_hook: typing.Optional[typing.Callable] = None, init_hook: typing.Optional[typing.Callable] = <function positional_factory.<locals>._hook>, post_init_hook: typing.Optional[typing.Callable] = None, pre_run_hook: typing.Optional[typing.Callable] = None, run_hook: typing.Optional[typing.Callable] = <function factory.<locals>._hook>, post_run_hook: typing.Optional[typing.Callable] = None, subparsers_kwargs: typing.Optional[dict] = None, **id_configs: typing.Any) → None[source]

Initiates a coma.

Starts up coma with an optional argument parser, optional global configs, optional global hooks, and optional subparsers keyword arguments.

Note

Any optional configs and/or hooks are applied globally to every register()ed command, unless explicitly forgotten using the forget() context manager.

Configs can be provided with or without an identifier. In the latter case, an identifier is derived automatically. See to_dict() for additional details.

Example:

@dataclass
class Config1:
    ...

@dataclass
class Config2:
    ...
coma.initiate(Config1, a_non_default_id=Config2, pre_run_hook=...)
Parameters

  • *configs (Any) – Global configs with default identifiers

  • parser (argparse.ArgumentParser) – Top-level ArgumentParser. If None, an ArgumentParser with default parameters is used.

  • parser_hook (Callable) – An optional global parser hook

  • pre_config_hook (Callable) – An optional global pre config hook

  • config_hook (Callable) – An optional global config hook

  • post_config_hook (Callable) – An optional global post config hook

  • pre_init_hook (Callable) – An optional global pre init hook

  • init_hook (Callable) – An optional global init hook

  • post_init_hook (Callable) – An optional global post init hook

  • pre_run_hook (Callable) – An optional global pre run hook

  • run_hook (Callable) – An optional global run hook

  • post_run_hook (Callable) – An optional global post run hook

  • subparsers_kwargs (Dict[str, Any]) – Keyword arguments to pass along to ArgumentParser.add_subparsers()

  • **id_configs (Any) – Global configs with explicit identifiers

Raises

KeyError – If config identifiers are not unique

See also

register(name: str, command: Callable, *configs: Any, parser_hook: Optional[Callable] = None, pre_config_hook: Optional[Callable] = None, config_hook: Optional[Callable] = None, post_config_hook: Optional[Callable] = None, pre_init_hook: Optional[Callable] = None, init_hook: Optional[Callable] = None, post_init_hook: Optional[Callable] = None, pre_run_hook: Optional[Callable] = None, run_hook: Optional[Callable] = None, post_run_hook: Optional[Callable] = None, parser_kwargs: Optional[dict] = None, **id_configs: Any) → None[source]

Registers a command that might be invoked upon waking from a coma.

Registers a command with ArgumentParser.add_subparsers().add_parser(), along with providing optional local configs and optional local hooks.

Note

Any provided local configs are appended to the list of global configs (rather than replacing them). See initiate() and forget() for more details.

Configs can be provided with or without an identifier. In the latter case, an identifier is derived automatically. See to_dict() for additional details.

Examples

Register function-based command with no configurations:

coma.register("cmd", lambda: ...)

Register function-based command with configurations:

@dataclass
class Config:
    ...
coma.register("cmd", lambda cfg: ..., Config)

Register class-based command with explicit configuration identifier:

@dataclass
class Config:
    ...
class Command:
    def __init__(self, cfg):
        ...
    def run(self):
        ...
coma.register("cmd", Command, a_non_default_id=Config)
Parameters

  • name (str) – Any (unique) valid command name according to argparse

  • command (Callable) – A command class or function

  • *configs (Any) – Local configs with default identifiers

  • parser_hook (Callable) – An optional local parser hook

  • pre_config_hook (Callable) – An optional local pre config hook

  • config_hook (Callable) – An optional local config hook

  • post_config_hook (Callable) – An optional local post config hook

  • pre_init_hook (Callable) – An optional local pre init hook

  • init_hook (Callable) – An optional local init hook

  • post_init_hook (Callable) – An optional local post init hook

  • pre_run_hook (Callable) – An optional local pre run hook

  • run_hook (Callable) – An optional local run hook

  • post_run_hook (Callable) – An optional local post run hook

  • parser_kwargs (Dict[str, Any]) – Keyword arguments to pass along to the constructor of the sub-ArgumentParser created for command

  • **id_configs (Any) – Local configs with explicit identifiers

Raises

See also

forget(*config_ids: str, parser_hook: bool = False, pre_config_hook: bool = False, config_hook: bool = False, post_config_hook: bool = False, pre_init_hook: bool = False, init_hook: bool = False, post_init_hook: bool = False, pre_run_hook: bool = False, run_hook: bool = False, post_run_hook: bool = False) → Iterator[None][source]

Temporarily forget selected global configs or hooks while in a coma.

A context manager that enables register()ing commands while selectively forgetting global configs or hooks.

Example:

with coma.forget(...):
    coma.register(...)

Note

Configs are referenced by identifier whereas hooks are referenced by type. For configs that were initiate()d or register()ed without an explicit identifier, the automatically-derived identifier can be retrieved programmatically using default_id().

Parameters

  • *config_ids (str) – Identifiers of global configs to temporarily forget

  • parser_hook (bool) – Whether to ignore the global parser hook (if any)

  • pre_config_hook (bool) – Whether to ignore the global pre config hook (if any)

  • config_hook (bool) – Whether to ignore the global config hook (if any)

  • post_config_hook (bool) – Whether to ignore the global post config hook (if any)

  • pre_init_hook (bool) – Whether to ignore the global pre init hook (if any)

  • init_hook (bool) – Whether to ignore the global init hook (if any)

  • post_init_hook (bool) – Whether to ignore the global post init hook (if any)

  • pre_run_hook (bool) – Whether to ignore the global pre run hook (if any)

  • run_hook (bool) – Whether to ignore the global run hook (if any)

  • post_run_hook (bool) – Whether to ignore the global post run hook (if any)

Returns

A generator yielding a single None

Raises

KeyError – If any provided config identifier does not match any known config

See also

wake(args=None, namespace=None) → None[source]

Wakes from a coma.

Parses command line arguments and invokes the appropriate command using the register()ed hooks.

Example

Use sys.argv as source of command line arguments.

coma.wake()

Simulate command line arguments.

coma.wake(args=...)
Parameters

See also