splitzip 0.1.0__py3-none-any.whl

splitzip/__init__.py

@@ -0,0 +1,107 @@
+"""
+splitzip - Create split ZIP archives compatible with standard tools.
+
+Create multi-part ZIP archives that can be extracted with Windows Explorer,
+WinZip, 7-Zip, and other standard tools without requiring special software.
+
+Example:
+    >>> import splitzip
+    >>> 
+    >>> # Simple one-liner
+    >>> splitzip.create("backup.zip", ["file1.txt", "data/"], split_size="100MB")
+    >>> 
+    >>> # Context manager for more control
+    >>> with splitzip.SplitZipWriter("backup.zip", split_size="100MB") as zf:
+    ...     zf.write("file1.txt")
+    ...     zf.write("data/", recursive=True)
+    ...     zf.writestr("hello.txt", b"Hello, world!")
+
+The resulting files will be named:
+    backup.z01, backup.z02, ..., backup.zip
+
+The final .zip file contains the central directory and must be present
+along with all .zXX files for extraction.
+"""
+
+from .exceptions import (
+    CompressionError,
+    FileNotFoundInArchiveError,
+    IntegrityError,
+    SplitZipError,
+    VolumeTooSmallError,
+    VolumeError,
+)
+from .structures import Compression
+from .utils import format_size, parse_size
+from .writer import SplitZipWriter
+
+__version__ = "0.1.0"
+__all__ = [
+    # Main classes
+    "SplitZipWriter",
+    # Convenience functions
+    "create",
+    # Constants
+    "Compression",
+    "STORED",
+    "DEFLATED",
+    # Utilities
+    "parse_size",
+    "format_size",
+    # Exceptions
+    "SplitZipError",
+    "VolumeError",
+    "VolumeTooSmallError",
+    "CompressionError",
+    "IntegrityError",
+    "FileNotFoundInArchiveError",
+]
+
+# Convenience aliases
+STORED = Compression.STORED
+DEFLATED = Compression.DEFLATED
+
+
+def create(
+    path: str,
+    files: list[str],
+    split_size: int | str,
+    compression: int = DEFLATED,
+    compresslevel: int = 6,
+    recursive: bool = True,
+) -> list[str]:
+    """
+    Create a split ZIP archive from a list of files/directories.
+
+    This is a convenience function for simple use cases. For more control,
+    use SplitZipWriter directly.
+
+    Args:
+        path: Path for the final .zip file.
+        files: List of file/directory paths to include.
+        split_size: Maximum size per volume (e.g., "100MB", "700MiB", 104857600).
+        compression: Compression method (STORED or DEFLATED).
+        compresslevel: DEFLATE compression level 1-9 (default 6).
+        recursive: If True, add directory contents recursively.
+
+    Returns:
+        List of paths to all volume files created.
+
+    Example:
+        >>> splitzip.create(
+        ...     "backup.zip",
+        ...     ["documents/", "photos/", "important.pdf"],
+        ...     split_size="650MB"  # CD-ROM size
+        ... )
+        ['backup.z01', 'backup.z02', 'backup.zip']
+    """
+    with SplitZipWriter(
+        path,
+        split_size=split_size,
+        compression=compression,
+        compresslevel=compresslevel,
+    ) as zf:
+        for file_path in files:
+            zf.write(file_path, recursive=recursive)
+
+    return [str(p) for p in zf.volume_paths]

splitzip/__main__.py

