unpack_octx()

Validate and safely unpack an OCTX Package while preventing overwrites and unsafe paths.

After validation succeeds, unpack_octx() safely unpacks the OCTX manifest and every declared payload into a destination directory. It is the OCTX alternative to the generic ZIP extractall() method.

Signature

def unpack_octx(
    package_or_source: OctxPackage | os.PathLike[str] | str,
    destination: os.PathLike[str] | str,
    *,
    limits: ArchiveLimits | None = None,
) -> Path

Parameter	Purpose
`package_or_source`	A `.octx` path, unpacked directory, or open `OctxPackage`.
`destination`	Destination directory; it must not exist or must be empty, and it cannot be a filesystem root.
`limits`	`ArchiveLimits` used while opening, validating, and copying.

Basic usage

from octx import unpack_octx

destination = unpack_octx(
    "./product-guide.octx",
    "./product-guide-expanded",
)
print(destination)

Security and atomicity

The unpacking workflow:

Calls validate_octx() and rejects an invalid OCTX Package or a known invalid layer.
Checks the destination path for symbolic links, platform path aliases, and case collisions.
Copies only manifest.json and payloads declared by manifest.files.
Recomputes each payload's SHA-256 while copying to prevent source changes after validation.
Writes to a temporary directory first and atomically publishes the destination only after every step succeeds.

Safe ordinary archive files that are not listed in the manifest are not unpacked. With an unknown optional layer or missing optional validator, a Package may have valid=True and fully_validated=False; callers can inspect the report first and apply a stricter acceptance policy.

Failure modes

Invalid Package: raises OctxValidationError, whose error.report contains every issue.
Non-empty destination directory or destination occupied by other content: raises FileExistsError.
Unsafe destination path or source that changes during copying: raises OctxSecurityError.

When passed an already open OctxPackage, the function does not close the caller-owned object. When passed a path, it opens and closes the Package itself.