open_octx()

open_octx() safely opens a .octx ZIP/ZIP64 file or an already unpacked OCTX directory and returns a read-only OctxPackage.

Signature

def open_octx(
    source: os.PathLike[str] | str,
    *,
    limits: ArchiveLimits | None = None,
) -> OctxPackage

What it does

The open phase:

• Scans every ZIP or directory entry, including entries not listed in the manifest.
• Rejects path traversal, symbolic links, encrypted entries, unsupported compression methods, and differences between local and central headers.
• Limits the number of entries, single-file size, total uncompressed size, and compression ratio.
• Reads and parses manifest.json, then creates a read-only payload view.

What it does not do

open_octx() does not currently perform full validation of file digests, JSON Schema, Capabilities, relationship coverage, or vector content. It does not write to the source.

Call validate_octx() when full validation is required:

from octx import open_octx, validate_octx

with open_octx("asset.octx") as package:
    report = validate_octx(package)
    if not report.valid:
        raise ValueError(report.to_dict())
    print(package.manifest["asset"])

Lifecycle

Using with is recommended so open file descriptors and the ZIP reader are closed:

with open_octx("asset.octx") as package:
    documents = list(package.iter_documents())

You can also call package.close() explicitly. Any subsequent read raises ValueError.

Failure modes

If the container cannot be opened safely, a subclass of OctxOpenError is raised, for example:

• OctxFormatError: corrupt ZIP, manifest, or encoding format.
• OctxSecurityError: unsafe path, link, encryption, or input that changes during a read.
• OctxResourceLimitError: input exceeds a resource limit.

To convert untrusted format errors into a report instead of exceptions, call validate_octx(path) directly.