mafw.storage

Public logical-storage types and runtime service.

Logical storage identifies files by a volume name and portable relative path. The LogicalFileReference value object handles that lexical identity; the StorageService resolves it against literal roots from a parsed storage configuration at runtime. The service validates each volume against the StorageVolume standard table and its UUID marker before resolving references or opening files.

Construct the service with the parsed storage configuration, the runtime PathResolutionContext, and the environment mapping used to interpolate roots. The caller owns database configuration and standard-table creation and must call initialize() explicitly. The service does not alter steering root values, create configured roots, or connect to or migrate a database.

Volume markers named .mafw_<volume>_uuid are administrative identity files. Explicit initialization may create a marker for a new volume even when its MAFw data-access policy is read-only or protected, if the operating system grants write permission. Ordinary file operations still enforce the configured policy; protected permits reads and writes but the service has no deletion operation.

exception mafw.storage.StorageConfigurationError

Bases: StorageError

A configured volume cannot be used by the filesystem service.

Added in version 2.4.

exception mafw.storage.StorageError

Bases: Exception

Base exception for storage-service failures.

Added in version 2.4.

exception mafw.storage.StorageInitializationError

Bases: StorageError

A configured volume root or persistent identity could not be validated.

Added in version 2.4.

exception mafw.storage.StorageRecoveryError

Bases: StorageInitializationError

Registration failed and compensating cleanup also failed.

Added in version 2.4.

exception mafw.storage.StorageVolumeNotFoundError

Bases: StorageError, KeyError

A reference or metadata request names an unconfigured volume.

Added in version 2.4.

class mafw.storage.LogicalFileReference(volume: str, relative_path: PurePosixPath)

Bases: object

Identify a file by storage volume name and a portable relative path.

The serialized form is <volume>:<relative/path>. Volume names contain only ASCII letters, digits, underscores, and hyphens. Paths use POSIX separators and cannot be absolute or contain .. components. Redundant separators and . components are normalized away. The reference is lexical; it does not validate a configured volume or resolve a filesystem path.

Parameters:

• volume – Case-sensitive logical volume name.

• relative_path – POSIX-style path relative to that volume.

Added in version 2.4.

classmethod from_parameter_value(value: object) → LogicalFileReference

Convert a serialized processor parameter value into this type.

Parameters:

value – An existing reference or its serialized string.

Returns:

The typed logical file reference.

Raises:

• TypeError – If value is neither a reference nor a string.

• ValueError – If the serialized reference is malformed.

Added in version 2.4: Added the optional processor-parameter conversion hook.

classmethod from_string(value: str) → LogicalFileReference

Parse and validate a serialized logical file reference.

Parameters:

value – String in <volume>:<relative/path> form.

Returns:

The validated logical reference.

Raises:

• TypeError – If value is not a string.

• ValueError – If the serialized reference is malformed.

Added in version 2.4.

to_string() → str

Return the canonical portable serialization.

Returns:

Canonical <volume>:<relative/path> representation.

Added in version 2.4.

class mafw.storage.StorageService(configuration: StorageConfiguration, path_context: PathResolutionContext, environment: Mapping[str, str])

Bases: object

Resolve logical references and access initialized storage volumes.

Construction is lightweight. Call initialize() after the caller has configured the MAFw Peewee database and created the StorageVolume table. Initialization can register a new volume by creating its UUID marker and database row. This registration write is administrative identity setup and is allowed for any logical access policy when OS permissions permit it. The read-only policy still prevents data-file writes through this service.

Parameters:

• configuration – Parsed storage configuration with literal root values.

• path_context – Runtime context used to resolve configured roots.

• environment – Resolved environment mapping for root interpolation.

Added in version 2.4.

static _mode_writes(mode: str) → bool

Validate Python mode syntax and report whether it can mutate data.

static _reference_from_contained(volume: StorageVolumeInfo, path: Path) → LogicalFileReference

Convert a checked physical path to its portable relative reference.

static _reject_dangling_symlinks(root: Path, candidate: Path) → None

Reject any existing symlink component that cannot be resolved strictly.

_check_containment(volume: StorageVolumeInfo, candidate: Path) → Path

Canonicalize an output-capable path and verify root containment.

_contained_absolute_path(volume: StorageVolumeInfo, candidate: Path) → Path

Resolve an absolute candidate and require it to remain in one root.

_contained_path(volume: StorageVolumeInfo, relative: Path) → Path

Resolve a relative target and reject symlink escape or dangling links.

_create_marker_exclusively(marker: Path, identity: str) → None

Write a UUID marker without following or replacing an existing file.

_initialize_volume(name: str, config: StorageVolumeConfiguration, db: Database) → StorageVolumeInfo

Resolve one root, validate/register identity, and build its view.

_read_marker(name: str, marker: Path) → str

