Event hooks service¶

`consortium.server.services.event_hooks_service` ¶

`EventHooksService(events_service, release_service, paths_service)` ¶

`get_event_hook_from_directory(directory, ignore_enabled_flag=False)` ¶

Instantiates an event hook from a directory without registering it.

Disabled event hooks (as indicated by enabled: false in their manifest.json) are not instantiated unless ignore_enabled_flag is True.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Path to the directory containing the event hook project files and `manifest.json`.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`BaseEventHook \| None`	The instantiated event hook, or `None` if the event hook is disabled and
`BaseEventHook \| None`	the enabled check is not overridden.

Raises:

Type	Description
`EventHookManifestFileNotFoundError`	If `manifest.json` is missing.
`InvalidEventHookManifestFileJSONError`	If `manifest.json` contains invalid JSON.
`InvalidEventHookManifestFileSchemaError`	If `manifest.json` does not follow the expected schema.
`InvalidEventHookPyProjectFileTOMLError`	If `pyproject.toml` is not valid TOML.
`InvalidEventHookPyProjectFileDependencyError`	If `pyproject.toml` contains an invalid dependency entry.
`EventHookEntryPointModuleNotFoundError`	If the entry-point module cannot be found.
`EventHookSymbolNotFoundError`	If the symbol specified in the manifest is not found.
`EventHookInterfaceError`	If the class does not inherit from the expected base class.
`IncompatibleEventHookFrameworkVersionError`	If the event hook is incompatible with the current framework version.
`InternalEventHookError`	If an unhandled exception occurs while loading the event hook.

`get_all_event_hooks_from_directory(directory, ignore_enabled_flag=False)` ¶

Recursively scans a directory for event hooks and instantiates them.

Disabled event hooks (as indicated by enabled: false in their manifest.json) are skipped unless ignore_enabled_flag is True.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	The directory to scan for event hooks.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in each event hook's manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`list[BaseEventHook]`	A three-element tuple: (1) a list of successfully instantiated event
`list[Path]`	hooks, (2) a list of paths skipped because the event hook was disabled,
`list[tuple[Path, EventHookLoadingError]]`	and (3) a list of `(path, error)` tuples for event hooks that failed to
`tuple[list[BaseEventHook], list[Path], list[tuple[Path, EventHookLoadingError]]]`	load.

Raises:

Type	Description
`EventHookDiscoveryFileSystemError`	If the recursive filesystem scan of `directory` fails, for example because a subdirectory is removed mid-scan or cannot be read due to a permissions error. This happens before any individual event hook is loaded, so it is not one of the per-event-hook errors collected in the returned error list, it propagates to the caller.

`register_event_hook(event_hook)` ¶

Registers an already-instantiated event hook with the service.

Parameters:

Name	Type	Description	Default
`event_hook`	`BaseEventHook`	The event hook instance to register.	required

Returns:

Type	Description
`BaseEventHook`	The registered event hook instance.

Raises:

Type	Description
`EventHookAlreadyRegisteredError`	If an event hook with the same ID is already registered.
`DuplicateEventHookLabelError`	If an event hook with the same label is already registered.

`register_event_hook_from_directory(directory, ignore_enabled_flag=False)` ¶

Instantiates and registers an event hook from a directory.

Disabled event hooks are skipped unless ignore_enabled_flag is True.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Path to the directory containing the event hook project files and `manifest.json`.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`BaseEventHook \| None`	The registered event hook instance, or `None` if the event hook is disabled and the enabled check is not overridden.

Raises:

Type	Description
`EventHookManifestFileNotFoundError`	If `manifest.json` is missing.
`InvalidEventHookManifestFileJSONError`	If `manifest.json` contains invalid JSON.
`InvalidEventHookManifestFileSchemaError`	If `manifest.json` does not follow the expected schema.
`InvalidEventHookPyProjectFileTOMLError`	If `pyproject.toml` is not valid TOML.
`InvalidEventHookPyProjectFileDependencyError`	If `pyproject.toml` contains an invalid dependency entry.
`EventHookEntryPointModuleNotFoundError`	If the entry-point module cannot be found.
`EventHookSymbolNotFoundError`	If the symbol specified in the manifest is not found.
`EventHookInterfaceError`	If the class does not inherit from the expected base class.
`IncompatibleEventHookFrameworkVersionError`	If the event hook is incompatible with the current framework version.
`InternalEventHookError`	If an unhandled exception occurs while loading the event hook.
`EventHookAlreadyRegisteredError`	If an event hook with the same ID is already registered.
`DuplicateEventHookLabelError`	If an event hook with the same label is already registered.

