zippathlib 0.6.0__py3-none-any.whl

zippathlib/__init__.py

@@ -0,0 +1,11 @@
+from .zip_pathlib import ZipPath, ZipPathDuplicateFileWarning
+
+import importlib.metadata
+__version__ = importlib.metadata.version(__package__)
+
+
+__all__ = [
+    '__version__',
+    'ZipPath',
+    'ZipPathDuplicateFileWarning',
+]

zippathlib/__main__.py

@@ -0,0 +1,249 @@
+import argparse
+import sys
+import zipfile
+from pathlib import Path
+
+from rich import print as rprint
+from rich.tree import Tree as RichTree
+
+from zippathlib import ZipPath
+
+DEFAULT_SIZE_LIMIT = 2 * 1024**3  # 2GB
+
+def get_version() -> str:
+    from . import __version__
+    return __version__
+
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.prog = 'zippathlib'
+    parser.add_argument("zip_file", help="Zip file to explore")
+    parser.add_argument("path_within_zip", nargs='?', default="",
+            help="Path within the zip file (optional)")
+
+    # options
+    parser.add_argument(
+        "-V", "--version",
+        action="version",
+        version=f"%(prog)s {get_version()}"
+    )
+    parser.add_argument("--tree" , action="store_true", help="list all files in a tree-like format")
+    parser.add_argument(
+        "-x", "--extract",
+        nargs="?", const=".", default=None,
+        dest="outputdir",
+        help="extract files from zip file to a directory or '-' for stdout, default is '.'"
+    )
+    parser.add_argument(
+        "--limit", default=2*1024**3,
+        type = _h2i,
+        help="guard value against malicious ZIP files that uncompress"
+             " to excessive sizes; specify as an integer or float value"
+             " optionally followed by a multiplier suffix K,M,G,T,P,E, or Z;"
+             f" default is {_i2h(DEFAULT_SIZE_LIMIT).rstrip('B')}"
+    )
+    parser.add_argument(
+        "--check",
+        choices=["duplicates", "limit", "d", "l"],
+        help="check ZIP file for duplicates, or for files larger than LIMIT"
+    )
+    parser.add_argument(
+        "--purge",
+        action="store_true",
+        help="purge ZIP file of duplicate file entries",
+    )
+    parser.add_argument(
+        "--new",
+        dest="create_new_zip",
+        action="store_true",
+        help="create new ZIP file"
+    )
+
+    return parser
+
+def _i2h(n: int) -> str:
+    if n < 1024 * 1024:
+        return f"{n:,} bytes"
+    n /= 1024
+    for prefix in "MGTPEZ":
+        n /= 1024
+        if n < 1024:
+            break
+    return f"{n:,.2f}{prefix}B"
+
+def _h2i(s: str) -> int:
+    if not s:
+        return 0
+
+    s = s.rstrip("B").replace(",", "").removesuffix(" bytes")
+
+    if s.isdigit():
+        return int(s)
+
+    n = 1
+    for prefix in "KMGTPEZ":
+        n *= 1024
+        if prefix == s[-1]:
+            break
+    return int(n * float(s[:-1]))
+
+def _extract_file(zippath:ZipPath, outputdir: Path | str | None = None):
+    """Extract a file from the zip archive."""
+    if not zippath.exists():
+        raise FileNotFoundError(f"File {str(zippath)!r} not found in zip archive.")
+
+    data = zippath.read_bytes()
+    path, _, name = zippath._path.rpartition("/")
+    (outputdir / path).mkdir(parents=True, exist_ok=True)
+    outputpath = outputdir / path / name
+    outputpath.write_bytes(data)
+
+
+def _construct_tree(zippath:ZipPath) -> RichTree:
+    """Construct a rich Tree for the given zip path."""
+
+    ret = RichTree("")
+    parent_stack: list[tuple[RichTree, int]] = [(ret, zippath._depth - 1)]
+
+    for node in zippath.riterdir():
+        if not node.name:
+            continue
+
+        # unwind stack until depth < node's depth (which will be the new node's parent)
+        while node._depth <= parent_stack[-1][-1]:
+            parent_stack.pop()
+
+        parent = parent_stack[-1][0]
+        node_branch = parent.add(node.name)
+
+        parent_stack.append((node_branch, node._depth))
+
+    return ret
+
+
+def main() -> int:
+    args =  make_parser().parse_args()
+
+    # unpack positional args into locals
+    zip_filename = args.zip_file
+    path_within_zip = args.path_within_zip
+    NL = "\n"
+
+    try:
+        # See if zip_filename is actually a ZIP file - if not, this
+        # will raise an exception and we'll either create a new
+        # archive or just reraise
+        try:
+            zipfile.ZipFile(zip_filename)
+        except FileNotFoundError:
+            if args.create_new_zip:
+                zip_file_path = Path(zip_filename)
+                ZipPath.create(zip_file_path)
+            else:
+                raise
+
+        zip_path: ZipPath = ZipPath(zip_filename)
+
+        if "*" in path_within_zip:
+            # Handle * wildcard for path_within_zip
+            files = [item for item in zip_path.glob(path_within_zip)]
+            print("Files:", *map(str, files), sep=NL)
+        else:
+
+            if path_within_zip:
+                zip_path = zip_path / path_within_zip
+
+            if not zip_path.exists():
+                raise ValueError(f"{path_within_zip!r} does not exist in {zip_filename}")
+
+            if args.tree:
+                # print pretty tree of ZIP contents
+                rprint(_construct_tree(zip_path))
+
+            elif args.check:
+                if args.check[:1] == "d":
+                    duplicates = zip_path.scan_for_duplicates()
+                    if duplicates:
+                        print("Duplicate files found")
+                        for fname, count in duplicates:
+                            print(f"{fname} ({count})")
+                        return 1
+
+                elif  args.check[:1] == "l":
+                    large_files = zip_path.scan_for_large_files(args.limit)
+                    if large_files:
+                        print("Large files found")
+                        for fname, size in large_files:
+                            print(f"{fname} - {_i2h(size)}")
+                        return 1
+
+            elif args.purge:
+                # guard against files > args.limit in size
+                duplicates:  list[tuple[str, int]] = zip_path.scan_for_duplicates()
+                if duplicates:
+                    deduped: list[zipfile.ZipInfo] = zip_path.get_deduplicated_entries()
+                    if any(entry.file_size > args.limit for entry in deduped):
+                        raise ValueError(f"Files larger than {_i2h(args.limit)} were found.")
+
+                    zip_path.purge_duplicates(replace=True)
+                    print("Rebuilt ZIP file with duplicate entries removed")
+                else:
+                    print("No duplicate file entries found")
+
+            elif args.outputdir:
+                # extracting one or more files/directories
+                if args.outputdir == "-":
+                    if zip_path.is_file():
+                        # dump to stdout
+                        print(zip_path.read_text())
+                    else:
+                        raise ValueError("Cannot dump directory to stdout")
+                else:
+                    # extract files to given directory
+                    zip_file_path = Path(zip_filename)
+                    outputdir = Path(args.outputdir) / zip_file_path.stem
+                    total_size = zip_path.total_size()
+                    if total_size > args.limit:
+                        raise ValueError(f"Total file size {_i2h(total_size)} exceeds extract limit {_i2h(args.limit)}")
+
+                    for file in zip_path.riterdir():
+                        if file.is_file():
+                            print(f"extracting {file}")
+                            _extract_file(file, outputdir)
+                        else:
+                            # make directory, in case it is an empty dir
+                            (outputdir / file._path).mkdir(parents=True, exist_ok=True)
+
+            elif args.create_new_zip:
+                print(f"ZIP archive {zip_filename!r} exists")
+                return 1
+
+            else:
+                # just browsing
+                if zip_path.is_file():
+                    print(f"File: {zip_path} ({_i2h(zip_path.size())})")
+                    content = zip_path.read_text()
+                    print(
+                        f"Content:{NL}{content[:100]}"
+                        f"{'...' if  len(content) > 100 else ''}"
+                    )
+
+                elif zip_path.is_dir():
+                    print(f"Directory: {zip_path} (total size {_i2h(zip_path.total_size())})")
+                    print("Contents:")
+                    for item in zip_path.iterdir():
+                        type_indicator = "FD"[item.is_dir()]
+                        print(f"  [{type_indicator}] {item.name} ({_i2h(item.size()) if item.is_file() else _i2h(item.total_size())})")
+                else:
+                    print(f"Path does not exist: {zip_path}")
+
+    except Exception as e:
+        print(f"Error: {type(e).__name__}: {e}")
+        # raise
+        return 1
+
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

