comicbox.write

source module comicbox.write

Public write API: single-file write_metadata and batch bulk_write.

Wraps the existing Comicbox(...).dump() plumbing with a documented, Codex-facing surface:

  • mode: "additive" / "update" / "replace" — picks the merge strategy applied to the patch dict against the comic’s existing metadata. See :class:comicbox.config.settings.WriteMode.
  • formats: which on-archive formats to write back (ComicInfo.xml, comicbox.yaml, …). Names match the MetadataFormats enum value.
  • dry_run: return the would-be-written payload instead of touching the archive.

bulk_write orchestrates the same call over many files via a process- global ThreadPoolExecutor (writes are I/O bound — full archive repack per CBZ). A module-level semaphore caps concurrent writes so a big batch can’t starve other disk traffic.

Classes

Functions

source class WriteResult()

Per-file outcome of a write.

source class BulkWriteItem()

One unit of work for bulk_write.

source write_metadata(path: Path, patch: Mapping[str, Any], *, mode: Mode = ‘additive’, formats: Iterable[FormatName] | None = None, dry_run: bool = False, base_config: ComicboxSettings | None = None) → WriteResult

Write metadata to one comic archive.

patch is a comicbox-shaped dict — either the contents under the "comicbox" root tag, or the root-wrapped form Comicbox.to_dict returns ({"comicbox": {...}}); the wrapper is detected and unwrapped so the natural round-trip works.

With dry_run=True no archive is touched; the result’s dry_run_payload carries the serialized would-be-written content per requested format (keyed by format name).

Raises

source bulk_write(items: Iterable[BulkWriteItem], *, workers: int | None = None, on_event: EventHandler | None = None, stop_on_error: bool = False, cancel: threading.Event | None = None, base_config: ComicboxSettings | None = None) → Generator[WriteResult, None, None]

Write metadata to many files in parallel.

Returns an iterator that MUST be drained: writes are submitted in a bounded window as results are consumed, so discarding the iterator without iterating performs no writes. Input handling, the BatchStarted event, and pool creation happen eagerly at call time. Abandoning the iterator midway never blocks: queued writes are cancelled and in-flight ones finish in their worker threads.

Yields :class:WriteResult per file in completion order, not submission order. Caller may pass a cancel :class:threading.Event; once set, no new writes start: in-flight writes run to completion and every queued file is reported with cancelled=True. With stop_on_error=True the first failed write trips the same cancellation (an internal event is created if the caller didn’t pass one). on_event receives the shared :class:comicbox.events stream (BatchStarted / FileParsed / FileError / BatchFinished); cancelled files emit no per-file event.