Library API
from filerepack import FileRepacker, PackResult, RepackOptions, RepackSummary
rp = FileRepacker()
summary = rp.repack("slides.pptx", options=RepackOptions(dryrun=True))
print(summary.total_insize, summary.total_outsize, summary.total_savings_pct)
for item in summary.results:
print(item.filepath, item.savings_pct)
repack is an alias of repack_zip_file. RepackSummary still supports the
0.1.x mapping:
summary['final'] # [insize, outsize, savings_pct]
summary['files'] # list of [path, in, out, pct]
summary['stats'] # [inner_count, inner_insize, inner_outsize]
Output destinations
DICOM processing requires filerepack[dicom] and a supported external encoder.
For direct verification, use
verify_output(candidate, "dcm", source_path=original) from filerepack.utils;
dicom and dic use the same check. Keep an unchanged original for comparison.
Calls without source_path return false because they cannot establish attribute
and pixel preservation. has_dicm_magic remains available in filerepack.dicom
for identification alone.
summary = rp.repack(
"notes.json",
outfile="out/notes.json",
options=RepackOptions(backup=True, backup_dir="backups"),
)
print(summary.filepath) # effective output path
A distinct outfile preserves source bytes for standalone and archive inputs.
If no improved candidate is accepted, it receives an unchanged copy verified
by byte identity for ordinary supported inputs. Scientific, NIB, CAR and WARC
profiles return the source without creating a distinct output when no candidate
is accepted. Refused processing also creates no fallback copy. SQLite outputs
use a consistent snapshot including committed WAL pages. Use a source-compatible
filename for a fallback copy. An accepted video/RAR conversion changes the
effective extension to .mp4/.7z,
and summary.filepath reports that destination. Source aliases, including
relative paths and filesystem links to the same file, are treated as an
in-place request at the source entry. Such a request refuses a file-symlink
source or multiple hard links. Linked sources remain readable for distinct
outputs.
Different existing destinations raise FileExistsError. Set
RepackOptions(overwrite=True) to explicitly replace a requested output or
conversion target. Required backups remain protected even with overwrite;
backup failure raises an error before encoding. A backup directory alone does
not enable backups. dryrun=True creates no output or backup artifacts and
sets result replaced=False while measuring staged candidates.
RepackOptions and dictionary requests share validation. Invalid ranges,
non-finite thresholds and unknown quality/profile values raise ValueError
before filesystem mutation. Active reservations coordinate filerepack
operations. The source snapshot and any existing output are rechecked after
staging, including content hashes and stat generations; changes raise a
conflict instead of replacing the file.
Permission mode, mtime and supported Linux/macOS xattrs are retained by the
library and direct format helpers. Native ACLs, ownership and Windows alternate
streams are outside the policy. durability="atomic" describes atomic
visibility; requests for crash durability raise ValueError before writes.
See Safety for platform limits and the final-check race.
Options
options = RepackOptions(
dryrun=False,
deep_walking=True,
pack_images=True,
pack_archives=True,
compression_level=9,
jpeg_quality=None, # set to enable lossy JPEG (also PDF images)
png_quality=None, # 'high'|'medium'|'low' enables pngquant
pdf_profile=None, # 'screen'|'ebook'|'printer'|'prepress'|'default'
pdf_linearize=False, # require linearized output; separate from compression
ole_recompress=False, # opt-in qualified OLE payload encoding
ole_embedded_recompress=False, # audited DOC/XLS child files
ole_deduplicate_images=False, # identical shared XLS/PPT images
lossy=False, # PDF uses Ghostscript /ebook unless pdf_profile is set
wmv_lossless=False,
convert_container=True,
keep_if_larger=True, # True discards output that is not smaller
keep_meta=False, # True also retains incidental metadata where supported
min_savings=None,
max_extract_bytes=None, # None = 8GiB default; 0 disables
max_extract_ratio=None, # None = 100× archive size
ultra=False, # Parquet zstd 22, zopflipng, mp3packer -z
quiet=False,
debug=False,
overwrite=False, # distinct existing outputs/conversion targets conflict
backup=False, # required before processing when enabled
backup_dir=None, # selector only; needs backup=True
durability="atomic", # atomic visibility; crash durability is unsupported
)
summary = rp.repack("data.parquet", options=options)
Profiles, selection and resource settings are also typed options:
from filerepack import options_for_profile
options = options_for_profile(
"maximum",
ultra=False, # explicit False overrides the profile
exclude_members=["originals/**"],
skip_categories=["video"],
max_depth=2, # optimization depth, root = 0
format_max_memory_bytes=512 * 1024 * 1024,
format_timeout=300.0,
tool_threads=1,
)
RepackOptions(profile="maximum", ultra=False) retains the same explicit
override. The CLI aliases --file-timeout and --max-temp-bytes correspond to
format_timeout and format_max_scratch_bytes; they are not Python option fields.
See shared options for defaults and accounting limits.
In-place SQLite needs RepackOptions(sqlite_offline=True) and closed users with
no sidecars. A distinct outfile uses the snapshot policy; single-file backups
of live WAL sources are refused. video_mode="remux" is the default;
video_mode="lossless" enables lossless encoding and video_mode="lossy"
requires lossy=True.
Parquet requires filerepack[parquet] or [data] with PyArrow 19+; accepted
candidates preserve schema, metadata and ordered values through batch verification.
ODF/EPUB control files are excluded from nested edits and their package structure
is validated before publication. Unsupported contracts retain the source; a
distinct output follows the unchanged-copy policy described above.
Pass on_progress to observe archive stages (extract, files, file,
write) or a standalone pack (standalone):
def on_progress(event, *, current=0, total=0, name=""):
print(event, current, total, name)
summary = rp.repack("slides.pptx", on_progress=on_progress)
A plain dict is still accepted as def_options=.
For legacy Office, rp.repack("report.doc", options=RepackOptions(ole_recompress=True))
enables qualified OfficeArt EMF/WMF/PNG/JPEG, PPT wrappers and HWP streams.
ole_embedded_recompress=True selects qualified DOC/XLS children;
ole_deduplicate_images=True selects identical shared XLS/PPT images. Install the ole-recompress extra and native
writer 0.4.0+. The isolated mode shares format_max_* budgets and format_timeout
with nested archives; its overall deadline is 120 seconds. Results include payload
counts, encoders, stream/file savings and fallback reasons. See
eligibility and preservation.
keep_if_larger=True is the CLI default (reject output that did not shrink).
--allow-grow sets it to False. ultra=True is Parquet zstd level 22, an
extra zopflipng PNG candidate, and mp3packer -z. Cover-art walking needs
pip install 'filerepack[media]'; lossless PDF image streams need
pip install 'filerepack[pdf]'.
Outcomes and read-only inspection
summary.outcome is the terminal RepackOutcome, with status, reason_code,
reason, actual source/destination, sizes and published. Its to_dict()
also includes the CLI-compatible file, output_file and savings fields.
Statuses are replaced, unchanged, skipped, unsupported, failed,
predicted and cancelled. Use summary.member_outcomes for nested events;
staged member savings do not imply outer publication.
from filerepack import inspect_file
inspection = inspect_file("notes.json", outfile="out/notes.json")
print(inspection.eligibility, inspection.blockers)
print(inspection.to_dict()["estimates"]["candidate_savings"]) # not measured
summary = rp.repack("notes.json", options=RepackOptions(dryrun=True))
if summary.outcome is not None:
print(summary.outcome.to_dict())
repack_store(source, output_parent, options) returns StoreResult for complete
offline local Zarr v2 stores. inspect_distributed_checkpoint(source, options)
returns a passive flat-directory inventory without loading pickle metadata.
Both are exported from filerepack; see store contracts
and DCP limits. CLI report/checkpoint flags belong to the
CLI coordinator and are not RepackOptions fields.
Format helpers
from filerepack.formats import identify_filename
from filerepack.repack import pack_gzip, pack_pdf, pack_jpg, pack_mp4
from filerepack.codecs import pack_sqlite, pack_jxl, pack_dcm, pack_xml, pack_json, pack_ogg
kind = identify_filename("slides.pptx")
print(kind.family, kind.key) # zip, pptx
result = pack_sqlite("notes.sqlite", sqlite_offline=True) # close users first
if result:
print(result.insize, result.outsize, result.replaced)
rp.pack_images(path, recursive=True) walks a directory of standalone
images/videos. Format coverage: Formats.
Existing helper imports from filerepack.repack and filerepack.codecs remain
supported after the implementations moved into format-family modules. Keyword
defaults, savings thresholds, dry-run behavior and PackResult are preserved.
The helpers share candidate verification/publication and operation-owned scratch
cleanup, including PNG encoder sidecars and WOFF2 tool directories.
Tool paths
from filerepack.tools import resolve_szip, doctor_rows, install_instructions
print(resolve_szip())
for row in doctor_rows():
print(row['tool'], row['status'], row['path'], row['install'])
print(install_instructions())