zippathlib/zip_pathlib.py

@@ -0,0 +1,769 @@
+#!/usr/bin/env python
+"""
+ZipPath - A pathlib.Path subclass for accessing files in ZIP archives
+
+This module provides a standalone utility class for working with files inside
+ZIP archives using a familiar pathlib-like interface.
+"""
+from __future__ import annotations
+
+import contextlib
+import fnmatch
+import functools
+import io
+import os
+import warnings
+from pathlib import Path, PurePosixPath, PurePath
+import stat
+from typing import BinaryIO, TextIO, Any, NamedTuple
+
+from collections.abc import Iterator
+import zipfile
+
+
+class ZipPathDuplicateFileWarning(UserWarning):
+    """
+    Writing to an existing file entry in a ZIP archive does not overwrite
+    the previous contents, but creates a duplicate entry for that file.
+    """
+    def __init__(self, file_path: str):
+        message = f"File overwrite creates duplicate ZIP entry: {file_path!r}"
+        super().__init__(message)
+
+
+class _ZipWriteFile:
+    """
+    A file-like object for writing to a file within a ZIP archive.
+
+    This class buffers written data and updates the ZIP file when closed.
+    """
+
+    def __init__(self, zip_path: ZipPath, mode: str, encoding: str | None = None):
+        """
+        Initialize a _ZipWriteFile object.
+
+        Args:
+            zip_path: The ZipPath object representing the file to write
+            mode: The file mode ('w', 'wb', 'a', 'ab')
+            encoding: Text encoding for text modes
+        """
+        self.zip_path = zip_path
+        self.mode = mode
+        self.encoding = encoding
+        self.closed = False
+
+        # Create the appropriate buffer based on mode
+        if 'b' in mode:  # Binary mode
+            self.buffer = io.BytesIO()
+        else:  # Text mode
+            self.buffer = io.StringIO()
+
+        # Check if we're appending and the file exists
+        if 'a' in mode and zip_path.is_file():
+            # Read existing content
+            if 'b' in mode:
+                existing_data = zip_path.read_bytes()
+                self.buffer.write(existing_data)
+            else:
+                existing_text = zip_path.read_text(encoding=encoding or 'utf-8')
+                self.buffer.write(existing_text)
+
+    def write(self, data: str | bytes) -> int:
+        """
+        Write data to the buffer.
+
+        Args:
+            data: The data to write
+
+        Returns:
+            Number of characters/bytes written
+
+        Raises:
+            ValueError: If the file is closed
+        """
+        if self.closed:
+            raise ValueError("I/O operation on closed file")
+        return self.buffer.write(data)
+
+    def close(self) -> None:
+        """
+        Close the file and update the ZIP archive.
+        """
+        if self.closed:
+            return
+
+        self.buffer.seek(0)
+
+        # Get the data from the buffer
+        if 'b' in self.mode:  # Binary mode
+            data = self.buffer.read()
+        else:  # Text mode
+            text = self.buffer.read()
+            data = text.encode(self.encoding or 'utf-8')
+
+        # Update the ZIP file
+        normalized_path = self.zip_path._normalize_path(self.zip_path._path)
+
+        # Open the ZIP file in append mode
+        with zipfile.ZipFile(
+            self.zip_path.zip_filename,
+            mode='a',
+            compression=zipfile.ZIP_DEFLATED,
+            compresslevel=9,
+        ) as zf:
+            zf.writestr(normalized_path, data)
+
+        self.closed = True
+        self.buffer.close()
+
+    def __enter__(self) -> _ZipWriteFile:
+        """Context manager enter method."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit method."""
+        self.close()
+
+
+class _ZipStat(NamedTuple):
+    st_mode: int = 0
+    st_ino: int = 0
+    st_dev: int = 0
+    st_nlink: int = 1
+    st_uid: int = 65534  # nobody
+    st_gid: int = 65534  # nogroup
+    st_size: int = 0
+    st_atime: int = 0
+    st_mtime: int = 0
+    st_ctime: int = 0
+
+
+class ZipPath(PurePosixPath):
+    """
+    A pathlib.Path-like interface to files within a ZIP archive.
+
+    This class allows you to navigate and access files within a ZIP archive
+    using a familiar pathlib-like interface. It handles the details of opening
+    and closing the ZIP file as needed.
+
+    Examples:
+        # Open a file from a ZIP archive
+        zip_path = ZipPath('archive.zip', 'path/to/file.txt')
+        with zip_path.open() as f:
+            content = f.read()
+
+        # List all files in a directory within the ZIP
+        zip_path = ZipPath('archive.zip', 'some/directory')
+        for file in zip_path.iterdir():
+            print(file)
+
+        # Check if a file exists in the ZIP
+        if ZipPath('archive.zip', 'path/to/file.txt').exists():
+            print("File exists!")
+    """
+
+    def __init__(self, zip_filename: str | PurePath, path: str = '', mode="r") -> None:
+        """
+        Initialize a ZipPath object.
+
+        Args:
+            zip_filename: Path to the ZIP file
+            path: Path within the ZIP file (default: root of the ZIP)
+        """
+        super().__init__(path)
+        self.zip_filename = Path(zip_filename)
+        self._path = path
+        self._mode = mode
+        self._zipfile_stat = os.stat(self.zip_filename)
+
+    @classmethod
+    def at_path(cls, source_path: Path | None, dest_path: Path = None) -> ZipPath:
+        """
+        ZIP archive creator, returning a ZipPath object for the newly-created ZIP archive
+        """
+        if dest_path is None:
+            dest = source_path.parent / f"{source_path.stem}.zip"
+        else:
+            dest = dest_path
+
+        if dest.exists():
+            return ZipPath(dest)
+        else:
+            # print(f"Creating {dest}")
+            with zipfile.ZipFile(
+                dest,
+                mode="w",
+                compression=zipfile.ZIP_DEFLATED,
+                compresslevel=9,
+            ) as new_zf:
+                if source_path is not None:
+                    for file in source_path.rglob("*"):
+                        if file.is_file():
+                            # print(f"adding {file}")
+                            new_zf.write(
+                                file,
+                                file.relative_to(source_path.parent),
+                            )
+            ret = ZipPath(dest)
+            return ret
+
+    @classmethod
+    def create(cls, new_zip_path: Path) -> ZipPath:
+        return cls.at_path(None, new_zip_path)
+
+    @property
+    def _depth(self):
+        """Internal property for recursion and tree formatting"""
+        return self._path.count("/")
+
+    def is_valid(self) -> bool:
+        """
+        Validation function to confirm that a ZipPath object is valid and the
+        zip file exists.
+        :return:
+        """
+        try:
+            self._get_zipfile()
+        except Exception:
+            return False
+        else:
+            return True
+
+    def __str__(self) -> str:
+        """Return a string representation of the path."""
+        return f"{self.zip_filename}::{self._path}"
+
+    def __repr__(self) -> str:
+        """Return a detailed string representation of the path."""
+        return f"ZipPath('{self.zip_filename}', '{self._path}')"
+
+    def _get_zipfile(self) -> zipfile.ZipFile:
+        """
+        Internal method to return the ZIP file that underlies the ZipPath object's file model.
+
+        Returns:
+            An open zipfile.ZipFile object
+
+        Raises:
+            FileNotFoundError: If the ZIP file doesn't exist
+            zipfile.BadZipFile: If the file is not a valid ZIP file
+        """
+        if not self.zip_filename.exists():
+            raise FileNotFoundError(f"ZIP file not found: '{self.zip_filename}'")
+        return zipfile.ZipFile(self.zip_filename, mode=self._mode)
+
+    def _normalize_path(self, path: str) -> str:
+        """
+        Normalize a path within the ZIP file.
+
+        Args:
+            path: Path to normalize
+
+        Returns:
+            Normalized path
+        """
+        # Remove leading slash if present
+        return path.removeprefix("/")
+
+    def joinpath(self, *paths: str) -> ZipPath:
+        """
+        Join this path with one or more path components.
+
+        Args:
+            *paths: Path components to join
+
+        Returns:
+            A new ZipPath object with the joined path
+        """
+        new_path = PurePosixPath(self._path).joinpath(*paths)
+        return ZipPath(self.zip_filename, str(new_path), mode=self._mode)
+
+    def __truediv__(self, key: str) -> ZipPath:
+        """
+        Join this path with another using the / operator.
+
+        Args:
+            key: Path component to join
+
+        Returns:
+            A new ZipPath object with the joined path
+        """
+        return self.joinpath(key)
+
+    def exists(self) -> bool:
+        """
+        Check if this path exists in the ZIP file.
+
+        Returns:
+            True if the path exists, False otherwise
+        """
+        if not self.zip_filename.exists():
+            return False
+
+        try:
+            with self._get_zipfile() as zf:
+                # For the root directory
+                if not self._path:
+                    return True
+
+                # For files
+                normalized_path = self._normalize_path(self._path)
+                if normalized_path in zf.namelist():
+                    return True
+
+                # For directories (check if any file starts with this path)
+                if not normalized_path.endswith('/'):
+                    normalized_path += '/'
+
+                for name in zf.namelist():
+                    if name.startswith(normalized_path):
+                        return True
+
+                return False
+        except zipfile.BadZipFile:
+            return False
+
+    def is_file(self) -> bool:
+        """
+        Check if this path is a file in the ZIP archive.
+
+        Returns:
+            True if the path is a file, False otherwise
+        """
+        if not self.zip_filename.exists():
+            return False
+
+        try:
+            with self._get_zipfile() as zf:
+                normalized_path = self._normalize_path(self._path)
+                return normalized_path in zf.namelist() and not normalized_path.endswith('/')
+        except zipfile.BadZipFile:
+            return False
+
+    def is_dir(self) -> bool:
+        """
+        Check if this path is a directory in the ZIP archive.
+
+        Returns:
+            True if the path is a directory, False otherwise
+        """
+        if not self.zip_filename.exists():
+            return False
+
+        if self.is_root():
+            return True
+
+        try:
+            with self._get_zipfile() as zf:
+                # Root directory
+                if not self._path:
+                    return True
+
+                normalized_path = self._normalize_path(self._path)
+
+                # Explicit directory entry
+                if normalized_path.endswith('/'):
+                    return normalized_path in zf.namelist()
+                else:
+                    dir_path = normalized_path + '/'
+                    if dir_path in zf.namelist():
+                        return True
+
+                # Implicit directory (contains files)
+                if any(name.startswith(dir_path) for name in zf.namelist()):
+                    return True
+
+                return False
+        except zipfile.BadZipFile:
+            return False
+
+    def is_root(self) -> bool:
+        """
+        Boolean function for determining if the ZipPath object is at the root of
+        the ZIP archive.
+        """
+        return self._path == ''
+
+    def iterdir(self) -> Iterator[ZipPath]:
+        """
+        Iterate over the files and directories in this directory.
+
+        Returns:
+            An iterator of ZipPath objects
+
+        Raises:
+            NotADirectoryError: If this path is not a directory
+        """
+        if not self.is_dir():
+            raise NotADirectoryError(f"Not a directory: {self}")
+
+        with self._get_zipfile() as zf:
+            prefix = self._normalize_path(self._path)
+            if prefix and not prefix.endswith('/'):
+                prefix += '/'
+
+            # Track directories we've seen to avoid duplicates
+            seen_dirs = set()
+
+            for name in zf.namelist():
+                if name.startswith(prefix):
+                    # Get the relative path from the current directory
+                    rel_path = name[len(prefix):]
+                    if not rel_path:
+                        continue
+
+                    # Get the first component of the relative path
+                    parts = rel_path.split('/', 1)
+                    first_part = parts[0]
+
+                    if len(parts) > 1:  # This is a subdirectory
+                        if first_part not in seen_dirs:
+                            seen_dirs.add(first_part)
+                            yield ZipPath(self.zip_filename, f"{prefix}{first_part}", mode=self._mode)
+                    else:  # This is a file
+                        yield ZipPath(self.zip_filename, f"{prefix}{first_part}", mode=self._mode)
+
+    def glob(self, pattern: str) -> Iterator[ZipPath]:
+        """
+        Iterate over paths matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern to match
+
+        Returns:
+            An iterator of ZipPath objects matching the pattern
+        """
+        with self._get_zipfile() as zf:
+            prefix = self._normalize_path(self._path)
+            if prefix and not prefix.endswith('/'):
+                prefix += '/'
+
+            if pattern.startswith("**/"):
+                list_src = zf.namelist()
+                pattern = pattern.removeprefix("**/")
+            else:
+                list_src = [str(p).partition("::")[-1] for p in self.iterdir()]
+
+            for name in list_src:
+                if name.startswith(prefix):
+                    # Get the relative path from the current directory
+                    rel_path = name[len(prefix):]
+                    if not rel_path:
+                        continue
+
+                    # Check if it matches the pattern
+                    if fnmatch.fnmatch(rel_path, pattern):
+                        yield ZipPath(self.zip_filename, f"{prefix}{rel_path}")
+
+    def riterdir(self) -> Iterator[ZipPath]:
+        """
+        Recursive iterator listing all files and directories in this directory and
+        its subdirectories (depth first).
+        """
+        to_visit: list[ZipPath] = [self]
+        while to_visit:
+            current = to_visit.pop()
+            yield current
+            if current.is_dir():
+                for entry in current.iterdir():
+                    to_visit.append(entry)
+
+    def rglob(self, pattern: str) -> Iterator[ZipPath]:
+        """
+        Recursive glob iterator listing all files and directories in this directory and its subdirectories
+        that match the given pattern.
+
+        Args:
+            pattern: Glob pattern to match
+
+        Returns:
+            An iterator of ZipPath objects matching the pattern
+        """
+        for path in self.riterdir():
+            if fnmatch.fnmatch(path.name, pattern):
+                yield path
+
+    def __iter__(self):
+        return (line for line in self.read_text().splitlines())
+
+    def open(self, mode: str = 'r', encoding: str | None = None) -> BinaryIO | TextIO:
+        """
+        Open the file pointed to by this path.
+
+        Args:
+            mode: Open mode ('r', 'rb', 'w', 'wb', etc.)
+            encoding: Text encoding (for text modes)
+
+        Returns:
+            A file-like object
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist in read mode
+            IsADirectoryError: If the path points to a directory
+        """
+        # Reading modes
+        if 'r' in mode and not any(c in mode for c in 'wa'):
+            if not self.is_file():
+                if self.is_dir():
+                    raise IsADirectoryError(f"Is a directory: {self}")
+                raise FileNotFoundError(f"File not found in ZIP: {self}")
+
+            with self._get_zipfile() as zf:
+                normalized_path = self._normalize_path(self._path)
+                file_data = zf.read(normalized_path)
+
+            if 'b' in mode:  # Binary mode
+                return io.BytesIO(file_data)
+            else:  # Text mode
+                encoding = encoding or 'utf-8'
+                return io.StringIO(file_data.decode(encoding))
+
+        # Writing modes
+        elif any(c in mode for c in 'wa'):
+            if self.is_dir():
+                raise IsADirectoryError(f"Is a directory: {self}")
+
+            # For writing, we return a custom file-like object that will update the ZIP when closed
+            if 'b' in mode:  # Binary mode
+                return _ZipWriteFile(self, mode, None)
+            else:  # Text mode
+                encoding = encoding or 'utf-8'
+                return _ZipWriteFile(self, mode, encoding)
+
+        else:
+            raise ValueError(f"Unsupported file mode: {mode}")
+
+    def read_text(self, encoding: str = 'utf-8') -> str:
+        """
+        Read the contents of this file as text.
+
+        Args:
+            encoding: Text encoding
+
+        Returns:
+            The file contents as a string
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            IsADirectoryError: If the path points to a directory
+        """
+        return self.read_bytes().decode(encoding)
+
+    def write_text(self, data: str, encoding: str = 'utf-8') -> int:
+        """
+        Write text to this file.
+
+        Args:
+            data: The text to write
+            encoding: Text encoding
+
+        Returns:
+            The number of characters written
+
+        Raises:
+            IsADirectoryError: If the path points to a directory
+        """
+        self._clear_cached_info()
+        if self.exists():
+            warnings.warn(
+                ZipPathDuplicateFileWarning(self._path),
+                stacklevel=2,
+            )
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=UserWarning)
+            with self.open('wt', encoding=encoding) as f:
+                return f.write(data)
+
+    def read_bytes(self) -> bytes:
+        """
+        Read the contents of this file as bytes.
+
+        Returns:
+            The file contents as bytes
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            IsADirectoryError: If the path points to a directory
+        """
+        with self.open('rb') as f:
+            return f.read()
+
+    def write_bytes(self, data: bytes) -> int:
+        """
+        Write bytes to this file.
+
+        Args:
+            data: The bytes to write
+
+        Returns:
+            The number of bytes written
+
+        Raises:
+            IsADirectoryError: If the path points to a directory
+        """
+        self._clear_cached_info()
+        if self.exists():
+            warnings.warn(
+                ZipPathDuplicateFileWarning(self._path),
+                stacklevel=2,
+            )
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=UserWarning)
+            with self.open('wb') as f:
+                return f.write(data)
+
+    @property
+    def parent(self) -> ZipPath:
+        """
+        Return the parent directory of this path.
+
+        Returns:
+            A ZipPath object pointing to the parent directory
+        """
+        parent_path = str(PurePath(self._path).parent)
+        return ZipPath(self.zip_filename, parent_path, mode=self._mode)
+
+    @functools.cached_property
+    def _info(self) -> zipfile.ZipInfo | None:
+        if not self.is_file() or not self.exists():
+            return None
+
+        with self._get_zipfile() as zf:
+            info: zipfile.ZipInfo = zf.getinfo(self._path)
+
+        return info
+
+    def _clear_cached_info(self):
+        with contextlib.suppress(AttributeError):
+            del self._info
+
+    def stat(self) -> os.stat_result:
+        """
+        Return a simulated stat.stat_result object for this file/directory.
+        """
+        if not self.exists():
+            raise FileNotFoundError(f"File not found in ZIP: {self}")
+
+        ret_st_mode = (
+            (stat.S_IFDIR if self.is_dir() else stat.S_IFREG)
+            | stat.S_IREAD
+            | (stat.S_IWRITE if "w" in self._mode else 0)
+        )
+
+        if self.is_file():
+            ret_st_size = self._info.file_size
+        else:
+            ret_st_size = 0
+
+        ret_atime = ret_mtime = ret_ctime = int(self._zipfile_stat.st_mtime)
+
+        return os.stat_result(
+            _ZipStat(
+                st_mode=ret_st_mode,
+                st_size=ret_st_size,
+                st_atime=ret_atime,
+                st_mtime=ret_mtime,
+                st_ctime=ret_ctime,
+            )
+        )
+
+    def size(self) -> int:
+        return self.stat().st_size
+
+    def total_size(self) -> int:
+        return sum(p.size() for p in self.riterdir())
+
+    def rmdir(self) -> None:
+        """Not supported."""
+        raise NotImplementedError(f"{type(self).__name__} does not support removing directories")
+
+    def unlink(self, *args) -> None:
+        """Not supported."""
+        raise NotImplementedError(f"{type(self).__name__} does not support removing files")
+
+    def rename(self, *args) -> None:
+        """Not supported."""
+        raise NotImplementedError(f"{type(self).__name__} does not support renaming files or directories")
+
+    def replace(self, *args) -> None:
+        """Not supported."""
+        raise NotImplementedError(f"{type(self).__name__} does not support replacing files or directories")
+
+    def chmod(self, *args) -> None:
+        """Not supported."""
+        raise NotImplementedError(f"{type(self).__name__} does not support changing file permissions")
+
+    def scan_for_large_files(self, cutoff_size: int) -> list[tuple[str, int]]:
+        large_files = []
+        for f in self.riterdir():
+            if f.is_file() and f.size() > cutoff_size:
+                large_files.append((f._path, f.size()))
+        return large_files
+
+    def scan_for_duplicates(self) -> list[tuple[str, int]]:
+        from collections import Counter
+        with self._get_zipfile() as zf:
+            file_tally = Counter(zf.namelist())
+            dupes = [(name, count) for name, count in file_tally.items() if count > 1]
+            return dupes
+
+    def get_deduplicated_entries(self) -> list[zipfile.ZipInfo]:
+        with self._get_zipfile() as zf:
+            deduped = {
+                info.filename: info for info in zf.infolist()
+            }
+            return list(deduped.values())
+
+    def purge_duplicates(
+            self,
+            *,
+            workdir: Path | str = None,
+            replace: bool = False,
+            keep: bool = False,
+    ):
+        """
+        Remove duplicate versions of any files.
+
+        Since ZIP files do not support actual deletion of entries, this requires creating
+        a new ZIP archive, and only copying the deduplicated files into it.
+
+        Since this involves extracting files from the original ZIP, we also need to
+        guard against malicious ZIP bomb files.
+        """
+        import tempfile
+        import shutil
+
+        if workdir is None:
+            workdir = Path(tempfile.gettempdir())
+        if isinstance(workdir, str):
+            workdir = Path(workdir)
+
+        dest = workdir / self.zip_filename.name
+
+        dupes = self.scan_for_duplicates()
+        if not dupes:
+            return
+
+        deduped: list[zipfile.ZipInfo] = self.get_deduplicated_entries()
+        if deduped:
+            with zipfile.ZipFile(
+                dest,
+                mode="w",
+                compression=zipfile.ZIP_DEFLATED,
+                compresslevel=9,
+            ) as new_zf:
+                for entry_info in deduped:
+                    if entry_info.is_dir():
+                        continue
+                    entry = self / entry_info.filename
+                    print(f"adding {entry._path}")
+                    new_zf.writestr(entry._path, entry.read_bytes())
+
+            if replace:
+                if keep:
+                    shutil.copy2(dest, self.zip_filename)
+                else:
+                    shutil.move(dest, self.zip_filename)
+            else:
+                if not keep:
+                    dest.unlink()

