API reference

Every name below is importable directly from the oaknut.zip namespace, e.g. from oaknut.zip import list_archive.

The library is function-shaped: there is no archive object to construct. Each entry point takes a path to a .zip file and works against the standard-library zipfile.ZipFile underneath. The metadata it recovers is carried in the shared AcornMeta dataclass and the MetaFormat enum from oaknut.file.

Inspecting an archive

oaknut.zip.list_archive(zipfile_path)

List ZIP contents with resolved Acorn metadata.

Parameters:

zipfile_path (Path) – Path to the ZIP file.

Returns:

A list of dicts, one per entry (excluding consumed .inf sidecars), with keys: filename, is_dir, file_size, load_address, exec_address, attr, filetype, source.

Raises:

click.ClickException – If the file is not a valid ZIP.

Return type:

list[dict]

oaknut.zip.archive_info(zipfile_path)

Return summary statistics of Acorn metadata in a ZIP file.

Parameters:

zipfile_path (Path) – Path to the ZIP file.

Returns:

filename, total, dirs, sparkfs_count, inf_count, pieb_inf_count, filename_count, plain_count, filetypes (a dict mapping filetype ints to counts).

Return type:

A dict with keys

Raises:

click.ClickException – If the file is not a valid ZIP.

Both return ordinary dictionaries; the symbolic keys they use are documented under Result dictionary keys below.

Extracting an archive

oaknut.zip.extract_archive(zipfile_path, output_dirpath, *, verbose=False, meta_format=MetaFormat.INF_TRAD, decode_filenames=True, owner=0)

Extract a ZIP file, preserving Acorn metadata.

Parameters:

  • zipfile_path (Path) – Path to the ZIP file.

  • output_dirpath (Path) – Directory to extract into.

  • verbose (bool) – Print extraction progress.

  • meta_format (MetaFormat | None) – Output metadata format, or None for raw extraction.

  • decode_filenames (bool) – Decode metadata from filename suffixes.

  • owner (int) – Econet owner ID for inf-pieb and xattr-pieb formats.

Raises:

click.ClickException – If the file is not a valid ZIP or xattr is requested on Windows.

Return type:

None

oaknut.zip.extract_member(zf, info, output_dirpath, *, verbose=False, meta_format=MetaFormat.INF_TRAD, decode_filenames=True, owner=0, inf_index=None)

Extract a single ZIP member, optionally writing metadata.

Writes the member’s data to output_dirpath and, when Acorn metadata is available, writes it in the requested meta_format.

Parameters:

  • zf (ZipFile) – An open ZipFile to read from.

  • info (ZipInfo) – The ZipInfo entry to extract.

  • output_dirpath (Path) – Directory to extract into.

  • verbose (bool) – Print extraction progress to stdout.

  • meta_format (MetaFormat | None) – Output metadata format, or None to skip metadata.

  • decode_filenames (bool) – Strip encoded metadata suffixes from filenames.

  • owner (int) – Econet owner ID for inf-pieb and xattr-pieb formats.

  • inf_index (dict[str, tuple[str, AcornMeta]] | None) – Pre-built index of bundled .inf metadata, as returned by build_inf_index().

Return type:

None

oaknut.zip.sanitise_extract_path(base_dirpath, member_path)

Sanitise a ZIP member path to prevent directory traversal.

Strips .., /, and \ components from the member path and resolves the result relative to base_dirpath.

Parameters:

  • base_dirpath (Path) – The root directory that all extracted paths must fall within.

  • member_path (str) – The raw path from the ZIP entry.

Returns:

A safe path under base_dirpath.

Raises:

ValueError – If the resolved path escapes base_dirpath.

Return type:

Path

extract_archive is the high-level entry point most callers want; extract_member exposes the per-entry mechanics for code that drives its own iteration over a zipfile.ZipFile. sanitise_extract_path is the traversal guard both rely on, surfaced for reuse.

Parsing and metadata resolution

These functions implement the three-source resolution described on the oaknut-zip page — they are exposed for callers that need to inspect a single source in isolation rather than the resolved result.

oaknut.zip.parse_sparkfs_extra(extra)

Parse SparkFS/ARC0 extra field data from a ZIP entry.

The extra field format (after the standard 4-byte ZIP extra header):

Offset Size Description 0 4 Signature “ARC0” 4 4 Load address (little-endian uint32) 8 4 Exec address (little-endian uint32) 12 4 Attributes (little-endian uint32) 16 4 Reserved (zero)

The Info-ZIP / David Pilling SparkFS specification defines only bits 0-7 of the Attributes field (the standard RISC OS access byte: R, W, L, PR, PW). Bits 8-31 have no documented meaning. In practice, archives produced by genuine RISC OS tooling write zero in the upper 24 bits, but some non-RISC-OS producers leave junk there. We mask to the low 8 bits so the stored attribute matches the Access enum semantics used throughout oaknut-file.

Parameters:

extra (bytes)

Return type:

AcornMeta | None

oaknut.zip.build_inf_index(zf)

Scan a ZIP for bundled .inf files and parse their metadata.

Returns (index, consumed) where:

  • index maps data filenames to (source_label, metadata)

  • consumed is the set of .inf ZIP member filenames that were parsed

Parameters:

zf (ZipFile)

Return type:

tuple[dict[str, tuple[str, AcornMeta]], set[str]]

oaknut.zip.resolve_metadata(info, *, decode_filenames=True, inf_index=None)

Extract metadata and clean filename from a ZIP entry.

Priority: SparkFS extra fields > bundled INF > filename encoding.

Returns (source_label, clean_filename, metadata).

Parameters:
Return type:

tuple[str | None, str, AcornMeta | None]

Result dictionary keys

list_archive and archive_info return stringly-keyed dicts. These module-level constants name those keys so callers need not hard-code the strings.

Per-entry keys — one dict per member from list_archive:

oaknut.zip.FILENAME_KEY = 'filename'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.IS_DIR_KEY = 'is_dir'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.FILE_SIZE_KEY = 'file_size'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.LOAD_ADDR_KEY = 'load_address'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.EXEC_ADDR_KEY = 'exec_address'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.ATTR_KEY = 'attr'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.FILETYPE_KEY = 'filetype'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.SOURCE_KEY = 'source'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

Summary keys — the single dict returned by archive_info:

oaknut.zip.TOTAL_KEY = 'total'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.DIRS_KEY = 'dirs'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.SPARKFS_COUNT_KEY = 'sparkfs_count'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.INF_COUNT_KEY = 'inf_count'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.PIEB_INF_COUNT_KEY = 'pieb_inf_count'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.FILENAME_COUNT_KEY = 'filename_count'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.PLAIN_COUNT_KEY = 'plain_count'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

oaknut.zip.FILETYPES_KEY = 'filetypes'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.