coma

Configurable command management for humans.

Sub-Modules

• coma.hooks
• coma.config

Module Attributes

SENTINEL = <object object>

A convenient sentinel for general use.

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

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

• forget()

• register()

• to_dict()

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

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:

• ValueError – If name is not unique

• KeyError – If config identifiers are not unique

See also

• command()

• initiate()

• forget()

• wake()

• to_dict()

command(name: str, parser_hook: Callable | None = None, pre_config_hook: Callable | None = None, config_hook: Callable | None = None, post_config_hook: Callable | None = None, pre_init_hook: Callable | None = None, init_hook: Callable | None = None, post_init_hook: Callable | None = None, pre_run_hook: Callable | None = None, run_hook: Callable | None = None, post_run_hook: Callable | None = None, parser_kwargs: dict | None = None)

Decorator declaring the decorated object as a coma command.

Acts as a lightweight wrapper around register().

Specifically, inspects the decorated object’s signature (either the function signature if the object is a function, or the signature of the __init__() method if the object is a class), and calls coma.register() with its **id_configs keyword arguments field populated using the signature parameters.

The name of each parameter is used as the config ID and the type hint annotation is used as the class type.

Example

The following declaration:

@dataclass
class SomeConfig:
    ...

@command("command_name")
def some_command(structured_config: SomeConfig, dict_config: dict):
    ...

is equivalent to:

@dataclass
class SomeConfig:
    ...

def some_command(structured_cfg: SomeConfig, dict_cfg: dict):
    ...

coma.register(
    "command_name", some_command, structured_cfg=SomeConfig, dict_cfg={}
)

The advantage of this decorator is to remove the boilerplate of registering a command when its registration is a one-to-one mapping to the command signature. As such, this decorator acts as a convenience wrapper for coma.register(). It works in simple use cases. It does not work if the decorated object’s signature contains non-config parameters (which is a rare and advanced use case). It also doesn’t work with forget() (a more common, if still slightly advanced use case). For such advanced uses cases, an explicit call to coma.register() must be made instead.

Parameters:

• name (str) – Passed directly to register().

• parser_hook (Callable) – See register().

• pre_config_hook (Callable) – See register().

• config_hook (Callable) – See register().

• post_config_hook (Callable) – See register().

• pre_init_hook (Callable) – See register().

• init_hook (Callable) – See register().

• post_init_hook (Callable) – See register().

• pre_run_hook (Callable) – See register().

• run_hook (Callable) – See register().

• post_run_hook (Callable) – See register().

• parser_kwargs (Dict[str, Any]) – See register().

See also

• forget()

• register()

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]

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

• initiate()

• register()

• default_id()

wake(args=None, namespace=None) → None

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:

• args – Passed to ArgumentParser.parse_known_args()

• namespace – Passed to ArgumentParser.parse_known_args()

See also

• register()

Raises:

WakeException – When failing to wake from a coma.

class WakeException

Raised when wake() fails.