`load_event_hook(event_hook)` `async` ¶

Registers and activates an already-instantiated event hook.

Parameters:

Name	Type	Description	Default
`event_hook`	`BaseEventHook`	The event hook instance to load.	required

Returns:

Type	Description
`BaseEventHook`	The loaded event hook instance.

Raises:

Type	Description
`EventHookAlreadyRegisteredError`	If an event hook with the same ID is already registered. This path only checks for a duplicate ID, not a duplicate label: `DuplicateEventHookLabelError` and the component dependency errors are only raised by the registration path (`register_event_hook`), not this loading path.
`EventHookSetupError`	If an error occurs while the event hook is setting up.

`load_event_hook_from_directory(directory, ignore_enabled_flag=False)` `async` ¶

Instantiates, registers, and activates an event hook from a directory.

Disabled event hooks are skipped unless ignore_enabled_flag is True.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	Path to the directory containing the event hook project files and `manifest.json`.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest. Defaults to `False`.	`False`

Returns:

Type	Description
`BaseEventHook \| None`	The loaded event hook instance, or `None` if the event hook is disabled and
`BaseEventHook \| None`	the enabled check is not overridden.

Raises:

Type	Description
`EventHookManifestFileNotFoundError`	If `manifest.json` is missing.
`InvalidEventHookManifestFileJSONError`	If `manifest.json` contains invalid JSON.
`InvalidEventHookManifestFileSchemaError`	If `manifest.json` does not follow the expected schema.
`EventHookEntryPointModuleNotFoundError`	If the entry-point module cannot be found.
`EventHookSymbolNotFoundError`	If the symbol specified in the manifest is not found.
`EventHookInterfaceError`	If the class does not inherit from the expected base class.
`IncompatibleEventHookFrameworkVersionError`	If the event hook is incompatible with the current framework version.
`InternalEventHookError`	If an unhandled exception occurs while loading the event hook.
`EventHookAlreadyRegisteredError`	If an event hook with the same ID is already registered. As with `load_event_hook`, this path only checks for a duplicate ID: `DuplicateEventHookLabelError` and the component dependency errors are only raised by the registration path (`register_event_hook_from_directory`), not this loading path.
`EventHookSetupError`	If an error occurs while the event hook is setting up.

`unload_event_hook_by_event_hook_id(event_hook_id)` `async` ¶

Deactivates and deregisters a loaded event hook by its ID.

Parameters:

Name	Type	Description	Default
`event_hook_id`	`str \| UUID`	The ID of the event hook to unload.	required

Raises:

Type	Description
`EventHookNotFoundError`	If no event hook with the given ID is registered.
`EventHookTeardownError`	If an error occurs while the event hook is tearing down.

`reload_event_hook_by_event_hook_id(event_hook_id, ignore_enabled_flag=False)` `async` ¶

Unloads and reloads an event hook from its original directory.

If the event hook is disabled after reload and ignore_enabled_flag is False, the event hook will only be unloaded, not reloaded.

Parameters:

Name	Type	Description	Default
`event_hook_id`	`str \| UUID`	The ID of the event hook to reload.	required
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in the manifest during reload. Defaults to `False`.	`False`

Returns:

Type	Description
`BaseEventHook \| None`	The reloaded event hook instance, or `None` if the event hook was disabled
`BaseEventHook \| None`	and the enabled check was not overridden.

Raises:

