Top-level API

Everything on this page is importable directly from openauc.

import openauc

openauc.load(...)
openauc.available_formats()
openauc.export_aucx(...)
openauc.inspect_aucx(...)
openauc.validate_aucx(...)
openauc.__version__

Loading

load

load(
    path: str | Path,
    *,
    format: str | None = None,
    manifest: str | Path | None = None,
) -> AUCExperiment

Load a generic delimited AUC experiment into an AUCExperiment.

Also reads AUCX archives: a .aucx file, or any path with format="aucx", is dispatched to the archive reader, which verifies every stored checksum before building a model.

Parameters:

Name	Type	Description	Default
path	str | Path	A directory containing a manifest and data file, a data-file path with an adjacent manifest, a manifest-file path, or an .aucx archive.	required
format	str | None	Optional explicit format id (overrides detection and the manifest's declared format for parser selection).	None
manifest	str | Path | None	Optional explicit manifest-file path.	None

Returns:

Type	Description
AUCExperiment	A canonical :class:AUCExperiment with import provenance attached. For
AUCExperiment	an archive this is the provenance stored inside it, unchanged.

Source code in src/openauc/formats/loader.py

def load(
    path: str | Path,
    *,
    format: str | None = None,
    manifest: str | Path | None = None,
) -> AUCExperiment:
    """Load a generic delimited AUC experiment into an ``AUCExperiment``.

    Also reads AUCX archives: a ``.aucx`` file, or any path with
    ``format="aucx"``, is dispatched to the archive reader, which verifies every
    stored checksum before building a model.

    Args:
        path: A directory containing a manifest and data file, a data-file path
            with an adjacent manifest, a manifest-file path, or an ``.aucx``
            archive.
        format: Optional explicit format id (overrides detection and the
            manifest's declared format for parser selection).
        manifest: Optional explicit manifest-file path.

    Returns:
        A canonical :class:`AUCExperiment` with import provenance attached. For
        an archive this is the provenance stored inside it, unchanged.
    """
    target = Path(path)
    explicit_manifest = Path(manifest) if manifest is not None else None
    if not target.exists():
        raise ParseError(f"path does not exist: {target}")

    if _is_archive_request(target, format):
        return read_aucx(target)

    base_dir, manifest_file, explicit_data = _resolve_layout(target, explicit_manifest)
    manifest_model = load_manifest(manifest_file)
    data_file = _resolve_data_file(base_dir, manifest_model, explicit_data)
    source = ResolvedSource(
        base_dir=base_dir, data_file=data_file, manifest_file=manifest_file
    )

    delimiter = _resolve_delimiter(data_file, manifest_model)
    table = _read_table(data_file, delimiter)

    parser, selection_warnings = _select_parser(format, manifest_model, table)
    result = parser.parse(table, source, manifest_model)
    return _with_provenance(result, parser, source, selection_warnings)

Format discovery

available_formats

available_formats() -> tuple[FormatInfo, ...]

Public descriptions of every registered format, sorted by id.

Covers both table parsers and archive formats.

Source code in src/openauc/formats/registry.py

def available_formats() -> tuple[FormatInfo, ...]:
    """Public descriptions of every registered format, sorted by id.

    Covers both table parsers and archive formats.
    """
    descriptions = {key: parser.info() for key, parser in _REGISTRY.items()}
    descriptions.update(_ARCHIVE_FORMATS)
    return tuple(descriptions[key] for key in sorted(descriptions))

Archives

export_aucx

export_aucx(
    experiment: AUCExperiment,
    path: str | Path,
    *,
    overwrite: bool = False,
    exported_at: datetime | None = None,
) -> Path

Write experiment to an AUCX archive and return the written path.

The archive is written to a sibling temporary file, verified by reading it back in full, and only then moved into place — so a failure never leaves a partial or corrupt archive at the destination.

Parameters:

Name	Type	Description	Default
experiment	AUCExperiment	The experiment to archive.	required
path	str | Path	Destination .aucx path.	required
overwrite	bool	Replace an existing file. Refuses by default.	False
exported_at	datetime | None	Timestamp recorded in the export provenance. Defaults to the current UTC time; pass a fixed value for byte-identical output.	None

Returns:

Type	Description
Path	The path written.

Raises:

Type	Description
ArchiveError	if the destination exists and overwrite is False, or if the archive fails its own verification.

Source code in src/openauc/formats/aucx.py

def export_aucx(
    experiment: AUCExperiment,
    path: str | Path,
    *,
    overwrite: bool = False,
    exported_at: datetime | None = None,
) -> Path:
    """Write ``experiment`` to an AUCX archive and return the written path.

    The archive is written to a sibling temporary file, verified by reading it
    back in full, and only then moved into place — so a failure never leaves a
    partial or corrupt archive at the destination.

    Args:
        experiment: The experiment to archive.
        path: Destination ``.aucx`` path.
        overwrite: Replace an existing file. Refuses by default.
        exported_at: Timestamp recorded in the export provenance. Defaults to
            the current UTC time; pass a fixed value for byte-identical output.

    Returns:
        The path written.

    Raises:
        ArchiveError: if the destination exists and ``overwrite`` is False, or
            if the archive fails its own verification.
    """
    from openauc import __version__

    destination = Path(path)
    if destination.exists() and not overwrite:
        raise ArchiveError(
            f"refusing to overwrite existing file: {destination}; "
            "pass overwrite=True to replace it"
        )
    if destination.parent and not destination.parent.exists():
        raise ArchiveError(
            f"destination directory does not exist: {destination.parent}"
        )

    export = AUCXExport(
        software_version=__version__,
        exported_at=exported_at if exported_at is not None else datetime.now(UTC),
        member_count=len(PAYLOAD_MEMBERS) + 1,
    )
    members = _build_members(experiment, export)

    handle, temporary_name = tempfile.mkstemp(
        dir=str(destination.parent or Path()), prefix=".aucx-", suffix=".tmp"
    )
    os.close(handle)
    temporary = Path(temporary_name)
    try:
        _write_zip(temporary, members)
        # Verify the completed archive before it replaces anything.
        read_aucx(temporary)
        os.replace(temporary, destination)
    except BaseException:
        temporary.unlink(missing_ok=True)
        raise
    return destination

inspect_aucx

inspect_aucx(path: str | Path) -> AUCXInfo

Verify an archive's integrity and report what it declares.

This is container-level inspection only. It reports nothing about the structural or scientific standing of the experiment inside.

Source code in src/openauc/formats/aucx.py

def inspect_aucx(path: str | Path) -> AUCXInfo:
    """Verify an archive's integrity and report what it declares.

    This is container-level inspection only. It reports nothing about the
    structural or scientific standing of the experiment inside.
    """
    target = Path(path)
    payloads, manifest = _read_verified(target)
    block = manifest.get("observations")
    observations_block = block if isinstance(block, dict) else {}
    experiment_payload = _loads(payloads[EXPERIMENT_MEMBER], EXPERIMENT_MEMBER, target)
    metadata = experiment_payload.get("metadata")
    experiment_id = (
        str(metadata.get("experiment_id")) if isinstance(metadata, dict) else None
    )
    try:
        mode = RadiusAxisMode(str(observations_block.get("mode")))
    except ValueError as exc:
        raise ArchiveError(f"{target.name}: invalid radius axis mode: {exc}") from exc
    return AUCXInfo(
        path=str(target),
        aucx_format_version=str(manifest["aucx_format_version"]),
        export=_export_record(payloads, target),
        members=tuple(sorted(payloads)),
        checksum_verified=True,
        radius_axis_mode=mode,
        n_scans=int(observations_block.get("n_scans", 0)),
        n_points=int(observations_block.get("n_points", 0)),
        scan_ids=tuple(str(s) for s in observations_block.get("scan_ids", [])),
        radius_unit=Unit(
            str(observations_block.get("radius_unit", Unit.UNKNOWN.value))
        ),
        signal_unit=Unit(
            str(observations_block.get("signal_unit", Unit.UNKNOWN.value))
        ),
        experiment_id=experiment_id,
    )

validate_aucx

validate_aucx(path: str | Path) -> ArchiveValidationReport

Check an archive's integrity without raising.

Container-level validation only: readability, safety, member agreement and checksums. Structural and readiness validation of the experiment inside remain separate — load the archive and use experiment.validate().

Source code in src/openauc/formats/aucx.py

def validate_aucx(path: str | Path) -> ArchiveValidationReport:
    """Check an archive's integrity without raising.

    Container-level validation only: readability, safety, member agreement and
    checksums. Structural and readiness validation of the experiment inside
    remain separate — load the archive and use ``experiment.validate()``.
    """
    target = Path(path)
    try:
        info = inspect_aucx(target)
    except ArchiveVersionError as exc:
        return _failed(target, "unsupported_format_version", exc)
    except ArchiveIntegrityError as exc:
        return _failed(target, "checksum_verification_failed", exc)
    except ArchiveError as exc:
        return _failed(target, "archive_unreadable", exc)
    try:
        read_aucx(target)
    except ArchiveError as exc:
        return _failed(target, "archive_contents_invalid", exc, info=info)
    return ArchiveValidationReport(path=str(target), info=info)

read_aucx

read_aucx(path: str | Path) -> AUCExperiment

Read an AUCX archive into an :class:AUCExperiment.

Every checksum is verified before any model is constructed. The returned experiment carries the import provenance stored in the archive, unchanged, so a round trip preserves it; the export record is available separately via :func:inspect_aucx.

Raises:

Type	Description
ArchiveError	for unreadable, unsafe or inconsistent archives.
ArchiveIntegrityError	for checksum problems.
ArchiveVersionError	for an unsupported format version.

Source code in src/openauc/formats/aucx.py

def read_aucx(path: str | Path) -> AUCExperiment:
    """Read an AUCX archive into an :class:`AUCExperiment`.

    Every checksum is verified before any model is constructed. The returned
    experiment carries the *import* provenance stored in the archive, unchanged,
    so a round trip preserves it; the export record is available separately via
    :func:`inspect_aucx`.

    Raises:
        ArchiveError: for unreadable, unsafe or inconsistent archives.
        ArchiveIntegrityError: for checksum problems.
        ArchiveVersionError: for an unsupported format version.
    """
    target = Path(path)
    payloads, manifest = _read_verified(target)
    observations = _observations_from(manifest, payloads, target)
    return _experiment_from(payloads, observations, target)

See also

• Experiments and metadata
• AUCX archives