canonzip 1.0.0__tar.gz

canonzip-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyler Coles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

canonzip-1.0.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: canonzip
+Version: 1.0.0
+Summary: Produce canonical zips and hashes.
+Author: Tyler Coles
+Author-email: Tyler Coles <tylercoles@javadocmd.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pygit2==1.19.1
+Requires-Dist: typer==0.24.1
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/JavadocMD/canonzip.git
+Description-Content-Type: text/markdown
+
+# canonzip
+
+Produce canonical zips and hashes from directory contents.
+
+A canonical zip produces the exact same file for the same inputs,
+regardless of when it was made or what machine made it.
+
+A canonical hash produces the exact same hash for the same inputs,
+regardless of when it was made or what machine made it.
+
+This is particularly useful when zipping things like code for
+AWS Lambda Functions, where you want to upload a new zip if and
+only if the code has truly changed.
+
+canonzip supports two usage modes: as a CLI or as an API.
+
+Check out [`examples/terraform-aws-lambda`](./examples/terraform-aws-lambda/)
+for an example use-case.
+
+## Command Line Interface (CLI)
+
+### `canonzip hash [OPTIONS] TARGET`
+
+Print a canonical SHA-1 hash of `TARGET` to stdout.
+
+```
+$ canonzip hash path/to/target
+4959e4b9a1812e511570eee14fe65b90098a0db6
+```
+
+### `canonzip zip [OPTIONS] OUTPUT_PATH TARGET`
+
+Write a canonical zip archive of `TARGET` to `OUTPUT_PATH`.
+
+```
+$ canonzip zip path/to/output.zip path/to/target
+```
+
+NOTE: the output of `hash` is *NOT* the same as the SHA-1 hash of the output
+from `zip`. `hash` is specifically designed to avoid the extra overhead of
+writing a zip file while fulfilling a similar use-case &mdash; detecting
+changes in the files.
+
+### CLI options
+
+Both commands accept:
+
+| Option | Description |
+|---|---|
+| `--exclude TEXT, -e TEXT` | Glob pattern to exclude (repeatable) |
+| `--gitignore` | Exclude files based on `.gitignore` rules from the target's git repository |
+| `--follow-symlinks` | Follow symbolic links; otherwise symlinks are ignored |
+| `--verbose, -v` | Print included file paths (relative to target) to stderr |
+| `--json` | Output result as JSON (e.g. `{"hash": "..."}`) |
+
+If you specify both `exclude` and `gitignore`, files will be excluded as long
+as they match at least one rule (logical or).
+
+NOTE: exclude double-star globs (**) match one-or-more path segments;
+contrary to gitignore syntax where they match zero-or-more.
+
+## Programmatic Interface (API)
+
+### `canonzip.hash(target, *, exclude, gitignore, follow_symlinks) -> str`
+
+Compute a canonical SHA-1 hash of a directory.
+
+```python
+import canonzip
+
+digest = canonzip.hash("path/to/target")
+#> "4959e4b9a1812e511570eee14fe65b90098a0db6"
+```
+
+### `canonzip.zip(output_path, target, *, exclude, gitignore, follow_symlinks) -> None`
+
+Create a canonical zip archive of a directory.
+
+```python
+canonzip.zip("path/to/output.zip", "path/to/target")
+```
+
+### Shared options
+
+Both functions accept:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `exclude` | `list[str] \| None` | `None` | Glob patterns to exclude |
+| `gitignore` | `bool` | `False` | Exclude files based on `.gitignore` rules from the target's git repository |
+| `follow_symlinks` | `bool` | `False` | Follow symbolic links; if `False`, symlinks are ignored |
+
+If you specify both `exclude` and `gitignore`, files will be excluded as long
+as they match at least one rule (logical or).
+
+NOTE: exclude double-star globs (**) match one-or-more path segments;
+contrary to gitignore syntax where they match zero-or-more.
+
+### Exceptions
+
+canonzip will raise standard errors if it cannot read or write files,
+typically inheriting from `OSError`.
+
+Additionally there are special cases which raise errors which inherit
+from `canonzip.CanonzipError`:
+
+| Exception | Raised when |
+|---|---|
+| `OutputPathError` | `output_path` is inside `target` |
+| `GitRepositoryError` | `gitignore=True` but target is not in a git repo |
+| `BrokenSymlinkError` | A broken symlink is encountered with `follow_symlinks=True` |
+| `SymlinkCycleError` | A symlink cycle is detected with `follow_symlinks=True` |
+
+### Advanced: build manifests explicitly
+
+If you need direct access to the list of files that *would* be included in the
+canonical hash or zip, you can use `build_manifest` to read the target
+directory and return a `Manifest` object containing the list of files.
+To save yourself from having to generate the manifest twice, you can then pass
+it directly to `hash_from_manifest` or `zip_from_manifest` to complete the
+operation.
+
+```python
+from canonzip import build_manifest, hash_from_manifest, zip_from_manifest
+
+manifest = build_manifest("path/to/target", exclude=[".venv"])
+
+# Do something interesting with the manifest...
+print(manifest.target.as_posix())
+
+for entry in manifest.entries:
+    print(entry.path.as_posix())
+
+# Then compute the hash or zip
+digest = hash_from_manifest(manifest)
+zip_from_manifest("path/to/output.zip", manifest)
+```

