coma.hooks.management

Utilities for managing recursive sequences of shared and command-specific hooks.

class Hooks(parser_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, pre_config_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, config_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, post_config_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, pre_init_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, init_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, post_init_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, pre_run_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, run_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None, post_run_hook: Callable[[T], T | None] | HookSentinels | None | Sequence[Callable[[T], T | None] | HookSentinels | None] = None)

A collection of all hooks that coma accepts.

static merge(shared_hooks: Hooks, command_hooks: Hooks) → Hooks

Returns a merged Hooks where the shared_hooks form the base and the command_hooks (which take precedence) are able to override this base.

Specifically, each hook in command_hooks can be either a plain HookOrSentinels or a Sequence thereof. If plain, the hook is transformed as below. If a sequence, each item in that sequence is recursively transformed as below, with the result being a new sequence of transformed items in the same order.

Transformation process for a plain hook item in command_hooks:

1. If the hook is None (not identity()), then set the merged hook to identity regardless of the value of the corresponding hook in shared_hooks.

2. If the hook is the SHARED sentinel, then set the merged hook to the corresponding hook from shared_hooks.

3. If the hook is the DEFAULT sentinel, then set the merged hook to the corresponding default hook regardless of the value of the corresponding hook in shared_hooks.

4. For all other values of hook (including identity), set the merged hook to said value (unchanged).

When case (2) applies, the corresponding hook in shared_hooks is also recursively transformed according to this process, that a shared hook cannot be set to the SHARED sentinel to avoid infinite regress.

Returns:

The merged hooks.

Return type:

Hooks

Raises:

ValueError – If a shared hook is or contains the SHARED sentinel.

parse(arg: T) → None

Calls the parser hook on arg.

invoke(arg: T) → None

Calls the entire invocation hook pipeline in order on arg.