@@ -0,0 +1,153 @@
+"""Command-line interface for splitzip."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import SplitZipWriter, __version__, format_size, parse_size
+from .structures import Compression
+
+
+def progress_callback(filename: str, done: int, total: int) -> None:
+    """Print progress for current file."""
+    if total > 0:
+        pct = (done / total) * 100
+        bar_width = 30
+        filled = int(bar_width * done / total)
+        bar = "█" * filled + "░" * (bar_width - filled)
+        print(f"\r  {bar} {pct:5.1f}% {Path(filename).name}", end="", flush=True)
+        if done >= total:
+            print()
+
+
+def volume_callback(volume_num: int, path: Path) -> None:
+    """Print when a new volume is created."""
+    print(f"  Created: {path}")
+
+
+def cmd_create(args: argparse.Namespace) -> int:
+    """Handle the create command."""
+    output = Path(args.output)
+    files = [Path(f) for f in args.files]
+
+    # Validate inputs
+    for f in files:
+        if not f.exists():
+            print(f"Error: '{f}' does not exist", file=sys.stderr)
+            return 1
+
+    try:
+        split_size = parse_size(args.split_size)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    compression = Compression.STORED if args.store else Compression.DEFLATED
+
+    print(f"Creating split archive: {output}")
+    print(f"  Split size: {format_size(split_size)}")
+    print(f"  Compression: {'STORED' if args.store else f'DEFLATE level {args.level}'}")
+    print()
+
+    try:
+        with SplitZipWriter(
+            output,
+            split_size=split_size,
+            compression=compression,
+            compresslevel=args.level,
+            on_volume=volume_callback if args.verbose else None,
+            on_progress=progress_callback if args.verbose else None,
+        ) as zf:
+            for file_path in files:
+                if args.verbose:
+                    print(f"Adding: {file_path}")
+                zf.write(file_path, recursive=not args.no_recursive)
+
+        print()
+        print(f"Created {len(zf.volume_paths)} volume(s):")
+        for p in zf.volume_paths:
+            size = p.stat().st_size
+            print(f"  {p.name}: {format_size(size)}")
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for CLI."""
+    parser = argparse.ArgumentParser(
+        prog="splitzip",
+        description="Create split ZIP archives compatible with standard tools.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Create command
+    create_parser = subparsers.add_parser(
+        "create",
+        help="Create a split ZIP archive",
+        description="Create a split ZIP archive from files and directories.",
+    )
+    create_parser.add_argument(
+        "-o", "--output",
+        required=True,
+        help="Output archive path (e.g., backup.zip)",
+    )
+    create_parser.add_argument(
+        "-s", "--split-size",
+        required=True,
+        help="Maximum size per volume (e.g., 100MB, 700MiB, 4.7GB)",
+    )
+    create_parser.add_argument(
+        "files",
+        nargs="+",
+        help="Files and directories to add",
+    )
+    create_parser.add_argument(
+        "-0", "--store",
+        action="store_true",
+        help="Store without compression",
+    )
+    create_parser.add_argument(
+        "-l", "--level",
+        type=int,
+        default=6,
+        choices=range(1, 10),
+        metavar="1-9",
+        help="Compression level (default: 6)",
+    )
+    create_parser.add_argument(
+        "--no-recursive",
+        action="store_true",
+        help="Don't add directory contents recursively",
+    )
+    create_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Show progress and volume creation",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.command == "create":
+        return cmd_create(args)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

splitzip/exceptions.py

@@ -0,0 +1,45 @@
+"""Custom exceptions for splitzip."""
+
+
+class SplitZipError(Exception):
+    """Base exception for all splitzip errors."""
+
+
+class VolumeError(SplitZipError):
+    """Error related to volume management."""
+
+
+class VolumeTooSmallError(VolumeError):
+    """Split size is too small to fit required headers."""
+
+    def __init__(self, split_size: int, min_required: int) -> None:
+        self.split_size = split_size
+        self.min_required = min_required
+        super().__init__(
+            f"Split size {split_size} bytes is too small. "
+            f"Minimum required: {min_required} bytes"
+        )
+
+
+class CompressionError(SplitZipError):
+    """Error during compression."""
+
+
+class IntegrityError(SplitZipError):
+    """CRC mismatch or corrupted data."""
+
+    def __init__(self, expected: int, actual: int, filename: str) -> None:
+        self.expected = expected
+        self.actual = actual
+        self.filename = filename
+        super().__init__(
+            f"CRC32 mismatch for '{filename}': expected {expected:08x}, got {actual:08x}"
+        )
+
+
+class FileNotFoundInArchiveError(SplitZipError):
+    """Requested file not found in archive."""
+
+    def __init__(self, filename: str) -> None:
+        self.filename = filename
+        super().__init__(f"File not found in archive: '{filename}'")

splitzip/structures.py

@@ -0,0 +1,386 @@
+"""ZIP file format data structures.
+
+Based on PKWARE's APPNOTE.TXT specification.
+https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import ClassVar
+
+
+class Compression(IntEnum):
+    """Compression methods supported by ZIP."""
+
+    STORED = 0  # No compression
+    DEFLATED = 8  # DEFLATE compression
+
+
+class GeneralPurposeFlag(IntEnum):
+    """General purpose bit flags."""
+
+    ENCRYPTED = 1 << 0
+    # Bits 1-2: compression options (for DEFLATE: 0=normal, 1=max, 2=fast, 3=super fast)
+    DATA_DESCRIPTOR = 1 << 3  # CRC and sizes in data descriptor after file data
+    ENHANCED_DEFLATE = 1 << 4
+    COMPRESSED_PATCHED = 1 << 5
+    STRONG_ENCRYPTION = 1 << 6
+    UTF8 = 1 << 11  # Filename and comment are UTF-8 encoded
+    ENHANCED_COMPRESSION = 1 << 12
+    MASKED_HEADERS = 1 << 13
+
+
+# Signatures
+LOCAL_FILE_HEADER_SIG = 0x04034B50
+CENTRAL_DIR_HEADER_SIG = 0x02014B50
+END_OF_CENTRAL_DIR_SIG = 0x06054B50
+DATA_DESCRIPTOR_SIG = 0x08074B50
+SPLIT_ARCHIVE_SIG = 0x08074B50  # Same as data descriptor
+
+
+@dataclass
+class LocalFileHeader:
+    """Local file header structure (precedes each file's data)."""
+
+    SIGNATURE: ClassVar[int] = LOCAL_FILE_HEADER_SIG
+    STRUCT_FORMAT: ClassVar[str] = "<IHHHHHIIIHH"
+    FIXED_SIZE: ClassVar[int] = 30  # Size without filename and extra
+
+    version_needed: int = 20  # 2.0 for DEFLATE
+    flags: int = 0
+    compression: int = Compression.DEFLATED
+    mod_time: int = 0
+    mod_date: int = 0
+    crc32: int = 0
+    compressed_size: int = 0
+    uncompressed_size: int = 0
+    filename: bytes = b""
+    extra: bytes = b""
+
+    def to_bytes(self) -> bytes:
+        """Serialize to bytes."""
+        header = struct.pack(
+            self.STRUCT_FORMAT,
+            self.SIGNATURE,
+            self.version_needed,
+            self.flags,
+            self.compression,
+            self.mod_time,
+            self.mod_date,
+            self.crc32,
+            self.compressed_size,
+            self.uncompressed_size,
+            len(self.filename),
+            len(self.extra),
+        )
+        return header + self.filename + self.extra
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "LocalFileHeader":
+        """Deserialize from bytes."""
+        if len(data) < cls.FIXED_SIZE:
+            raise ValueError(f"Data too short for LocalFileHeader: {len(data)} < {cls.FIXED_SIZE}")
+
+        (
+            sig,
+            version_needed,
+            flags,
+            compression,
+            mod_time,
+            mod_date,
+            crc32,
+            compressed_size,
+            uncompressed_size,
+            filename_len,
+            extra_len,
+        ) = struct.unpack(cls.STRUCT_FORMAT, data[: cls.FIXED_SIZE])
+
+        if sig != cls.SIGNATURE:
+            raise ValueError(f"Invalid local file header signature: {sig:#010x}")
+
+        filename = data[cls.FIXED_SIZE : cls.FIXED_SIZE + filename_len]
+        extra = data[cls.FIXED_SIZE + filename_len : cls.FIXED_SIZE + filename_len + extra_len]
+
+        return cls(
+            version_needed=version_needed,
+            flags=flags,
+            compression=compression,
+            mod_time=mod_time,
+            mod_date=mod_date,
+            crc32=crc32,
+            compressed_size=compressed_size,
+            uncompressed_size=uncompressed_size,
+            filename=filename,
+            extra=extra,
+        )
+
+    @property
+    def total_size(self) -> int:
+        """Total size of header including variable fields."""
+        return self.FIXED_SIZE + len(self.filename) + len(self.extra)
+
+
+@dataclass
+class DataDescriptor:
+    """Optional data descriptor (follows file data when sizes unknown upfront)."""
+
+    SIGNATURE: ClassVar[int] = DATA_DESCRIPTOR_SIG
+    STRUCT_FORMAT_WITH_SIG: ClassVar[str] = "<IIII"
+    STRUCT_FORMAT_NO_SIG: ClassVar[str] = "<III"
+    SIZE_WITH_SIG: ClassVar[int] = 16
+    SIZE_NO_SIG: ClassVar[int] = 12
+
+    crc32: int = 0
+    compressed_size: int = 0
+    uncompressed_size: int = 0
+
+    def to_bytes(self, include_signature: bool = True) -> bytes:
+        """Serialize to bytes."""
+        if include_signature:
+            return struct.pack(
+                self.STRUCT_FORMAT_WITH_SIG,
+                self.SIGNATURE,
+                self.crc32,
+                self.compressed_size,
+                self.uncompressed_size,
+            )
+        else:
+            return struct.pack(
+                self.STRUCT_FORMAT_NO_SIG,
+                self.crc32,
+                self.compressed_size,
+                self.uncompressed_size,
+            )
+
+
+@dataclass
+class CentralDirectoryHeader:
+    """Central directory file header."""
+
+    SIGNATURE: ClassVar[int] = CENTRAL_DIR_HEADER_SIG
+    STRUCT_FORMAT: ClassVar[str] = "<IHHHHHHIIIHHHHHII"
+    FIXED_SIZE: ClassVar[int] = 46
+
+    version_made_by: int = 20  # 2.0, MS-DOS compatible
+    version_needed: int = 20
+    flags: int = 0
+    compression: int = Compression.DEFLATED
+    mod_time: int = 0
+    mod_date: int = 0
+    crc32: int = 0
+    compressed_size: int = 0
+    uncompressed_size: int = 0
+    disk_number_start: int = 0  # Disk where file starts
+    internal_attr: int = 0
+    external_attr: int = 0
+    local_header_offset: int = 0  # Offset of local header on starting disk
+    filename: bytes = b""
+    extra: bytes = b""
+    comment: bytes = b""
+
+    def to_bytes(self) -> bytes:
+        """Serialize to bytes."""
+        header = struct.pack(
+            self.STRUCT_FORMAT,
+            self.SIGNATURE,
+            self.version_made_by,
+            self.version_needed,
+            self.flags,
+            self.compression,
+            self.mod_time,
+            self.mod_date,
+            self.crc32,
+            self.compressed_size,
+            self.uncompressed_size,
+            len(self.filename),
+            len(self.extra),
+            len(self.comment),
+            self.disk_number_start,
+            self.internal_attr,
+            self.external_attr,
+            self.local_header_offset,
+        )
+        return header + self.filename + self.extra + self.comment
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "CentralDirectoryHeader":
+        """Deserialize from bytes."""
+        if len(data) < cls.FIXED_SIZE:
+            raise ValueError(
+                f"Data too short for CentralDirectoryHeader: {len(data)} < {cls.FIXED_SIZE}"
+            )
+
+        (
+            sig,
+            version_made_by,
+            version_needed,
+            flags,
+            compression,
+            mod_time,
+            mod_date,
+            crc32,
+            compressed_size,
+            uncompressed_size,
+            filename_len,
+            extra_len,
+            comment_len,
+            disk_number_start,
+            internal_attr,
+            external_attr,
+            local_header_offset,
+        ) = struct.unpack(cls.STRUCT_FORMAT, data[: cls.FIXED_SIZE])
+
+        if sig != cls.SIGNATURE:
+            raise ValueError(f"Invalid central directory header signature: {sig:#010x}")
+
+        offset = cls.FIXED_SIZE
+        filename = data[offset : offset + filename_len]
+        offset += filename_len
+        extra = data[offset : offset + extra_len]
+        offset += extra_len
+        comment = data[offset : offset + comment_len]
+
+        return cls(
+            version_made_by=version_made_by,
+            version_needed=version_needed,
+            flags=flags,
+            compression=compression,
+            mod_time=mod_time,
+            mod_date=mod_date,
+            crc32=crc32,
+            compressed_size=compressed_size,
+            uncompressed_size=uncompressed_size,
+            disk_number_start=disk_number_start,
+            internal_attr=internal_attr,
+            external_attr=external_attr,
+            local_header_offset=local_header_offset,
+            filename=filename,
+            extra=extra,
+            comment=comment,
+        )
+
+    @property
+    def total_size(self) -> int:
+        """Total size of header including variable fields."""
+        return self.FIXED_SIZE + len(self.filename) + len(self.extra) + len(self.comment)
+
+
+@dataclass
+class EndOfCentralDirectory:
+    """End of central directory record."""
+
+    SIGNATURE: ClassVar[int] = END_OF_CENTRAL_DIR_SIG
+    STRUCT_FORMAT: ClassVar[str] = "<IHHHHIIH"
+    FIXED_SIZE: ClassVar[int] = 22
+
+    disk_number: int = 0  # Number of this disk
+    disk_with_cd_start: int = 0  # Disk where central directory starts
+    entries_on_disk: int = 0  # Entries in central directory on this disk
+    total_entries: int = 0  # Total entries in central directory
+    cd_size: int = 0  # Size of central directory
+    cd_offset: int = 0  # Offset of central directory on starting disk
+    comment: bytes = b""
+
+    def to_bytes(self) -> bytes:
+        """Serialize to bytes."""
+        return struct.pack(
+            self.STRUCT_FORMAT,
+            self.SIGNATURE,
+            self.disk_number,
+            self.disk_with_cd_start,
+            self.entries_on_disk,
+            self.total_entries,
+            self.cd_size,
+            self.cd_offset,
+            len(self.comment),
+        ) + self.comment
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "EndOfCentralDirectory":
+        """Deserialize from bytes."""
+        if len(data) < cls.FIXED_SIZE:
+            raise ValueError(
+                f"Data too short for EndOfCentralDirectory: {len(data)} < {cls.FIXED_SIZE}"
+            )
+
+        (
+            sig,
+            disk_number,
+            disk_with_cd_start,
+            entries_on_disk,
+            total_entries,
+            cd_size,
+            cd_offset,
+            comment_len,
+        ) = struct.unpack(cls.STRUCT_FORMAT, data[: cls.FIXED_SIZE])
+
+        if sig != cls.SIGNATURE:
+            raise ValueError(f"Invalid end of central directory signature: {sig:#010x}")
+
+        comment = data[cls.FIXED_SIZE : cls.FIXED_SIZE + comment_len]
+
+        return cls(
+            disk_number=disk_number,
+            disk_with_cd_start=disk_with_cd_start,
+            entries_on_disk=entries_on_disk,
+            total_entries=total_entries,
+            cd_size=cd_size,
+            cd_offset=cd_offset,
+            comment=comment,
+        )
+
+    @property
+    def total_size(self) -> int:
+        """Total size of record including comment."""
+        return self.FIXED_SIZE + len(self.comment)
+
+
+@dataclass
+class ZipEntry:
+    """Internal tracking of an entry being written."""
+
+    filename: str
+    arcname: bytes
+    compression: int
+    mod_time: int
+    mod_date: int
+    crc32: int = 0
+    compressed_size: int = 0
+    uncompressed_size: int = 0
+    disk_number_start: int = 0
+    local_header_offset: int = 0
+    external_attr: int = 0
+    extra: bytes = b""
+    comment: bytes = b""
+
+    def to_central_directory_header(self) -> CentralDirectoryHeader:
+        """Convert to a CentralDirectoryHeader."""
+        return CentralDirectoryHeader(
+            version_made_by=20,
+            version_needed=20,
+            flags=GeneralPurposeFlag.UTF8,
+            compression=self.compression,
+            mod_time=self.mod_time,
+            mod_date=self.mod_date,
+            crc32=self.crc32,
+            compressed_size=self.compressed_size,
+            uncompressed_size=self.uncompressed_size,
+            disk_number_start=self.disk_number_start,
+            internal_attr=0,
+            external_attr=self.external_attr,
+            local_header_offset=self.local_header_offset,
+            filename=self.arcname,
+            extra=self.extra,
+            comment=self.comment,
+        )
+
+    def _is_utf8(self) -> bool:
+        """Check if filename requires UTF-8 flag."""
+        try:
+            self.arcname.decode("ascii")
+            return False
+        except UnicodeDecodeError:
+            return True