Read a canonical UUID4 marker without following a symlink.

_reference_for_path(volume: StorageVolumeInfo, path: Path) → LogicalFileReference

Apply the same canonical containment rules for explicit-volume paths.

_register_new_volume(name: str, marker: Path, db: Database) → str

Create a new marker exclusively, then insert its DB identity.

_remove_created_marker(marker: Path, identity: str) → None

Compensate only if this attempt’s regular marker is still unchanged.

_require_database() → tuple[Any, Database]

Find the registered StorageVolume model and require its active DB.

_require_initialized() → None

Reject runtime operations until the complete volume set is valid.

_require_volume_model() → Any

Return the model resolved from MAFw’s registry for this initialization.

_validate_unique_identity(name: str, identity: str) → None

Ensure a database UUID does not identify another logical volume.

_volume_for_reference(reference: LogicalFileReference | str) → StorageVolumeInfo

Return initialized volume metadata for a reference.

delete(reference: LogicalFileReference | str | Sequence[LogicalFileReference | str]) → None

Delete one or more referenced files on fully accessible volumes.

Each reference is validated before unlinking. A missing target is idempotent success; other filesystem and storage failures are raised. For a sequence, all references are attempted and failures are reported together so callers can retain their queue entry and retry safely.

Parameters:

reference – One logical reference or an ordered sequence.

Raises:

• PermissionError – If any referenced volume is not full.

• ExceptionGroup – If one or more sequence items cannot be deleted.

Added in version 2.4: Added policy-aware deletion for logical storage references.

generate_reference(path: Path | str, *, volume: str | None = None) → LogicalFileReference

Create a logical reference for an absolute path within one volume.

Parameters:

• path – Absolute path, which may identify a not-yet-created output.

• volume – Optional explicit volume when root membership is ambiguous.

Returns:

A normalized portable logical reference.

Raises:

StorageError – If the path is relative, outside the selected root, or ambiguous across configured roots.

Added in version 2.4.

get_volume(name: str) → StorageVolumeInfo

Return validated immutable runtime metadata for a configured volume.

Parameters:

name – Case-sensitive logical volume name.

Returns:

Resolved volume metadata.

Raises:

• RuntimeError – If initialization has not completed.

• StorageVolumeNotFoundError – If the name is not configured.

Added in version 2.4.

initialize() → None

Resolve and validate all volumes, registering new identities safely.

Existing markers and database identities are never modified when a volume is unavailable or mismatched. Successfully created registrations are durable even if a later configured volume fails; a subsequent call validates those records as existing volumes.

Raises:

• StorageInitializationError – If database, root, marker, or identity validation fails.

• StorageConfigurationError – If configuration is unusable.

Added in version 2.4.

open(reference: LogicalFileReference | str, mode: str = 'r', **kwargs: Any) → IO[Any]

Open a referenced file while enforcing its logical access policy.

full and protected permit standard Python file modes, including overwrite and append. read-only permits modes without +, w, a or x. The service does not create parent directories. Text access defaults to UTF-8; callers may pass other open keyword arguments. protected has no deletion API in this public surface.

Parameters:

• reference – A validated reference or serialized reference string.

• mode – Standard Python file mode.

• kwargs – Additional arguments forwarded to Path.open().

Returns:

An open file object.

Raises:

• PermissionError – If the mode violates the volume policy.

• OSError – Filesystem errors, with their original cause preserved when contextualized by path validation.

Added in version 2.4.

resolve(reference: LogicalFileReference | str) → Path

Resolve a logical reference to a contained physical path.

The target need not exist, allowing callers to prepare output paths. Existing symlinks are followed only when their targets remain inside the effective volume root. This path-based check cannot prevent a symlink replacement between validation and a later filesystem call.

Parameters:

reference – A validated reference or its serialized string.

Returns:

Canonical contained path, possibly not yet present.

Raises:

StorageError – If the service is not initialized or resolution would escape the configured root.

Added in version 2.4.

property initialized: bool

Whether all configured volumes passed initialization.

Added in version 2.4.

class mafw.storage.StorageVolumeInfo(name: str, configured_root: str, root: Path, type: VolumeStorageType, access: StorageAccess, parameters: Mapping[str, Any], uuid: uuid.UUID)

Bases: object

Resolved runtime metadata for one validated volume.

Parameters:

• name – Case-sensitive logical volume name.

• configured_root – Literal root expression from steering configuration.

• root – Resolved canonical filesystem root.

• type – Configured storage backend.

• access – MAFw access policy for service-managed operations.

• parameters – Read-only view of backend-specific settings.

• uuid – Validated persistent volume identity as a uuid.UUID.

Added in version 2.4.

Modules

logical_reference	Portable logical file references, independent of runtime storage roots.
service	Runtime access to configured logical storage volumes.