Type	Description
`EventHookNotFoundError`	If no event hook with the given ID is registered.
`EventHookTeardownError`	If an error occurs while the previously loaded event hook is tearing down.
`EventHookManifestFileNotFoundError`	If `manifest.json` is missing from the event hook's directory on reload.
`InvalidEventHookManifestFileJSONError`	If `manifest.json` contains invalid JSON on reload.
`InvalidEventHookManifestFileSchemaError`	If `manifest.json` does not follow the expected schema on reload.
`EventHookEntryPointModuleNotFoundError`	If the entry-point module cannot be found on reload.
`EventHookSymbolNotFoundError`	If the symbol specified in the manifest is not found on reload.
`EventHookInterfaceError`	If the class does not inherit from the expected base class on reload.
`IncompatibleEventHookFrameworkVersionError`	If the event hook is incompatible with the current framework version on reload.
`InternalEventHookError`	If an unhandled exception occurs while reloading the event hook.
`EventHookAlreadyRegisteredError`	If the reloaded event hook's ID is already registered.
`EventHookSetupError`	If an error occurs while the reloaded event hook is setting up. Same as `load_event_hook_from_directory`, this method does not raise `DuplicateEventHookLabelError` or the component dependency errors: it reloads through the same loading path, not the registration path.

`load_framework_event_hooks(ignore_enabled_flag=False)` `async` ¶

Scans the framework's event hooks directory and loads all enabled event hooks.

Disabled event hooks and those that fail to load are logged and skipped without aborting the overall load.

Parameters:

Name	Type	Description	Default
`ignore_enabled_flag`	`bool`	When `True`, bypasses the `enabled` check in each event hook's manifest. Defaults to `False`.	`False`

Raises:

Type	Description
`EventHookDiscoveryFileSystemError`	If the framework event hooks directory cannot be scanned (for example, due to a permissions error) while discovering candidate event hook directories.

`unload_framework_event_hooks()` `async` ¶

Unloads all event hooks that were loaded from the framework's event hooks directory.

Raises:

Type	Description
`EventHookNotFoundError`	If an event hook selected for unloading is no longer registered by the time its unload is attempted.
`EventHookTeardownError`	If an error occurs while an event hook is tearing down.

`reload_framework_event_hooks()` `async` ¶

Unloads all framework event hooks then reloads them from the event hooks directory.

Per-event-hook load failures during the load half are caught and logged rather than propagated, so a single bad event hook does not abort loading the rest.

Raises:

Type	Description
`EventHookNotFoundError`	If an event hook selected for unloading is no longer registered by the time its unload is attempted, during the unload half.
`EventHookTeardownError`	If an error occurs while an event hook is tearing down, during the unload half.
`EventHookDiscoveryFileSystemError`	If the framework event hooks directory cannot be scanned during the load half.

`get_event_hook_by_event_hook_id(event_hook_id)` ¶

Returns a loaded event hook by its ID.

Parameters:

Name	Type	Description	Default
`event_hook_id`	`str \| UUID`	The ID of the event hook to retrieve.	required

Returns:

Type	Description
`BaseEventHook`	The requested event hook.

Raises:

Type	Description
`EventHookNotFoundError`	If no event hook with the given ID is registered.

`get_all_event_hooks()` ¶

Returns all currently loaded event hooks.

Returns:

Type	Description
`list[BaseEventHook]`	A list of all loaded event hooks. Empty if none are loaded.

`get_all_event_types()` ¶

Returns all supported event types.

Returns:

Type	Description
`list[EventType]`	A list of all values from the `EventType` enum.

`trigger_event(event)` `async` ¶

Triggers an event, invoking every handler registered for its type.

This is a convenience wrapper around EventsService.trigger_event for callers already working with the event hooks service. It delegates entirely to the events service so event hooks and any other registered handlers (for example, websocket subscribers) are notified through the same code path.

Parameters:

Name	Type	Description	Default
`event`	`Event`	The event to trigger.	required

Raises:

Type	Description
`ExceptionGroup`	If one or more registered handlers raise exceptions. Event hooks that raise `EventHookTriggerError` from `on_triggered()` are represented in the group as the consortium-level `EventHookTriggerError`.

Event hooks service¶

consortium.server.services.event_hooks_service ¶