zippathlib-0.6.0.dist-info/METADATA

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: zippathlib
+Version: 0.6.0
+Summary: A `pathlib.Path`-like class for accessing the contents of ZIP archives
+Author-email: Paul McGuire <ptmcg_pm+zippathlib@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ptmcg/zippathlib
+Project-URL: Source, https://github.com/ptmcg/zippathlib.git
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=9.7.0
+Dynamic: license-file
+
+# zippathlib - Provides a pathlib.Path-like class for accessing files in ZIP archives
+
+`zippathlib` is a Python library that provides a standalone `ZipPath` class for working with files 
+inside ZIP archives using a familiar pathlib.Path-like interface. This allows you to navigate and 
+access files within a ZIP archive without first extracting them. From your Python code, you can access
+the contents using the familar `pathlib.Path` API, instead of the standard library's `zipfile` module, and
+perform operations like reading, writing, checking existence of files and directories, etc.
+
+`zippathlib` is also accessible from the command line, allowing you to list contents of ZIP archives,
+extract individual files or directories, and view the contents of the ZIP archive as a tree.
+
+<!-- TOC -->
+* [zippathlib - Provides a pathlib.Path-like class for accessing files in ZIP archives](#zippathlib---provides-a-pathlibpath-like-class-for-accessing-files-in-zip-archives)
+  * [Features](#features)
+  * [Doesn't Python's `zipfile` module already have a `Path` class?](#doesnt-pythons-zipfile-module-already-have-a-path-class)
+  * [Usage - Command line](#usage---command-line)
+    * [List the root directory of a ZIP archive](#list-the-root-directory-of-a-zip-archive)
+    * [List the files in a directory](#list-the-files-in-a-directory)
+    * [List the first few lines of a file](#list-the-first-few-lines-of-a-file)
+    * [Extract a file from a ZIP archive to the local filesystem](#extract-a-file-from-a-zip-archive-to-the-local-filesystem)
+    * [Extract a file from a ZIP archive to stdout](#extract-a-file-from-a-zip-archive-to-stdout)
+    * [View the contents of a ZIP archive (or a subdirectory within the ZIP archive) as a tree](#view-the-contents-of-a-zip-archive-or-a-subdirectory-within-the-zip-archive-as-a-tree)
+  * [Usage - `zippathlib.ZipPath` API](#usage---zippathlibzippath-api)
+    * [Open a file from a ZIP archive for reading](#open-a-file-from-a-zip-archive-for-reading)
+    * [Store a file into a ZIP archive, and use the '/' operator to navigate or create directories](#store-a-file-into-a-zip-archive-and-use-the--operator-to-navigate-or-create-directories)
+    * [List all files in a directory within the ZIP](#list-all-files-in-a-directory-within-the-zip)
+    * [Recursively list all directories and files in the ZIP](#recursively-list-all-directories-and-files-in-the-zip)
+    * [Check if a file exists in the ZIP](#check-if-a-file-exists-in-the-zip)
+  * [Installation](#installation)
+  * [Testing](#testing)
+  * [Contributing](#contributing)
+  * [License](#license)
+<!-- TOC -->
+
+## Features
+- `ZipPath` class provides a pathlib-like API to access ZIP archive files and directories.
+- Supports path composition using the '/' operator.
+- Supports basic read/write operations on files within a ZIP archive, including opening files for reading, writing data, etc.
+- Allows navigating the directory structure within a ZIP archive using familiar `pathlib` methods like `iterdir()`, `joinpath()`, etc.
+ `riterdir()` provides a recursive listing of the directories and files in the archive.
+- Command-line interface for browsing a ZIP archive's contents, or for extracting files to the local filesystem.
+
+
+## Doesn't Python's `zipfile` module already have a `Path` class?
+
+The Python standard library module `zipfile` does provide a `Path` [class](https://docs.python.org/3/library/zipfile.html#zipfile.Path), 
+but it is primarily for read support in existing ZIP files. It doesn't provide a complete `pathlib`-like API for working with files and directories.
+
+
+## Usage - Command line
+After installing it, the `zippathlib` module can be run from the command line with `python -m zippathlib` or just `zippathlib`.
+
+    $ zippathlib -h
+    usage: zippathlib [-h] [-V] [--tree] [-x [OUTPUTDIR]] [--limit LIMIT] [--check {duplicates,limit,d,l}] [--purge]
+                      zip_file [path_within_zip]
+    
+    positional arguments:
+      zip_file              Zip file to explore
+      path_within_zip       Path within the zip file (optional)
+    
+    options:
+      -h, --help            show this help message and exit
+      -V, --version         show program's version number and exit
+      --tree                list all files in a tree-like format
+      -x, --extract [OUTPUTDIR]
+                            extract files from zip file to a directory or '-' for stdout,
+                            default is '.'
+      --limit LIMIT         guard value against malicious ZIP files that uncompress to excessive
+                            sizes; specify as an integer or float value optionally followed by a
+                            multiplier suffix K,M,G,T,P,E, or Z; default is 2.00G
+      --check {duplicates,limit,d,l}
+                            check ZIP file for duplicates, or for files larger than LIMIT
+      --purge               purge ZIP file of duplicate file entries
+
+### List the root directory of a ZIP archive
+
+    $ zippathlib .\dist\zippathlib-0.4.0-py3-none-any.whl
+    Directory: dist\zippathlib-0.4.0-py3-none-any.whl:: (total size 39.76KB)
+    Contents:
+      [D] zippathlib (28.32KB)
+      [D] zippathlib-0.4.0.dist-info (11.44KB)
+
+### List the files in a directory
+
+    $ zippathlib .\dist\zippathlib-0.4.0-py3-none-any.whl zippathlib-0.4.0.dist-info
+    Directory: dist\zippathlib-0.4.0-py3-none-any.whl::zippathlib-0.4.0.dist-info (total size 11.44KB)
+    Contents:
+      [D] licenses (1.06KB)
+      [F] METADATA (9.49KB)
+      [F] WHEEL (91 bytes)
+      [F] entry_points.txt (56 bytes)
+      [F] top_level.txt (11 bytes)
+      [F] RECORD (748 bytes
+
+### List the first few lines of a file
+
+    $ zippathlib .\dist\zippathlib-0.4.0-py3-none-any.whl zippathlib-0.4.0.dist-info/licenses/LICENSE
+    File: dist\zippathlib-0.4.0-py3-none-any.whl::zippathlib-0.4.0.dist-info/licenses/LICENSE (1.06KB)
+    Content:
+    MIT License
+    
+    Copyright (c) 2025 Paul McGuire
+
+Permission is hereby granted, free of charge, to a...
+
+### Extract a file from a ZIP archive to the local filesystem
+
+    # if outputdir is omitted, file is extracted to the current directory
+    $ zippathlib .\dist\zippathlib-0.4.0-py3-none-any.whl zippathlib-0.4.0.dist-info/licenses/LICENSE --extract tmp
+    extracting dist\zippathlib-0.4.0-py3-none-any.whl::zippathlib-0.4.0.dist-info/licenses/LICENSE
+
+### Extract a file from a ZIP archive to stdout
+
+    # if outputdir is "-", file is extracted and printed to stdout
+    $ zippathlib .\dist\zippathlib-0.4.0-py3-none-any.whl zippathlib-0.4.0.dist-info/licenses/LICENSE --extract -
+    MIT License
+    
+    Copyright (c) 2025 Paul McGuire
+    
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    ...
+
+### View the contents of a ZIP archive (or a subdirectory within the ZIP archive) as a tree
+
+    $ zippathlib .\dist\zippathlib-0.4.0-py3-none-any.whl --tree                                                 
+
+    ├── zippathlib-0.4.0.dist-info
+    │   ├── RECORD
+    │   ├── top_level.txt
+    │   ├── entry_points.txt
+    │   ├── WHEEL
+    │   ├── METADATA
+    │   └── licenses
+    │       └── LICENSE
+    └── zippathlib
+        ├── zip_pathlib.py
+        ├── __main__.py
+        └── __init__.py
+
+(Thanks to Will McGugan's `rich` library for making the tree output so easy.)
+
+## Usage - `zippathlib.ZipPath` API
+
+Here are some examples on how to use `ZipPath` in your Python code:
+
+### Open a file from a ZIP archive for reading
+
+```python
+from zippathlib import ZipPath
+
+zip_path = ZipPath('archive.zip', 'path/to/file.txt')
+with zip_path.open() as f:
+    content = f.read()
+```
+
+### Store a file into a ZIP archive, and use the '/' operator to navigate or create directories
+
+```python
+from zippathlib import ZipPath
+
+zp = ZipPath('archive.zip')
+content_file = zp / 'some/directory' / 'file.txt'
+content_file.write_text("This is too easy!")
+```
+
+
+### List all files in a directory within the ZIP
+
+```python
+from zippathlib import ZipPath
+
+zip_path = ZipPath('archive.zip')
+for file in (zip_path / 'some' / 'directory').iterdir():
+    print(file)
+```
+
+### Recursively list all directories and files in the ZIP
+
+```python
+from zippathlib import ZipPath
+
+zip_path = ZipPath('archive.zip')
+
+# list all contents, in depth first search
+for file in zip_path.riterdir():
+    print(file)
+```
+
+### Check if a file exists in the ZIP
+
+```python
+from zippathlib import ZipPath
+
+if ZipPath('archive.zip', 'path/to/file.txt').exists():
+    print("File exists")
+```
+
+## Installation
+You can install `ZipPath` using `pip` or `pipx`:
+
+```bash
+pip install zippathlib
+```
+
+## Testing
+Tests are located in the tests directory and can be run using pytest:
+
+```bash
+pytest tests
+```
+
+## Contributing
+Contributions are welcome. Please open an issue or submit a pull request on [GitHub](https://github.com/ptmcg/zippathlib).
+
+If you have ideas or suggestions, feel free to drop a note in the GitHub repo [Discussions](https://github.com/ptmcg/zippathlib/discussions).
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.

zippathlib-0.6.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+zippathlib/__init__.py,sha256=qxC_vTSj8evxfsgf1x-k6sMbGeW5hAWfnTgYatt7nZA,228
+zippathlib/__main__.py,sha256=7ynPcm2FBM5CFhEJEzNk1xbjQ4EH_f2UjO-OdL04lTQ,8568
+zippathlib/zip_pathlib.py,sha256=EbFY1IHRiMB5-txpLdFIa2sq01KWgehOAghnMEHfo-o,24334
+zippathlib-0.6.0.dist-info/licenses/LICENSE,sha256=B0BZBr37IGE4EPrbiOE93PnBCVyrKLXJqBXC8EFHzgE,1069
+zippathlib-0.6.0.dist-info/METADATA,sha256=NblnxGFP2daBwLYwCL7fTrwPFTRjR5_vEWo3VLGOrnE,10458
+zippathlib-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+zippathlib-0.6.0.dist-info/entry_points.txt,sha256=oGQt99IKEGPX1DBW3L7boQxFDl2L9a67XQw5LyUYrZk,56
+zippathlib-0.6.0.dist-info/top_level.txt,sha256=uM8DB-MPxHohOJpSSggSc-wro5y_nw-VNtkcE7rSzHI,11
+zippathlib-0.6.0.dist-info/RECORD,,

zippathlib-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zippathlib-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zippathlib = zippathlib:__main__.main

zippathlib-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul McGuire
+
+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.

zippathlib-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zippathlib