canonzip-1.0.0/README.md

@@ -0,0 +1,137 @@
+# canonzip
+
+Produce canonical zips and hashes from directory contents.
+
+A canonical zip produces the exact same file for the same inputs,
+regardless of when it was made or what machine made it.
+
+A canonical hash produces the exact same hash for the same inputs,
+regardless of when it was made or what machine made it.
+
+This is particularly useful when zipping things like code for
+AWS Lambda Functions, where you want to upload a new zip if and
+only if the code has truly changed.
+
+canonzip supports two usage modes: as a CLI or as an API.
+
+Check out [`examples/terraform-aws-lambda`](./examples/terraform-aws-lambda/)
+for an example use-case.
+
+## Command Line Interface (CLI)
+
+### `canonzip hash [OPTIONS] TARGET`
+
+Print a canonical SHA-1 hash of `TARGET` to stdout.
+
+```
+$ canonzip hash path/to/target
+4959e4b9a1812e511570eee14fe65b90098a0db6
+```
+
+### `canonzip zip [OPTIONS] OUTPUT_PATH TARGET`
+
+Write a canonical zip archive of `TARGET` to `OUTPUT_PATH`.
+
+```
+$ canonzip zip path/to/output.zip path/to/target
+```
+
+NOTE: the output of `hash` is *NOT* the same as the SHA-1 hash of the output
+from `zip`. `hash` is specifically designed to avoid the extra overhead of
+writing a zip file while fulfilling a similar use-case — detecting
+changes in the files.
+
+### CLI options
+
+Both commands accept:
+
+| Option | Description |
+|---|---|
+| `--exclude TEXT, -e TEXT` | Glob pattern to exclude (repeatable) |
+| `--gitignore` | Exclude files based on `.gitignore` rules from the target's git repository |
+| `--follow-symlinks` | Follow symbolic links; otherwise symlinks are ignored |
+| `--verbose, -v` | Print included file paths (relative to target) to stderr |
+| `--json` | Output result as JSON (e.g. `{"hash": "..."}`) |
+
+If you specify both `exclude` and `gitignore`, files will be excluded as long
+as they match at least one rule (logical or).
+
+NOTE: exclude double-star globs (**) match one-or-more path segments;
+contrary to gitignore syntax where they match zero-or-more.
+
+## Programmatic Interface (API)
+
+### `canonzip.hash(target, *, exclude, gitignore, follow_symlinks) -> str`
+
+Compute a canonical SHA-1 hash of a directory.
+
+```python
+import canonzip
+
+digest = canonzip.hash("path/to/target")
+#> "4959e4b9a1812e511570eee14fe65b90098a0db6"
+```
+
+### `canonzip.zip(output_path, target, *, exclude, gitignore, follow_symlinks) -> None`
+
+Create a canonical zip archive of a directory.
+
+```python
+canonzip.zip("path/to/output.zip", "path/to/target")
+```
+
+### Shared options
+
+Both functions accept:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `exclude` | `list[str] \| None` | `None` | Glob patterns to exclude |
+| `gitignore` | `bool` | `False` | Exclude files based on `.gitignore` rules from the target's git repository |
+| `follow_symlinks` | `bool` | `False` | Follow symbolic links; if `False`, symlinks are ignored |
+
+If you specify both `exclude` and `gitignore`, files will be excluded as long
+as they match at least one rule (logical or).
+
+NOTE: exclude double-star globs (**) match one-or-more path segments;
+contrary to gitignore syntax where they match zero-or-more.
+
+### Exceptions
+
+canonzip will raise standard errors if it cannot read or write files,
+typically inheriting from `OSError`.
+
+Additionally there are special cases which raise errors which inherit
+from `canonzip.CanonzipError`:
+
+| Exception | Raised when |
+|---|---|
+| `OutputPathError` | `output_path` is inside `target` |
+| `GitRepositoryError` | `gitignore=True` but target is not in a git repo |
+| `BrokenSymlinkError` | A broken symlink is encountered with `follow_symlinks=True` |
+| `SymlinkCycleError` | A symlink cycle is detected with `follow_symlinks=True` |
+
+### Advanced: build manifests explicitly
+
+If you need direct access to the list of files that *would* be included in the
+canonical hash or zip, you can use `build_manifest` to read the target
+directory and return a `Manifest` object containing the list of files.
+To save yourself from having to generate the manifest twice, you can then pass
+it directly to `hash_from_manifest` or `zip_from_manifest` to complete the
+operation.
+
+```python
+from canonzip import build_manifest, hash_from_manifest, zip_from_manifest
+
+manifest = build_manifest("path/to/target", exclude=[".venv"])
+
+# Do something interesting with the manifest...
+print(manifest.target.as_posix())
+
+for entry in manifest.entries:
+    print(entry.path.as_posix())
+
+# Then compute the hash or zip
+digest = hash_from_manifest(manifest)
+zip_from_manifest("path/to/output.zip", manifest)
+```

