Storage planning¶

Storage planning and lightweight adapter primitives.

This module keeps storage decisions explicit without turning ogcat into a domain storage framework. Plans describe where an artifact should live and how it should be materialised; ogcat.hooks.ArtifactWriter implementations perform any side effects.

class ogcat.storage.FsspecStorageAdapter(storage_options=None)[source]¶

Bases: object

Storage adapter for fsspec-addressable urlpath locators.

storage_options: dict[str, object] | None¶

exists(locator)[source]¶

Return whether a fsspec URL exists.

Return type:: bool

open(locator, mode='rb')[source]¶

Open a fsspec URL.

Return type:: IO[bytes]

copy_from_path(source, target)[source]¶

Copy a local file to a fsspec target.

Return type:: None

move_from_path(source, target)[source]¶

Move a local file to a fsspec target.

Return type:: None

mkdir(locator)[source]¶

Create a fsspec directory target.

Return type:: None

mkdir_parent(locator)[source]¶

Create the parent directory for a fsspec target.

Return type:: None

remove(locator, *, target_kind='file')[source]¶

Remove a fsspec target.

Return type:: None

class ogcat.storage.LocalStorageAdapter[source]¶

Bases: object

Storage adapter for local path locators.

exists(locator)[source]¶

Return whether a local path-backed locator exists.

Return type:: bool

open(locator, mode='rb')[source]¶

Open a local path-backed locator.

Return type:: IO[bytes]

copy_from_path(source, target)[source]¶

Copy a local source path to a local target.

Return type:: None

move_from_path(source, target)[source]¶

Move a local source path to a local target.

Return type:: None

mkdir(locator)[source]¶

Create a local directory target.

Return type:: None

mkdir_parent(locator)[source]¶

Create the parent directory for a local file target.

Return type:: None

remove(locator, *, target_kind='file')[source]¶

Remove a local file or directory target.

Return type:: None

class ogcat.storage.StorageAdapter(*args, **kwargs)[source]¶

Bases: Protocol

Minimal storage operations needed by plans and bundled writers.

exists(locator)[source]¶

Return whether a locator currently exists.

Return type:: bool

open(locator, mode='rb')[source]¶

Open a locator for binary file I/O.

Return type:: IO[bytes]

copy_from_path(source, target)[source]¶

Copy a local source path to the target locator.

Return type:: None

move_from_path(source, target)[source]¶

Move a local source path to the target locator.

Return type:: None

mkdir(locator)[source]¶

Create a directory-like target.

Return type:: None

mkdir_parent(locator)[source]¶

Create the parent directory for a file-like target.

Return type:: None

remove(locator, *, target_kind='file')[source]¶

Remove a file-like or directory-like locator.

Return type:: None

class ogcat.storage.StoragePlan(locator, target_kind='file', write_mode='reference', checksum='none', ogcat_owned=False, profile=None, adapter=None, time_added=None, storage_relative_path=None, resolved_directory=None, resolved_filename=None)[source]¶

Bases: object

Concrete storage decision for a catalog operation.

Parameters:

locator (ArtifactLocator) – Canonical artifact locator that should be stored on the record.
target_kind (Literal['file', 'directory']) – Whether the target is a file-like or directory-like artifact.
write_mode (Literal['copy', 'move', 'write', 'reference']) – How data should be materialised, or "reference" for record-only external artifacts.
checksum (Literal['none']) – Checksum policy requested for the write.
ogcat_owned (bool) – Whether ogcat is responsible for cleanup on rollback.
profile (str | None) – Optional storage profile name or hint.
adapter (str | None) – Optional adapter identifier, such as "local" or "fsspec".
time_added (str | None) – Optional timestamp used when rendering date-based storage templates.
storage_relative_path (str | None) – Optional target path relative to the configured storage root.
resolved_directory (str | None) – Optional rendered directory path for template-based storage.
resolved_filename (str | None) – Optional rendered filename or final path component.

locator: ArtifactLocator¶

target_kind: Literal['file', 'directory']¶

write_mode: Literal['copy', 'move', 'write', 'reference']¶

checksum: Literal['none']¶

ogcat_owned: bool¶

profile: str | None¶

adapter: str | None¶

time_added: str | None¶

storage_relative_path: str | None¶

resolved_directory: str | None¶

resolved_filename: str | None¶

ogcat.storage.adapter_for_locator(locator)[source]¶

