coma.hooks.base

Base of hook utilities implementation.

class HookSentinels(value)

Type for sentinels for hooks.

DEFAULT

Replace a hook marked as this with a default hook.

SHARED

Replace a command-specific hook marked as this with a shared hook.

See also

• merge()

class GeneralSentinel(value)

Type for the sentinel of general use.

DEFAULT = HookSentinels.DEFAULT

Sentinel for marking a hook to either command() or wake() as being a default hook. The runtime value of the hook will be replaced by the corresponding coma default.

Recall that a hook can also be defined as a (recursive) sequence. Each occurrence of DEFAULT in said sequence will be replaced by the coma default.

SHARED = HookSentinels.SHARED

Sentinel for marking that a hook to command() ought be be replaced at runtime with the runtime value of the corresponding hook from wake().

Recall that a hook can also be defined as a (recursive) sequence. Each occurrence of SHARED in said sequence will be replaced by the wake() value.

SHARED is not a legal value for wake() hooks to avoid infinite regress.

SENTINEL = GeneralSentinel.token

A convenient pre-defined sentinel for general use. Unlike other sentinels in coma, SENTINEL has no special semantic value beyond its existence as a sentinel.

Hook

Base definition of a “raw” coma hook. A valid hook is typically a procedural function (modifying its input parameter in place and returning None). However, returning an instance of the same type T is also permitted to account for cases where T is an immutable type. A non-None return value takes precedence: it replaces the procedural parameter is all downstream hooks in a hook pipeline. Typically, T is a subclass of HookData.

Alias:

alias of Callable[[T], T | None]

HookOrSentinels

A Hook or one of the valid hook sentinels: DEFAULT, SHARED, or None.

Alias:

alias of Callable[[T], T | None] | HookSentinels | None

AugmentedHook

A HookOrSentinels, or any (recursive) Sequence thereof.

Example:

parser_hook=(
    DEFAULT, (
        SHARED, (
            add_argument_factory(...),
            None,
        ),
    ),
    add_argument_factory(...),
)

Alias:

alias of Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None]

CommandName

The name under which to register a command with coma. The same value is used to invoke the command on the command line. Any value allowed by argparse is allowed.

Command

Any function or any class with (by default) a no-argument run() method. Configs are inferred from the command signature. See command().

alias of Callable | type

class HookData(name: str, command: Callable | type, parameters: ParamData, persistence_manager: PersistenceManager)

Base class for typical Hook arguments.

name

The command name.

Type:

CommandName

command

The command itself.

Type:

Command, optional

parameters

The command’s parameters.

Type:

ParamData

persistence_manager

The manager for serializing configs in parameters.

Type:

PersistenceManager

class ParserData(name: str, command: Callable | type, parameters: ParamData, persistence_manager: PersistenceManager, parser: ArgumentParser)

The HookData for parser hooks.

parser

The sub-parser for this command.

Type:

argparse.ArgumentParser

class InvocationData(name: str, command: Callable | type, parameters: ParamData, persistence_manager: PersistenceManager, known_args: Any, unknown_args: list[str], result: Any | None = None)

The HookData for all invocation hooks.

known_args

The namespace of known command line arguments. Typically, this is the first return value of parse_known_args().

Type:

Any

unknown_args

The list of unknown command line arguments. Typically, this is the second return value of parse_known_args().

Type:

list[str]

result

The return value from invoking command.

Type:

Any, optional

identity(arg: T) → T

A no-op Hook. For convenience.

class Pipe(*fns: Callable[[T], T | None] | Sequence[Callable[[T], T | None]])

A convenience wrapper for sequences of Hook s.

Recursively composes functions, which can then be invoked with a single call.

Parameters:

*fns (Union[Hook, Sequence[Hook]]) – The Hook s to recursively compose (in order).