Replica views

Replica views are user-requested generated link trees derived from catalog records. They are separate from secondary artifacts, such as the default template-link created during UUID-primary add_file() operations. Secondary artifact internals are documented on the internals page.

Replica and generated view helpers.

Replica views are derived filesystem state. They point at catalogued primary artifacts but do not change catalog records.

ogcat.replicas.plan_replica_view(*, root, template, records, mode='symlink', role='view_link')[source]

Plan a generated local replica view for records.

Parameters:

  • root (str | Path) – Root directory for rendered replica paths.

  • template (str) – Combined path template relative to root.

  • records (Sequence[CatalogRecord]) – Catalog records to include in the view.

  • mode (Literal['symlink']) – Replica materialisation mode. Only "symlink" is supported.

  • role (Literal['template_link', 'view_link']) – Semantic role for planned replicas.

Return type:

ReplicaViewPlan

Returns:

Dry-run replica view plan.

class ogcat.ReplicaViewPlan(root, template, mode, items)[source]

Bases: object

Dry-run plan for a generated replica view.

Parameters:

  • root (Path) – Root directory for generated view paths.

  • template (str) – Path template rendered for each record.

  • mode (Literal['symlink']) – Replica materialisation mode.

  • items (tuple[ReplicaPlanItem, ...]) – Planned replica items.

root: Path
template: str
mode: Literal['symlink']
items: tuple[ReplicaPlanItem, ...]
property collisions: list[ReplicaPlanItem]

Return planned items that cannot be applied because of collisions.

property unsupported: list[ReplicaPlanItem]

Return planned items whose source cannot be linked locally.

property missing_targets: list[ReplicaPlanItem]

Return planned items whose primary local target is missing.

apply(*, skip_errors=False)[source]

Create symlink replicas described by this plan.

Parameters:

skip_errors (bool) – Whether to skip invalid items instead of raising before creating links.

Return type:

ReplicaApplyResult

Returns:

Per-item apply result.

Raises:

ValueError – If the plan contains blocking items and skip_errors is false.

class ogcat.ReplicaPlanItem(record_id, source_path, target_path, mode='symlink', role='view_link', state=ReplicaState.PLANNED, message=None)[source]

Bases: object

One planned or applied replica path.

Parameters:

  • record_id (str | None) – Catalog record id when available.

  • source_path (Path | None) – Primary local path the replica should point at.

  • target_path (Path) – Replica path to create or validate.

  • mode (Literal['symlink']) – Replica materialisation mode.

  • role (Literal['template_link', 'view_link']) – Semantic role of the replica.

  • state (ReplicaState) – Current plan or apply state.

  • message (str | None) – Optional human-readable diagnostic.

record_id: str | None
source_path: Path | None
target_path: Path
mode: Literal['symlink']
role: Literal['template_link', 'view_link']
state: ReplicaState
message: str | None
class ogcat.ReplicaApplyResult(items)[source]

Bases: object

Result from applying a replica view plan.

items: tuple[ReplicaPlanItem, ...]
property created: list[ReplicaPlanItem]

Return replicas created by this apply call.

property up_to_date: list[ReplicaPlanItem]

Return replicas that already pointed at the desired target.

property skipped: list[ReplicaPlanItem]

Return replicas skipped or left unapplied when errors were skipped.

property errors: list[ReplicaPlanItem]

Return replicas with blocking errors.

class ogcat.ReplicaState(value)[source]

Bases: StrEnum

Lifecycle or diagnostic state for one planned replica.

PLANNED = 'planned'
CREATED = 'created'
UP_TO_DATE = 'up_to_date'
COLLISION = 'collision'
UNSUPPORTED = 'unsupported'
MISSING_TARGET = 'missing_target'
ERROR = 'error'