Skip to content

Containers

Container APIs are the normal entry point. They open one or many image paths and return structured success/error results instead of exposing parser tracebacks.

Unified object loading for axklib container formats.

Classes

OpenOptions dataclass

Options that control container loading.

Use these when opening images to choose partition limits, whether payload bytes should be loaded, and whether unsupported or malformed inputs should fail strictly.

Attributes

max_partitions class-attribute instance-attribute 
max_partitions: int | None = 8
include_payloads class-attribute instance-attribute 
include_payloads: bool = True
strict class-attribute instance-attribute 
strict: bool = False

AxklibContainer dataclass

Loaded Yamaha-capable container with decoded object payloads.

Use this as the primary result of opening one SFS/HDA/HDS image, ISO9660 disc image, FAT floppy image, standalone object, or directory expansion.

Attributes

source_path instance-attribute 
source_path: Path
kind instance-attribute 
kind: str
detected_format instance-attribute 
detected_format: str
objects instance-attribute 
objects: tuple[AxklibObject, ...]
recovery_quality_summary instance-attribute 
recovery_quality_summary: dict[str, int]
issues class-attribute instance-attribute 
issues: tuple[str, ...] = ()

AxklibContainerLoadError dataclass

Structured error for an input path that could not be opened as a supported container.

Use this in multi-input workflows so one bad file can be reported without discarding successfully loaded containers.

Attributes

path instance-attribute 
path: Path
error_code instance-attribute 
error_code: str
message instance-attribute 
message: str
recoverable instance-attribute 
recoverable: bool
original_exception class-attribute instance-attribute 
original_exception: str = ''

AxklibContainerLoadResult dataclass

Per-path load result containing either a container or a structured load error.

Use this for corpus scans and CLI commands that need deterministic failure reporting across many inputs.

Attributes

path instance-attribute 
path: Path
container class-attribute instance-attribute 
container: AxklibContainer | None = None
error class-attribute instance-attribute 
error: AxklibContainerLoadError | None = None

AxklibContainerUnsupportedError

Exception raised when a path is readable but not a supported axklib container.

The code attribute is intended for stable diagnostics rather than user-facing traceback text.

Attributes

code instance-attribute 
code = code

Functions:

open 

open(
    path: str | Path, *, options: OpenOptions | None = None
) -> AxklibContainer

open_many 

open_many(
    paths: Iterable[str | Path],
    *,
    options: OpenOptions | None = None,
) -> list[AxklibContainerLoadResult]