py-zippy 1.0.0__py3-none-any.whl

py_zippy-1.0.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: py-zippy
+Version: 1.0.0
+Summary: Archive Utility Toolkit supporting multi-format workflows, password recovery, and repair helpers.
+Author-email: John Hauger Mitander <john@on1.no>
+License: MIT License
+        
+        Copyright (c) 2025 John H. Mitander
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/John0n1/ZIPPY
+Project-URL: Documentation, https://github.com/John0n1/ZIPPY#readme
+Project-URL: Issues, https://github.com/John0n1/ZIPPY/issues
+Keywords: archives,zip,tar,cli,toolkit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyzipper>=0.3.6
+Requires-Dist: patool>=1.12
+Dynamic: license-file
+
+<div align="center">
+
+# Zippy
+
+**Multi-purpose archive extraction, repair and brute-force toolkit.**
+
+</div>
+
+![PyPI](https://img.shields.io/pypi/v/zippy-toolkit?color=blue&logo=pypi&style=flat-square) ![Python](https://img.shields.io/pypi/pyversions/zippy-toolkit?color=blue&logo=python&style=flat-square) ![License](https://img.shields.io/pypi/l/zippy-toolkit?color=blue&logo=apache&style=flat-square) ![Build](https://img.shields.io/github/actions/workflow/status/John0n1/ZIPPY/ci.yml?branch=main&label=build&logo=github&style=flat-square) ![Coverage](https://img.shields.io/codecov/c/github/John0n1/ZIPPY/main?logo=codecov&style=flat-square)
+
+```bash
+
+- **Broad format coverage** - (`tar`, `tar.gz`, `tar.bz2`, `tar.xz`, `tar.lzma`), (`gzip`, `bz2`, `xz`, `lzma`), `7z`, `rar`, `zstd` and ZIP family (including APK/JAR/WAR/IPA/EAR).
+- **Consistent UX** - consistent logging, progress indicators, and tab completion for every command.
+- **Security tooling** - create or re-lock encrypted ZIPs, run smart dictionary attacks with the bundled password list, and capture verbose traces when needed.
+- **Integrity & repair** - repair, attempt salvage extractions, and perform best-effort recovery for TAR and single-file formats. It grabs whatever it can, even if files look broken or corrupted. This is achieved by scanning the archive for valid headers and footers, and extracting the data in between, then rebuilding the file structure using advanced data pointers and heuristics.
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+python -m pip install zippy
+```
+
+### From source
+
+```bash
+git clone https://github.com/John0n1/ZIPPY.git
+cd ZIPPY
+python -m pip install .
+
+### Debian package
+
+```bash
+sudo apt install ./zippy_*.deb
+```
+
+## Quick start
+
+```bash
+# Extract an archive
+zippy --extract backups/site.tar.xz -o ./site
+
+# Create a password-protected ZIP from multiple paths
+zippy --lock secure.zip -f docs,images -p "Tru5ted!"
+
+# List TAR.BZ2 contents
+zippy --list datasets.tar.bz2
+
+# Attempt unlocking with the bundled wordlist
+zippy --unlock encrypted.zip -d password_list.txt --verbose
+
+# Run salvage repair on a damaged tarball
+zippy --repair broken.tar.gz --repair-mode remove_corrupted
+```
+
+Run `zippy --help` for the full command reference or `zippy --version` to confirm the installed release.
+
+## Supported archive formats
+
+| Family | Types |
+| ------ | ----- |
+| ZIP | `zip` (with optional password protection) |
+| TAR | `tar`, `tar.gz`, `tar.bz2`, `tar.xz`, `tar.lzma`, `.tgz`, `.tbz`, `.txz`, `.tlz` |
+| Single-file | `gzip` (`.gz`), `bz2` (`.bz2`), `xz` (`.xz`), `lzma` (`.lzma`) |
+
+Unsupported formats (e.g. 7z, rar, zstd) will raise a friendly error instructing you to choose a supported type.
+
+## Configuration & automation
+
+- Use `--save-config <file>` to capture the current flag set (including passwords or dictionary paths if provided).
+- Rehydrate saved flags via `--load-config <file>` for repeatable batch jobs.
+- Disable animations with `--no-animation` for CI environments.
+
+## Logging & colours
+
+Logging defaults to concise `INFO` output. Add `--verbose` for `DEBUG` traces. Colour output automatically downgrades in non-interactive terminals, while animations fall back to plain log messages when disabled or redirected. Windows terminals are supported through `colorama`.
+
+## Password dictionary
+
+The bundled `password_list.txt` contains hundreds of common credentials, curated for demonstration purposes. The unlock command trims duplicates, ignores comments (`# ...`), and safely handles mixed encodings. Supply your own list with `--dictionary <file>` for larger attacks.
+
+## Contributing
+Pull requests are welcome—please open an issue describing the enhancement before submitting substantial changes.
+
+## License
+
+Zippy is released under the MIT License. See `LICENSE` for the full text.
+
+## Disclaimer
+
+Zippy is provided "as is" without warranty of any kind. Use at your own risk and keep backups of critical data.
+
+**The author is not responsible for any data loss or damage resulting from the use of this software.**

py_zippy-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+py_zippy-1.0.0.dist-info/licenses/LICENSE,sha256=9VKiQ2gJZk1vRNRUsnO3nBWxbNyA65LmMo1QORMNyZ0,1073
+zippy/__init__.py,sha256=smZtZ8pgEvlsAVLKZhQqxDtzrk8K9X3VPSfyNqhjkyU,181
+zippy/cli.py,sha256=YM0dRTBVAaDjv0E_NcrMfdHOhcuYbQL4KFWx_OZN5vI,8385
+zippy/create.py,sha256=H3Yb2UDtJoZ2DBB7sdiWdXoXOVVrSNSjD4e_uh1CPFw,9567
+zippy/extract.py,sha256=fGU2_9ORsL50EydvhzLgNwVQk2XZ6XAevp-tJ38vkeA,4773
+zippy/list.py,sha256=7oYCHFKAlyuHw4CpZAmnRz7jmdPC0_yzKNNrs1nvAs8,2336
+zippy/lock.py,sha256=118GnvT3yfIv8wP-DF7M4NCK9Yus1RKtQwdnB0OTlh0,3396
+zippy/repair.py,sha256=7jCgHuv-dVhYFK3iVmpSX4f6JVWF1jbO8TWzfLAH6zk,9700
+zippy/test.py,sha256=9nHneW9q_JUq3Lg3XEYIz4TDYVqK7RfyXFkLrv37xhA,5542
+zippy/unlock.py,sha256=9AQ-6C8jUD0PbE-bXD9LZnropqP5zBh2L6_jHemJtxE,4428
+zippy/utils.py,sha256=YQECi0vyOmz-RqX6bnnODzs162nAD72flw_bsBrCwkQ,10721
+py_zippy-1.0.0.dist-info/METADATA,sha256=b170Pu_W2fU-O9UIjiNK3RcGmzQ5yTHVCu6pabxZ9eg,6647
+py_zippy-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+py_zippy-1.0.0.dist-info/entry_points.txt,sha256=MuEnhP2ZUmhg38SIktO91HhqwYmODGjKj8nfyfI72C0,41
+py_zippy-1.0.0.dist-info/top_level.txt,sha256=Y5J0yny13o5cYQhIr0YVS4WX5bYyFP0iFbMQ1WBa12E,6
+py_zippy-1.0.0.dist-info/RECORD,,

py_zippy-1.0.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
+

py_zippy-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zippy = zippy.cli:main

py_zippy-1.0.0.dist-info/licenses/LICENSE

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

py_zippy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zippy

zippy/__init__.py

@@ -0,0 +1,8 @@
+"""
+zippy - Archive Utility Toolkit
+
+This package provides utilities for working with various archive formats
+including zip, tar, tar.gz, and gzip files.
+"""
+
+__version__ = "1.0.0"

zippy/cli.py

@@ -0,0 +1,286 @@
+import argparse
+import json
+import os
+import readline
+import sys
+from typing import Iterable, Optional
+
+from dotenv import load_dotenv
+
+from . import __version__
+from .create import create_archive
+from .extract import extract_archive
+from .list import list_archive_contents
+from .lock import lock_archive
+from .repair import repair_archive
+from .test import test_archive_integrity
+from .unlock import unlock_archive
+from .utils import (
+    Fore,
+    SUPPORTED_ARCHIVE_TYPES,
+    ZippyError,
+    color_text,
+    configure_logging,
+    get_logger,
+    handle_errors,
+    validate_path,
+)
+
+SCRIPT_NAME = "zippy"
+CONFIG_FILE = "zippy_config.json"
+PASSWORD_DICT_DEFAULT = "password_list.txt"
+
+
+def _format_supported_types() -> str:
+    unique_types = sorted({value for value in SUPPORTED_ARCHIVE_TYPES.values()})
+    return ", ".join(unique_types)
+
+
+def display_banner() -> None:
+    banner = f"{SCRIPT_NAME.upper()} v{__version__}"
+    print(color_text(banner, Fore.CYAN if Fore else None))
+
+
+def setup_auto_completion(flags: Iterable[str]) -> None:
+    def completer(text: str, state: int) -> Optional[str]:
+        options = [flag for flag in flags if flag.startswith(text)]
+        return options[state] if state < len(options) else None
+
+    readline.set_completer(completer)
+    readline.parse_and_bind("tab: complete")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=f"{SCRIPT_NAME.upper()} - Archive Utility Toolkit",
+    )
+    command_group = parser.add_mutually_exclusive_group(required=True)
+    command_group.add_argument(
+        "--extract",
+        "-x",
+        dest="command",
+        action="store_const",
+        const="extract",
+        help="Extract archive contents",
+    )
+    command_group.add_argument(
+        "--create",
+        "-c",
+        dest="command",
+        action="store_const",
+        const="create",
+        help="Create a new archive",
+    )
+    command_group.add_argument(
+        "--list",
+        "-l",
+        dest="command",
+        action="store_const",
+        const="list",
+        help="List archive contents",
+    )
+    command_group.add_argument(
+        "--test",
+        "-t",
+        dest="command",
+        action="store_const",
+        const="test",
+        help="Test archive integrity",
+    )
+    command_group.add_argument(
+        "--unlock",
+        "-u",
+        dest="command",
+        action="store_const",
+        const="unlock",
+        help="Attempt to unlock a password-protected ZIP",
+    )
+    command_group.add_argument(
+        "--lock",
+        dest="command",
+        action="store_const",
+        const="lock",
+        help="Create or re-lock a password-protected ZIP",
+    )
+    command_group.add_argument(
+        "--repair",
+        "-r",
+        dest="command",
+        action="store_const",
+        const="repair",
+        help="[Experimental] Attempt archive repair",
+    )
+    parser.add_argument("archive_file", nargs="?", help="Path to the archive file.")
+    parser.add_argument(
+        "-o",
+        "--output",
+        dest="output_path",
+        default=".",
+        help="Output directory for extraction (default: .)",
+    )
+    parser.add_argument(
+        "-p", "--password", dest="password", help="Password for archive operations"
+    )
+    parser.add_argument(
+        "-d",
+        "--dictionary",
+        dest="dictionary_file",
+        default=PASSWORD_DICT_DEFAULT,
+        help=f"Dictionary file for unlock attempts (default: {PASSWORD_DICT_DEFAULT})",
+    )
+    parser.add_argument(
+        "-f",
+        "--files",
+        dest="files_to_add",
+        help="Comma-separated files/directories to add",
+    )
+    parser.add_argument("--type", dest="archive_type", help="Force archive type")
+    parser.add_argument(
+        "--repair-mode",
+        dest="repair_mode",
+        default="remove_corrupted",
+        choices=["remove_corrupted", "scan_only"],
+        help="Repair mode for ZIP archives",
+    )
+    parser.add_argument("--verbose", action="store_true", help="Enable verbose logging")
+    parser.add_argument(
+        "--no-animation", action="store_true", help="Disable loading animation"
+    )
+    parser.add_argument(
+        "--save-config", dest="save_config_file", help="Save current settings to JSON"
+    )
+    parser.add_argument(
+        "--load-config", dest="load_config_file", help="Load settings from JSON"
+    )
+    parser.add_argument("--version", action="version", version=f"{SCRIPT_NAME} {__version__}")
+    return parser
+
+
+def _persist_config(args: argparse.Namespace, path: str) -> None:
+    data = vars(args).copy()
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=4)
+    get_logger(__name__).info("Configuration saved to %s", path)
+
+
+def _load_config(path: str) -> dict:
+    if not os.path.exists(path):
+        handle_errors(f"Configuration file not found: {path}")
+    with open(path, "r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    get_logger(__name__).info("Configuration loaded from %s", path)
+    return data
+
+
+def _apply_loaded_config(args: argparse.Namespace, config: dict) -> None:
+    for key, value in config.items():
+        if hasattr(args, key):
+            setattr(args, key, value)
+
+
+def _validate_archive_path(command: str, archive_path: Optional[str]) -> None:
+    if not archive_path:
+        handle_errors("Archive file path is required for this command.")
+    if command in {"extract", "list", "test", "unlock", "repair"}:
+        validate_path(archive_path, "Archive file path", must_exist=True, is_dir=False)
+    elif command in {"create", "lock"}:
+        directory = os.path.dirname(os.path.abspath(archive_path)) or "."
+        validate_path(directory, "Output directory", must_exist=True, is_dir=True)
+
+
+def _execute_command(args: argparse.Namespace) -> None:
+    command = args.command
+    archive_path = args.archive_file
+    _validate_archive_path(command, archive_path)
+
+    if command == "extract":
+        extract_archive(
+            archive_path,
+            args.output_path,
+            args.password,
+            args.verbose,
+            args.no_animation,
+        )
+    elif command == "create":
+        create_archive(
+            archive_path,
+            args.files_to_add,
+            args.archive_type,
+            args.password,
+            args.verbose,
+            args.no_animation,
+        )
+    elif command == "list":
+        list_archive_contents(archive_path, args.verbose, args.no_animation)
+    elif command == "test":
+        test_archive_integrity(
+            archive_path, args.verbose, args.no_animation, args.password
+        )
+    elif command == "unlock":
+        unlock_archive(
+            archive_path,
+            args.dictionary_file,
+            args.password,
+            args.verbose,
+            args.no_animation,
+        )
+    elif command == "lock":
+        lock_archive(
+            archive_path,
+            args.files_to_add,
+            "zip",
+            args.password,
+            args.verbose,
+            args.no_animation,
+        )
+    elif command == "repair":
+        repair_archive(
+            archive_path,
+            args.verbose,
+            args.no_animation,
+            args.repair_mode,
+            args.password,
+        )
+    else:  # pragma: no cover - defensive
+        handle_errors("Invalid command. See 'help'.")
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    load_dotenv()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    configure_logging(args.verbose)
+    command_flags = [
+        "--extract",
+        "--create",
+        "--list",
+        "--test",
+        "--unlock",
+        "--lock",
+        "--repair",
+    ]
+    setup_auto_completion(command_flags)
+
+    if args.save_config_file:
+        _persist_config(args, args.save_config_file)
+        return 0
+
+    if args.load_config_file:
+        config = _load_config(args.load_config_file)
+        _apply_loaded_config(args, config)
+
+    display_banner()
+    try:
+        _execute_command(args)
+    except ZippyError as error:
+        get_logger(__name__).error(str(error))
+        return getattr(error, "exit_code", 1)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    try:
+        sys.exit(main())
+    except ZippyError as error:
+        get_logger(__name__).error(str(error))
+        sys.exit(getattr(error, "exit_code", 1))