Hooks and plugins

Lifecycle hooks, writer protocols, and operation context objects.

Hooks are structural protocols: a plugin object participates in a lifecycle phase by implementing the corresponding method, such as before_validate_metadata(context) or extract_metadata(context). Hook methods receive an OperationContext, a mutable object that carries the catalog root, operation id, source description, planned locators, user metadata, derived metadata, rollback registrar, and accumulated hook warnings.

The design intentionally keeps hook classes lightweight. Plugin authors do not subclass a base class; they implement one or more protocol methods, usually with context: OperationContext and -> None or -> MetadataDict | None type hints. HookManager dispatches protocols in deterministic registration order, merges returned derived metadata, records non-fatal after-commit failures as warnings, and preserves the original exception when error or rollback hooks fail.

Artifact writers use the same context model. Any object satisfying ArtifactWriter can materialise an ogcat.models.ArtifactLocator from an OperationSource before the catalog record is committed.

Operation context

Hook methods receive an OperationContext unless their signature documents additional arguments such as a validation report or exception. The context is the main coordination object for metadata mutation, locator planning, rollback registration, and source information.

class ogcat.OperationContext(catalog_root, operation_id, operation_type, record_type, user_metadata, derived_metadata=<factory>, planned_locators=<factory>, register_rollback=None, source=<factory>, storage_mode=None, storage_plan=None, original_path=None, original_filename=None, suffixes=<factory>, warnings=<factory>)[source]

Bases: object

Mutable context passed to catalog lifecycle hooks.

Hooks exert their effect by mutating documented fields on this object, raising an exception, or registering rollback work. user_metadata may be mutated before validation. planned_locators may be changed during resolve_artifact_locator; the first locator is treated as canonical. derived_metadata may be updated during metadata extraction.

Parameters:

  • catalog_root (Path) – Root path of the catalog.

  • operation_id (str) – Identifier shared with the transaction.

  • operation_type (str) – Catalog operation name, such as "add_file".

  • record_type (str) – Record type being created.

  • user_metadata (MetadataDict) – User-supplied metadata, mutable by hooks before validation.

  • derived_metadata (MetadataDict) – Derived metadata collected during the operation.

  • planned_locators (list[ArtifactLocator]) – Locators planned or supplied for the operation.

  • register_rollback (RollbackRegistrar | None) – Low-level rollback registrar. Hook authors should normally call context.rollback(...) instead.

  • source (OperationSource) – Artifact source description for this operation.

  • storage_mode (str | None) – Optional storage mode, such as "copy" or "move".

  • storage_plan (StoragePlan | None) – Optional planned artifact storage decision.

  • original_path (str | Path | None) – Optional original path or URI.

  • original_filename (str | None) – Optional original filename.

  • suffixes (list[str]) – Source suffixes associated with the artifact.

storage_plan: StoragePlan | None
property source_path: Path | None

Optional local source path, kept for compatibility with existing hooks.

property source_descriptor: str | None

Optional source description, kept for compatibility with existing hooks.

add_warning(warning, *, hook_name='hook')[source]

Record a non-fatal warning for this operation.

Return type:

None

rollback(action, *, description=None)[source]

Register a rollback action through the active catalog transaction.

Return type:

RollbackAction

class ogcat.OperationSource(kind, path=None, descriptor=None, metadata=<factory>, payload=None)[source]

Bases: object

Description of the artifact source for a catalog operation.

Parameters:

  • kind (str) – Short source kind, such as "local_file" or "external".

  • path (Path | None) – Optional local source path.

  • descriptor (str | None) – Optional non-path source description or URI.

  • metadata (MetadataDict) – Source-specific JSON-compatible metadata.

  • payload (object | None) – Optional in-memory Python object for writer helpers.

class ogcat.HookWarning(hook_name, message, code='hook.warning')[source]

Bases: object

A non-fatal hook warning.

Parameters:

  • hook_name (str) – Name of the hook or plugin reporting the warning.

  • message (str) – Human-readable warning message.

  • code (str) – Stable machine-readable warning code.

to_metadata()[source]

Convert the warning to JSON-compatible metadata.

Return type:

MetadataDict

Plugin registry

class ogcat.PluginRegistry(hooks=())[source]

Bases: object

Registry for direct Python hook registration.

Parameters:

hooks (Iterable[object]) – Hook objects to register in dispatch order.

property hooks: tuple[object, ...]

Registered hooks in insertion order.

register(hook)[source]

Register a hook object and return it for decorator-style usage.

Return type:

object

hook_manager()[source]

Build a hook manager from the currently registered hooks.

Return type:

HookManager

Hook protocols

class ogcat.hooks.BeforeValidateMetadataHook(*args, **kwargs)[source]

Bases: Protocol

Hook called before schema metadata validation.

before_validate_metadata(context)[source]

Inspect or mutate metadata before validation.

Return type:

None

class ogcat.hooks.AfterValidateMetadataHook(*args, **kwargs)[source]

Bases: Protocol

Hook called after schema metadata validation.

after_validate_metadata(context, report)[source]

Inspect validation results.

Return type:

None

class ogcat.hooks.ResolveArtifactLocatorHook(*args, **kwargs)[source]

Bases: Protocol

Hook called after an artifact locator has been proposed.

resolve_artifact_locator(context)[source]

Inspect, replace, or extend planned artifact locators.

Return type:

None

class ogcat.hooks.BeforeRecordWriteHook(*args, **kwargs)[source]

Bases: Protocol

Hook called before writing the catalog record.

before_record_write(context)[source]

Run before the catalog record is written.

Return type:

None

class ogcat.hooks.AfterRecordWriteHook(*args, **kwargs)[source]

Bases: Protocol

Hook called after writing the catalog record.

after_record_write(context)[source]

Run after the catalog record is written.

Return type:

None

class ogcat.hooks.ExtractMetadataHook(*args, **kwargs)[source]

Bases: Protocol

Hook called during derived metadata extraction.

extract_metadata(context)[source]

Return derived metadata to merge into the operation context.

Return type:

MetadataDict | None

class ogcat.hooks.BeforeCommitHook(*args, **kwargs)[source]

Bases: Protocol

Hook called before committing the catalog transaction.

before_commit(context)[source]

Run before transaction commit.

Return type:

None

class ogcat.hooks.AfterCommitHook(*args, **kwargs)[source]

Bases: Protocol

Hook called after committing the catalog transaction.

after_commit(context)[source]

Run after transaction commit.

Return type:

None

class ogcat.hooks.ErrorHook(*args, **kwargs)[source]

Bases: Protocol

Hook called when an operation fails.

on_error(context, error)[source]

Run when an operation fails.

Return type:

None

class ogcat.hooks.RollbackHook(*args, **kwargs)[source]

Bases: Protocol

Hook called when an operation fails and rolls back.

on_rollback(context, error)[source]

Run after rollback has been requested for a failed operation.

Return type:

None

Dispatch

class ogcat.HookManager(hooks=())[source]

Bases: object

Deterministic dispatcher for registered catalog hooks.

property hooks: tuple[object, ...]

Registered hooks in dispatch order.

register(hook)[source]

Register a hook object and return it for decorator-style usage.

Return type:

object

before_validate_metadata(context)[source]

Dispatch before_validate_metadata hooks.

Return type:

None

after_validate_metadata(context, report)[source]

Dispatch after_validate_metadata hooks.

Return type:

None

resolve_artifact_locator(context)[source]

Dispatch resolve_artifact_locator hooks.

Return type:

None

before_record_write(context)[source]

Dispatch before_record_write hooks.

Return type:

None

after_record_write(context)[source]

Dispatch after_record_write hooks.

Return type:

None

extract_metadata(context)[source]

Dispatch metadata extraction hooks and merge returned metadata.

Return type:

None

before_commit(context)[source]

Dispatch before_commit hooks.

Return type:

None

after_commit(context)[source]

Dispatch after_commit hooks without failing committed work.

Return type:

None

on_error(context, error)[source]

Dispatch error hooks, preserving the original operation failure.

Return type:

None

on_rollback(context, error)[source]

Dispatch rollback hooks, preserving the original operation failure.

Return type:

None