Return the storage adapter that can interpret a locator.

Parameters:: locator (ArtifactLocator) – Artifact locator to inspect.
Return type:: StorageAdapter
Returns:: Storage adapter for local path or fsspec URL-path locators.
Raises:: ValueError – If ogcat does not provide a storage adapter for the locator kind.

ogcat.storage.create_directory_target(locator, *, adapter=None)[source]¶

Create an empty directory target after checking it does not exist.

Parameters:

locator (ArtifactLocator) – Directory-like target locator to create.
adapter (StorageAdapter | None) – Optional pre-resolved storage adapter.

Raises:

FileExistsError – If the directory target already exists.
ValueError – If no adapter can interpret the locator.

Return type:

None

ogcat.storage.ensure_parent_directory(locator, *, adapter=None)[source]¶

Create parent directories for a file-like target.

Parameters:

locator (ArtifactLocator) – File-like target locator whose parent should exist.
adapter (StorageAdapter | None) – Optional pre-resolved storage adapter.

Raises:

ValueError – If no adapter can interpret the locator.

Return type:

None

ogcat.storage.ensure_target_absent(locator, *, adapter=None)[source]¶

Raise if a target already exists.

Parameters:

locator (ArtifactLocator) – Target locator to check.
adapter (StorageAdapter | None) – Optional pre-resolved storage adapter.

Raises:

FileExistsError – If the target exists.
ValueError – If no adapter can interpret the locator.

Return type:

None

ogcat.storage.plan_storage(locator, *, target_kind='file', write_mode='reference', checksum='none', ogcat_owned=False, profile=None, adapter=None, time_added=None, storage_relative_path=None, resolved_directory=None, resolved_filename=None)[source]¶

Build a storage plan from already-resolved storage decisions.

Parameters:

locator (ArtifactLocator) – Target locator that should be recorded for the artifact.
target_kind (Literal['file', 'directory']) – Whether the target is file-like or directory-like.
write_mode (Literal['copy', 'move', 'write', 'reference']) – Intended materialisation mode.
checksum (Literal['none']) – Checksum policy requested for the write.
ogcat_owned (bool) – Whether ogcat should treat the target as managed.
profile (str | None) – Optional storage profile name or hint.
adapter (str | None) – Optional adapter identifier, such as "local" or "fsspec".
time_added (str | None) – Optional timestamp used when rendering date-based storage templates.
storage_relative_path (str | None) – Optional target path relative to the configured storage root.
resolved_directory (str | None) – Optional rendered directory path for template-based storage.
resolved_filename (str | None) – Optional rendered filename or final path component.

Return type:

StoragePlan

Returns:

Storage plan describing the target and intended write.

ogcat.storage.register_remove_on_rollback(rollback, locator, *, target_kind='file', adapter=None, description=None)[source]¶

Parameters:

rollback (_RollbackRegistrar) – Rollback registration callback, such as ogcat.hooks.OperationContext.rollback().
locator (ArtifactLocator) – Target locator to remove if rollback runs.
target_kind (Literal['file', 'directory']) – Whether the target is file-like or directory-like.
adapter (StorageAdapter | None) – Optional pre-resolved storage adapter.
description (str | None) – Optional human-readable rollback description.

Raises:

ValueError – If no adapter can interpret the locator.

Return type:

None

ogcat.storage.remove_target(locator, *, target_kind='file', adapter=None)[source]¶

Remove a file-like or directory-like target.

Parameters:

locator (ArtifactLocator) – Target locator to remove.
target_kind (Literal['file', 'directory']) – Whether to remove a file-like or directory-like target.
adapter (StorageAdapter | None) – Optional pre-resolved storage adapter.

Raises:

ValueError – If no adapter can interpret the locator.

Return type:

None

ogcat.storage.require_local_path(locator)[source]¶

Return a local path for a path-backed locator.

Parameters:: locator (ArtifactLocator) – Artifact locator expected to contain a local path.
Return type:: Path
Returns:: Local filesystem path represented by the locator.
Raises:: ValueError – If the locator is not path-backed.

ogcat.storage.require_storage_target(locator)[source]¶

Return an adapter for a filesystem-like target locator.

Parameters:: locator (ArtifactLocator) – Artifact locator that should be writable through a storage adapter.
Return type:: StorageAdapter
Returns:: Storage adapter that can operate on the locator.
Raises:: ValueError – If the locator kind is not filesystem-like.