- `--input PATH`, `--in PATH`: Use an existing zipapp as the starting point. Can be a file path or directory. When a directory is given, zipbundler resolves the zip file name using the output filename

zipbundler build --input dist/app.pyz --force

zipbundler build --input dist --force

zipbundler build --input existing.pyz --add-include new_module.py --force

zipbundler build --input dist/app.pyz --force

zipbundler build --input existing.pyz --add-include src/new_module.py --force

The `--input` flag allows you to start from an existing zipapp and update it with new or modified packages:

zipbundler build -o dist/app.pyz

zipbundler build --input dist/app.pyz --force

**Use Cases:**

- **Incremental development**: Add new modules without rebuilding everything

- **Staged builds**: Build base packages once, then add features incrementally

- **Configuration updates**: Update package metadata while preserving application code

- **Patching**: Apply updates to specific packages in a production build

import pathspec as ps

def _should_exclude_file(path: str, excludes: list[dict[str, object]]) -> bool:

"""Check if a file path matches any exclude pattern.

if not excludes:

return False

for exc in excludes:

pattern = exc.get("path", "")

if not isinstance(pattern, str):

continue

# Create a PathSpec from the pattern and check the path

try:

spec = ps.PathSpec.from_lines("gitwildmatch", [pattern])

if spec.match_file(path):

return True

except ValueError:

# If pattern is invalid, skip it and continue checking other patterns

pass

return False

zip_includes: list[tuple[Path, Path | None]] | None = None,

input_archive: Path | str | None = None,

preserve_input_files: bool = True,

if input_archive:

logger.debug("Input archive: %s", input_archive)

# Track which files are being added from the new build

# (for updating/overwriting in the input archive)

new_files_by_arcname: dict[str, tuple[Path, Path]] = {}

arcname_path = f.relative_to(archive_root)

arcname_str = str(arcname_path)

files_to_include.append((f, arcname_path))

new_files_by_arcname[arcname_str] = (f, arcname_path)

logger.trace("Added file: %s -> %s", f, arcname_str)

arcname_path = Path(dest) if dest else Path(file_path.name)

arcname_str = str(arcname_path)

files_to_include.append((file_path, arcname_path))

new_files_by_arcname[arcname_str] = (file_path, arcname_path)

logger.trace("Added additional file: %s -> %s", file_path, arcname_str)

# Track files from zip includes

zip_files_to_include: dict[str, bytes] = {}

if zip_includes:

logger.debug("Processing %d zip includes", len(zip_includes))

for zip_path, dest in zip_includes:

if not zip_path.exists():

msg = f"Zip include not found: {zip_path}"

raise FileNotFoundError(msg)

if not zip_path.is_file():

msg = f"Zip include is not a file: {zip_path}"

raise ValueError(msg)

logger.debug("Extracting zip: %s", zip_path)

# Read zip file (handle shebang if present)

try:

with zip_path.open("rb") as file_handle:

first_two = file_handle.read(2)

if first_two == b"#!":

file_handle.readline()

else:

file_handle.seek(0)

zip_data = file_handle.read()

# Extract files from zip

temp_zip = io.BytesIO(zip_data)

with zipfile.ZipFile(temp_zip, "r") as zf:

for name in zf.namelist():

# Skip PKG-INFO if we're generating new metadata

if name == "PKG-INFO" and metadata:

logger.trace(

"Skipping PKG-INFO from zip %s (generating new)",

zip_path.name,

)

continue

# Skip __main__.py if we're generating new entry point

if name == "__main__.py" and entry_point is not None:

logger.trace(

"Skipping __main__.py from zip %s (generating new)",

zip_path.name,

)

continue

# Apply dest remapping if provided

zip_arcname: str = str(Path(dest) / name) if dest else name

# Apply exclude patterns

excludes_list: list[dict[str, object]] = [

{"path": e.get("path", "")} for e in (excludes or [])

]

should_exclude = excludes_list and _should_exclude_file(

zip_arcname, excludes_list

)

if should_exclude:

logger.trace(

"Excluded from zip %s: %s", zip_path.name, name

)

continue

# Read file content

zip_files_to_include[zip_arcname] = zf.read(name)

logger.trace(

"Added from zip %s: %s", zip_path.name, zip_arcname

)

except zipfile.BadZipFile as e:

msg = f"Invalid zip file in include: {zip_path}"

raise ValueError(msg) from e

entry_point_count = 1 if entry_point is not None else 0

file_count = len(files_to_include) + len(zip_files_to_include) + entry_point_count

# If input archive is provided, read it first and preserve existing files

existing_files: dict[str, bytes] = {}

if input_archive:

input_path = Path(input_archive).resolve()

if not input_path.exists():

msg = f"Input archive not found: {input_path}"

raise FileNotFoundError(msg)

if not input_path.is_file():

msg = f"Input archive is not a file: {input_path}"

raise ValueError(msg)

# Read existing zip file content (skipping shebang if present)

try:

with input_path.open("rb") as file_handle:

# Check for shebang (first 2 bytes are #!)

first_two = file_handle.read(2)

if first_two == b"#!":

# Skip shebang line

file_handle.readline()

else:

# No shebang, rewind to start

file_handle.seek(0)

# Read remaining data (the zip file)

zip_data = file_handle.read()

# Extract files from the existing archive

temp_zip = io.BytesIO(zip_data)

with zipfile.ZipFile(temp_zip, "r") as input_zf:

for name in input_zf.namelist():

# Skip PKG-INFO if we're generating new metadata

if name == "PKG-INFO" and metadata:

logger.trace(

"Skipping PKG-INFO from input archive (will generate new)"

)

continue

# Skip __main__.py if we're generating a new entry point

if name == "__main__.py" and entry_point is not None:

logger.trace(

"Skipping __main__.py from input archive (will "

"generate new)"

)

continue

# Skip files if preserve_input_files is False (--replace mode)

if not preserve_input_files:

logger.trace(

"Skipping file from input archive (--replace mode "

"wipes): %s",

name,

)

continue

# Store all other files except those being overwritten by new build

if name not in new_files_by_arcname:

existing_files[name] = input_zf.read(name)

logger.trace(

"Preserving existing file from input archive: %s", name

)

else:

logger.trace(

"Will overwrite existing file from input archive: %s", name

)

logger.info("Loaded input archive: %s", input_path)

except zipfile.BadZipFile as e:

msg = f"Invalid zip file in input archive: {input_path}"

raise ValueError(msg) from e

# Write all new Python files from packages

for file_path, file_arcname in files_to_include:

zf.write(file_path, str(file_arcname))

# Write files from zip includes

for zip_file_arcname, content in zip_files_to_include.items():

zf.writestr(str(zip_file_arcname), content)

logger.trace("Wrote zip include file: %s", zip_file_arcname)

# Write preserved files from input archive

for preserved_arcname, content in existing_files.items():

zf.writestr(preserved_arcname, content)

logger.trace("Wrote preserved file to output: %s", preserved_arcname)