Tutorial: intermediate topics

These tutorials are placeholders for focused guides that build on the basic catalog workflow. They should stay small and runnable.

Custom hooks and extractors

Use this level for examples that register hooks through PluginRegistry, fill metadata before validation, collect derived metadata, or handle rollback warnings. The existing runnable example is:

uv run python examples/custom_extractor/scripts/run.py

Future content should show:

  • before_validate_metadata for metadata defaults

  • extract_metadata for derived metadata

  • context.add_warning(...) for non-fatal findings

  • focused tests for hook outcomes

Artifact writers

Use this level for examples that materialise data during add_artifact(), for example writing an in-memory object or unpacking a zip archive with helpers from ogcat.writers.

Future content should show:

  • memory_source() with memory_writer()

  • path_source() with path_writer()

  • UnzipArtifactWriter

  • rollback behavior when a writer fails

Validation patterns

Use this level for stricter catalog policies. Required metadata fields are errors during ingest, while unknown metadata is accepted unless strict validation is requested explicitly.

Future content should show:

  • validate_spec() before writing a catalog spec

  • validate_metadata() and ValidationIssue.path

  • allow_unknown_metadata=False with explicit strict validation

  • user-friendly error messages in CLIs or notebooks

CLI parity

Use this level for shell-first workflows that mirror the Python API.

Future content should show:

  • compact search expressions such as species=CH4, title:methane, and field?

  • --fields plus --format csv|tsv|pipe

  • --json, --ids, and --paths for automation