canonzip-1.0.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "canonzip"
+version = "1.0.0"
+requires-python = ">=3.11"
+
+authors = [{ name = "Tyler Coles", email = "tylercoles@javadocmd.com" }]
+description = "Produce canonical zips and hashes."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "pygit2==1.19.1",
+    "typer==0.24.1",
+]
+
+[project.urls]
+Repository = "https://github.com/JavadocMD/canonzip.git"
+
+[project.scripts]
+canonzip = "canonzip.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit==4.5.1",
+    "pytest==9.0.2",
+    "ruff==0.15.7",
+]
+
+[tool.ruff]
+extend-exclude = ["examples"]
+
+[tool.ruff.lint]
+preview = true
+select = ["ALL"]
+
+# Ruff ignores:
+# - CPY: no need for copyright notice at the top of every file
+# - COM812: Ruff recommends disabling this when using formatter
+ignore = ["CPY", "COM812"]
+
+[tool.ruff.lint.extend-per-file-ignores]
+# - S101: we are allowed to use `assert` in pytest
+# - D103: no docstrings required
+"tests/**/*.py" = ["S101", "D103"]
+
+[tool.ruff.lint.flake8-builtins]
+ignorelist = ["hash", "zip"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+preview = true

canonzip-1.0.0/src/canonzip/__init__.py

@@ -0,0 +1,31 @@
+"""canonzip is a library for producing canonical zips and hashes."""
+
+from importlib.metadata import version
+
+from canonzip.exceptions import (
+    BrokenSymlinkError,
+    CanonzipError,
+    GitRepositoryError,
+    OutputPathError,
+    SymlinkCycleError,
+)
+from canonzip.hashing import hash, hash_from_manifest
+from canonzip.manifest import FileEntry, Manifest, build_manifest
+from canonzip.zipping import zip, zip_from_manifest
+
+__all__ = [
+    "BrokenSymlinkError",
+    "CanonzipError",
+    "FileEntry",
+    "GitRepositoryError",
+    "Manifest",
+    "OutputPathError",
+    "SymlinkCycleError",
+    "build_manifest",
+    "hash",
+    "hash_from_manifest",
+    "zip",
+    "zip_from_manifest",
+]
+
+__version__: str = version("canonzip")

canonzip-1.0.0/src/canonzip/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running canonzip as `python -m canonzip`."""
+
+from canonzip.cli import app
+
+app()

canonzip-1.0.0/src/canonzip/cli.py

@@ -0,0 +1,111 @@
+"""Command-line interface for canonzip."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from canonzip.exceptions import CanonzipError
+from canonzip.hashing import hash_from_manifest
+from canonzip.manifest import build_manifest
+from canonzip.zipping import zip_from_manifest
+
+app = typer.Typer(no_args_is_help=True, help="Produce canonical zips and hashes.")
+
+ExcludeOption = Annotated[
+    list[str] | None,
+    typer.Option("--exclude", "-e", help="Glob pattern to exclude (repeatable)."),
+]
+GitignoreOption = Annotated[
+    bool,
+    typer.Option("--gitignore", help="Exclude files matching .gitignore patterns."),
+]
+FollowSymlinksOption = Annotated[
+    bool,
+    typer.Option("--follow-symlinks", help="Follow symbolic links."),
+]
+VerboseOption = Annotated[
+    bool,
+    typer.Option("--verbose", "-v", help="Print included file paths to stderr."),
+]
+JsonOption = Annotated[
+    bool,
+    typer.Option("--json", help="Output result as JSON."),
+]
+TargetArgument = Annotated[
+    Path,
+    typer.Argument(
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+        help="Target directory.",
+    ),
+]
+OutputArgument = Annotated[
+    Path,
+    typer.Argument(dir_okay=False, help="Output zip file path."),
+]
+
+
+@app.command("hash")
+def hash_command(  # noqa: PLR0913
+    target: TargetArgument,
+    *,
+    exclude: ExcludeOption = None,
+    gitignore: GitignoreOption = False,
+    follow_symlinks: FollowSymlinksOption = False,
+    verbose: VerboseOption = False,
+    output_json: JsonOption = False,
+) -> None:
+    """Compute a canonical hash of a directory."""  # noqa: DOC501
+    try:
+        manifest = build_manifest(
+            target,
+            exclude=exclude,
+            gitignore=gitignore,
+            follow_symlinks=follow_symlinks,
+        )
+        if verbose:
+            for path in manifest.relative_paths:
+                typer.echo(path, err=True)
+        digest = hash_from_manifest(manifest)
+        output = json.dumps({"hash": digest}) if output_json else digest
+        typer.echo(output)
+    except CanonzipError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from None
+
+
+@app.command("zip")
+def zip_command(  # noqa: PLR0913
+    output_path: OutputArgument,
+    target: TargetArgument,
+    *,
+    exclude: ExcludeOption = None,
+    gitignore: GitignoreOption = False,
+    follow_symlinks: FollowSymlinksOption = False,
+    verbose: VerboseOption = False,
+    output_json: JsonOption = False,
+) -> None:
+    """Create a canonical zip archive of a directory."""  # noqa: DOC501
+    try:
+        manifest = build_manifest(
+            target,
+            exclude=exclude,
+            gitignore=gitignore,
+            follow_symlinks=follow_symlinks,
+        )
+        if verbose:
+            for path in manifest.relative_paths:
+                typer.echo(path, err=True)
+        zip_from_manifest(output_path, manifest)
+        if output_json:
+            output = json.dumps({"hash": hash_from_manifest(manifest)})
+            typer.echo(output)
+    except CanonzipError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from None

canonzip-1.0.0/src/canonzip/exceptions.py

@@ -0,0 +1,73 @@
+"""Custom exception types for canonzip."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = [
+    "BrokenSymlinkError",
+    "CanonzipError",
+    "GitRepositoryError",
+    "OutputPathError",
+    "SymlinkCycleError",
+]
+
+
+class CanonzipError(Exception):
+    """Base exception for all canonzip errors."""
+
+
+class SymlinkCycleError(CanonzipError):
+    """A symlink cycle was detected during directory traversal."""
+
+    path: Path
+    """The path where the cycle was detected."""
+
+    def __init__(self, path: Path) -> None:
+        """Initialize with the path where the cycle was detected."""
+        super().__init__(f"Symlink cycle detected at {path}")
+        self.path = path
+
+
+class BrokenSymlinkError(CanonzipError):
+    """A broken symlink was found during directory traversal."""
+
+    path: Path
+    """The path of the broken symlink."""
+
+    def __init__(self, path: Path) -> None:
+        """Initialize with the path of the broken symlink."""
+        super().__init__(f"Broken symlink found at {path}")
+        self.path = path
+
+
+class GitRepositoryError(CanonzipError):
+    """The target is not in a valid (non-bare) git repository."""
+
+    path: Path
+    """The path that is not in a valid git repository."""
+
+    def __init__(self, path: Path) -> None:
+        """Initialize with the path that is not in a valid git repository."""
+        super().__init__(f"Not a valid (non-bare) git repository: {path}")
+        self.path = path
+
+
+class OutputPathError(CanonzipError):
+    """The output path is inside the target directory."""
+
+    output_path: Path
+    """The (invalid) output path attempted."""
+    target: Path
+    """The target directory that contains the output path."""
+
+    def __init__(self, output_path: Path, target: Path) -> None:
+        """Initialize with the output path and target directory."""
+        super().__init__(
+            f"Output path ({output_path}) cannot be inside target directory ({target})",
+        )
+        self.output_path = output_path
+        self.target = target

canonzip-1.0.0/src/canonzip/hashing.py

@@ -0,0 +1,92 @@
+"""Implements canonical hashing of directories."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from canonzip.manifest import build_manifest
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from os import PathLike
+
+    from canonzip.manifest import Manifest
+
+__all__ = ["hash", "hash_from_manifest"]
+
+CHUNK_SIZE = 1024 * 1024
+"""The chunk size to use when reading files for hashing, in bytes.
+
+1 MiB is a good balance between performance and memory usage.
+"""
+
+
+def hash(
+    target: str | PathLike[str],
+    *,
+    exclude: Sequence[str] | None = None,
+    gitignore: bool = False,
+    follow_symlinks: bool = False,
+) -> str:
+    """Compute a canonical hash of the directory at the given target path.
+
+    This hash should be stable across different platforms and runs, as long as the
+    directory contents and structure remain the same.
+
+    Args:
+        target: The target path to hash.
+        exclude: Optional sequence of glob patterns to exclude from the hash.
+            Uses pathlib.Path.match() syntax, so "**" globs are not supported.
+        gitignore: If True, exclude files matching .gitignore patterns.
+            If True, the target directory must be in a valid git repository.
+        follow_symlinks: If True, follow symbolic links; if False, ignore them.
+
+    Returns:
+        A stable SHA-1 hash representing the directory files' paths and contents.
+    """
+    manifest = build_manifest(
+        Path(target).resolve(),
+        exclude=exclude,
+        gitignore=gitignore,
+        follow_symlinks=follow_symlinks,
+    )
+    return hash_from_manifest(manifest)
+
+
+def hash_from_manifest(manifest: Manifest) -> str:
+    """Compute a canonical hash from a pre-built manifest.
+
+    This is useful when you want to inspect the manifest (e.g. to print
+    included paths) before hashing, without walking the directory twice.
+
+    Args:
+        manifest: The pre-built manifest to hash.
+
+    Returns:
+        A stable SHA-1 hash representing the directory files' paths and contents.
+    """
+    digest = hashlib.sha1()  # noqa: S324 (SHA-1 is not used for security here)
+    for entry in manifest.entries:
+        # For each file, digest:
+        # - the relative path prefixed by its size, and
+        # - the file content prefixed by its size.
+        # The sizes act as separators to mitigate hash collisions.
+        # For example, without the size prefixes, the following two file sets would
+        # produce the same hash:
+        # - foobar (content: "baz")
+        # - foo (content: "barbaz")
+        rel_path = entry.path.relative_to(manifest.target)
+        rel_path_bytes = rel_path.as_posix().encode("utf-8")
+        digest.update(len(rel_path_bytes).to_bytes(8))
+        digest.update(rel_path_bytes)
+        digest.update(entry.size.to_bytes(8))
+        with entry.path.open("rb") as handle:
+            while True:
+                chunk = handle.read(CHUNK_SIZE)
+                if not chunk:
+                    break
+                digest.update(chunk)
+
+    return digest.hexdigest()

canonzip-1.0.0/src/canonzip/manifest.py

@@ -0,0 +1,258 @@
+"""Implements canonical ordering of files in directories.
+
+Hashing and zipping use this manifest to ensure consistent behavior.
+"""
+
+from __future__ import annotations
+
+import stat
+from collections.abc import Callable, Generator, Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+import pygit2
+
+from canonzip.exceptions import (
+    BrokenSymlinkError,
+    GitRepositoryError,
+    SymlinkCycleError,
+)
+
+__all__ = ["FileEntry", "Manifest", "build_manifest"]
+
+
+@dataclass(frozen=True, slots=True)
+class FileEntry:
+    """Represents a file or directory entry in the manifest."""
+
+    path: Path
+    """The absolute path to the file or directory."""
+    path_relative: Path
+    """The path relative to the manifest target directory."""
+    mode: int
+    """The file mode (permissions and type) as returned by os.stat()."""
+    is_dir: bool
+    """Indicates if the entry is a directory."""
+    is_file: bool
+    """Indicates if the entry is a file."""
+    is_symlink: bool
+    """Indicates if the entry is a symbolic link."""
+    is_broken: bool
+    """Indicates if the entry is a broken symbolic link."""
+    size: int
+    """The size of the file in bytes."""
+
+    @staticmethod
+    def from_path(path: Path, path_relative: Path) -> FileEntry:
+        """Create a FileEntry from a given path, gathering necessary metadata.
+
+        Args:
+            path: The absolute path to a file or directory.
+            path_relative: The path relative to the manifest target directory.
+
+        Returns:
+            The FileEntry object.
+        """
+        # Take care to handle broken symlinks correctly.
+        # First stat without following symlinks to determine if it's a symlink.
+        # If so, stat again with following enabled to determine if it's broken.
+        stat_nofollow = path.stat(follow_symlinks=False)
+        is_symlink = stat.S_ISLNK(stat_nofollow.st_mode)
+        if not is_symlink:
+            stat_result = stat_nofollow
+            is_broken = False
+        else:
+            try:
+                stat_result = path.stat(follow_symlinks=True)
+                is_broken = False
+            except OSError:
+                stat_result = stat_nofollow
+                is_broken = True
+        mode = stat_result.st_mode
+        return FileEntry(
+            path=path,
+            path_relative=path_relative,
+            mode=mode,
+            is_dir=stat.S_ISDIR(mode),
+            is_file=stat.S_ISREG(mode),
+            is_symlink=is_symlink,
+            is_broken=is_broken,
+            size=stat_result.st_size,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Manifest:
+    """A canonical ordered collection of files for a given target directory."""
+
+    target: Path
+    """The resolved path of the target directory."""
+    entries: tuple[FileEntry, ...]
+    """The canonical ordered file entries."""
+
+    @property
+    def relative_paths(self) -> Iterable[str]:
+        """The relative paths of the manifest entries (posix-formatted strings)."""
+        return (entry.path_relative.as_posix() for entry in self.entries)
+
+
+ExcludePredicate = Callable[[FileEntry], bool]
+"""A predicate function: should a FileEntry be excluded from the manifest?"""
+
+
+def exclude_none(_file_entry: FileEntry) -> bool:
+    """The default exclusion predicate: exclude nothing."""  # noqa: DOC201
+    return False
+
+
+def exclude_symlinks(prev: ExcludePredicate) -> ExcludePredicate:
+    """Exclude symbolic links."""  # noqa: DOC201
+
+    def exclude(file_entry: FileEntry) -> bool:
+        return file_entry.is_symlink or prev(file_entry)
+
+    return exclude
+
+
+def exclude_by_patterns(
+    patterns: Sequence[str],
+    prev: ExcludePredicate,
+) -> ExcludePredicate:
+    """Exclude files matching any of the given glob patterns."""  # noqa: DOC201
+    patterns_list = list(patterns)
+
+    def exclude(file_entry: FileEntry) -> bool:
+        path = PurePosixPath(file_entry.path_relative)
+        match = any(
+            any(candidate.match(p) for p in patterns_list)  # check each pattern
+            for candidate in [path, *path.parents[:-1]]  # check each path and parents
+        )
+        return match or prev(file_entry)
+
+    return exclude
+
+
+def exclude_gitignored(path: Path, prev: ExcludePredicate) -> ExcludePredicate:
+    """Exclude files using the .gitignore of the repository containing the path."""  # noqa: DOC201, DOC501
+    try:
+        repository = pygit2.Repository(path)
+    except pygit2.GitError:
+        raise GitRepositoryError(path) from None
+    if repository.is_bare:
+        raise GitRepositoryError(path) from None
+    workdir = Path(repository.workdir).resolve()
+
+    def is_ignored(file_entry: FileEntry) -> bool:
+        rel_path = file_entry.path.relative_to(workdir).as_posix()
+        if file_entry.is_dir:
+            rel_path = f"{rel_path}/"
+        return repository.path_is_ignored(rel_path)
+
+    def exclude(file_entry: FileEntry) -> bool:
+        return is_ignored(file_entry) or prev(file_entry)
+
+    return exclude
+
+
+def build_manifest(
+    target: Path,
+    *,
+    exclude: Sequence[str] | None = None,
+    gitignore: bool = False,
+    follow_symlinks: bool = False,
+) -> Manifest:
+    """Build the canonical manifest for the given target directory.
+
+    Args:
+        target: The target directory to build the manifest for.
+        exclude: Optional sequence of glob patterns to exclude from themanifest.
+            Uses pathlib.Path.match() syntax, so "**" globs are not supported.
+        gitignore: If True, exclude files matching .gitignore patterns.
+            If True, the target directory must be in a valid git repository.
+        follow_symlinks: If True, follow symbolic links; if False, ignore them.
+
+    Returns:
+        A Manifest containing the resolved target path and its canonical file entries.
+
+    Raises:
+        FileNotFoundError: If the target directory does not exist.
+        NotADirectoryError: If the target path is not a directory.
+        SymlinkCycleError: If a symlink cycle is detected.
+        GitRepositoryError: If gitignore=True but the target is not in a valid
+            git repository.
+        BrokenSymlinkError: If a broken symlink is found when follow_symlinks=True.
+    """  # noqa: DOC502
+    if not target.exists():
+        raise FileNotFoundError(target)
+    if not target.is_dir():
+        raise NotADirectoryError(target)
+    target = target.resolve()
+
+    # Build up the exclude predicate based on the options.
+    # Chained function application implements a logical or of the selected conditions,
+    # so a file is excluded if it matches any of the criteria.
+    exclude_fn = exclude_none
+    if not follow_symlinks:
+        exclude_fn = exclude_symlinks(exclude_fn)
+    if exclude:
+        exclude_fn = exclude_by_patterns(exclude, exclude_fn)
+    if gitignore:
+        exclude_fn = exclude_gitignored(target, exclude_fn)
+
+    walk = walk_directory(
+        target,
+        target,
+        walked_dirs=set(),
+        exclude=exclude_fn,
+        follow_symlinks=follow_symlinks,
+    )
+
+    return Manifest(target=target, entries=tuple(walk))
+
+
+def walk_directory(
+    root: Path,
+    path: Path,
+    *,
+    walked_dirs: set[Path],
+    exclude: ExcludePredicate,
+    follow_symlinks: bool,
+) -> Generator[FileEntry, None, None]:
+    """Recursively yield FileEntry objects for non-excluded files in a directory.
+
+    Args:
+        root: The root directory for relative path calculations.
+        path: The directory to walk.
+        walked_dirs: A set of directories that have already been walked.
+        exclude: A predicate that returns True for files that should be excluded.
+        follow_symlinks: If True, follow symbolic links; if False, ignore them.
+
+    Yields:
+        FileEntry objects for files that are not excluded.
+
+    Raises:
+        SymlinkCycleError: If a symlink cycle is detected.
+        BrokenSymlinkError: If a broken symlink is found when follow_symlinks=True.
+    """
+    if any(path.samefile(x) for x in walked_dirs):
+        raise SymlinkCycleError(path)
+    walked_dirs.add(path)
+
+    # Sorting entries by name ensures a stable order regardless of filesystem behavior.
+    for entry in sorted(path.iterdir(), key=lambda p: p.name):
+        file_entry = FileEntry.from_path(entry, entry.relative_to(root))
+        if follow_symlinks and file_entry.is_broken:
+            raise BrokenSymlinkError(entry)
+        if exclude(file_entry):
+            continue
+
+        if file_entry.is_file:
+            yield file_entry
+        elif file_entry.is_dir:
+            yield from walk_directory(
+                root,
+                entry,
+                walked_dirs=walked_dirs,
+                exclude=exclude,
+                follow_symlinks=follow_symlinks,
+            )

canonzip-1.0.0/src/canonzip/zipping.py

@@ -0,0 +1,112 @@
+"""Implements canonical zipping of directories."""
+
+from __future__ import annotations
+
+import shutil
+import stat
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from canonzip.exceptions import OutputPathError
+from canonzip.manifest import build_manifest
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from os import PathLike
+
+    from canonzip.manifest import Manifest
+
+__all__ = ["zip", "zip_from_manifest"]
+
+CHUNK_SIZE = 1024 * 1024
+"""The chunk size to use when copying files into the zip, in bytes.
+
+1 MiB is a good balance between performance and memory usage.
+"""
+
+
+def zip(
+    output_path: str | PathLike[str],
+    target: str | PathLike[str],
+    *,
+    exclude: Sequence[str] | None = None,
+    gitignore: bool = False,
+    follow_symlinks: bool = False,
+) -> None:
+    """Create a canonical zip file of the directory at the given target path.
+
+    Args:
+        output_path: The path to write the zip file to.
+            Must not be inside the target directory.
+        target: The target directory to zip.
+        exclude: Optional sequence of glob patterns to exclude from the zip.
+            Uses pathlib.Path.match() syntax, so "**" globs are not supported.
+        gitignore: If True, exclude files matching .gitignore patterns.
+            If True, the target directory must be in a valid git repository.
+        follow_symlinks: If True, follow symbolic links; if False, ignore them.
+    """
+    manifest = build_manifest(
+        Path(target).resolve(),
+        exclude=exclude,
+        gitignore=gitignore,
+        follow_symlinks=follow_symlinks,
+    )
+    zip_from_manifest(output_path, manifest)
+
+
+def zip_from_manifest(output_path: str | PathLike[str], manifest: Manifest) -> None:
+    """Create a canonical zip file from a pre-built manifest.
+
+    This is useful when you want to inspect the manifest (e.g. to print
+    included paths) before zipping, without walking the directory twice.
+
+    Args:
+        output_path: The path to write the zip file to.
+            Must not be inside the target directory.
+        manifest: The pre-built manifest whose entries to include.
+
+    Raises:
+        OutputPathError: If the output path is inside the target directory.
+    """
+    destination = Path(output_path).resolve()
+    target_path = manifest.target
+
+    # Ensure the output path is not inside the target directory;
+    # I'm not sure this would cause problems, but it seems better to rule this case out.
+    try:
+        destination.relative_to(target_path)
+    except ValueError:
+        pass
+    else:
+        raise OutputPathError(destination, target_path)
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    fixed_timestamp = (1980, 1, 1, 0, 0, 0)
+    compression = zipfile.ZIP_DEFLATED
+    with zipfile.ZipFile(
+        destination,
+        mode="w",
+        compression=compression,
+        compresslevel=9,
+    ) as zip:
+        for entry in manifest.entries:
+            rel_path = entry.path.relative_to(target_path)
+            # This seems like a decent reference on zip file format:
+            # https://pkwaredownloads.blob.core.windows.net/pkware-general/Documentation/APPNOTE-6.3.9.TXT
+            # create_system=3 indicates file attributes are UNIX compatible
+            # attr is shifted because left two bytes are for UNIX, right two for Windows
+            info = zipfile.ZipInfo(rel_path.as_posix(), fixed_timestamp)
+            info.compress_type = compression
+            info.create_system = 3
+            info.external_attr = normalized_mode(entry.mode) << 16
+            with entry.path.open("rb") as src, zip.open(info, "w") as dst:
+                shutil.copyfileobj(src, dst, length=CHUNK_SIZE)
+
+
+def normalized_mode(mode: int) -> int:
+    """Normalize the mode of zipped files (for cross-platform stability)."""  # noqa: DOC201
+    if mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+        return 0o755
+    return 0o644