Metadata-Version: 2.1
Name: pybit7z
Version: 0.3.0
Summary: A wrapper based on bit7z.
Author-Email: "l.feng" <msclock@126.com>
License: Apache-2.0
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/msclock/pybit7z
Project-URL: Bug tracker, https://github.com/msclock/pybit7z/issues
Project-URL: Discussions, https://github.com/msclock/pybit7z/discussions
Project-URL: Changelog, https://github.com/msclock/pybit7z/releases
Requires-Python: >=3.8
Requires-Dist: typing-extensions>=3.10.0; python_version < "3.9"
Requires-Dist: importlib_metadata>=1.4
Requires-Dist: pytest>=6; extra == "test"
Requires-Dist: pytest-cov>=3; extra == "test"
Requires-Dist: pytest>=6; extra == "dev"
Requires-Dist: pytest-cov>=3; extra == "dev"
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: myst_parser>=0.13; extra == "docs"
Requires-Dist: sphinx_copybutton; extra == "docs"
Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
Requires-Dist: furo>=2023.08.17; extra == "docs"
Provides-Extra: test
Provides-Extra: dev
Provides-Extra: docs
Description-Content-Type: text/markdown

# pybit7z

<!-- SPHINX-START -->

A wrapper based on bit7z.

[![Documentation](https://img.shields.io/badge/Documentation-sphinx-blue)](https://msclock.github.io/pybit7z)
[![License](https://img.shields.io/github/license/msclock/pybit7z)](https://github.com/msclock/pybit7z/blob/master/LICENSE)
[![SS Badge](https://img.shields.io/badge/Serious%20Scaffold-pybind11-blue)](https://github.com/serious-scaffold/ss-pybind11)

[![CI](https://github.com/msclock/pybit7z/actions/workflows/ci.yml/badge.svg)](https://github.com/msclock/pybit7z/actions/workflows/ci.yml)
[![CD](https://github.com/msclock/pybit7z/actions/workflows/cd.yml/badge.svg)](https://github.com/msclock/pybit7z/actions/workflows/cd.yml)
[![Renovate](https://github.com/msclock/pybit7z/actions/workflows/renovate.yml/badge.svg)](https://github.com/msclock/pybit7z/actions/workflows/renovate.yml)
[![Semantic Release](https://github.com/msclock/pybit7z/actions/workflows/semantic-release.yml/badge.svg)](https://github.com/msclock/pybit7z/actions/workflows/semantic-release.yml)
[![codecov](https://codecov.io/gh/msclock/pybit7z/branch/master/graph/badge.svg?token=123456789)](https://codecov.io/gh/msclock/pybit7z)

[![Release](https://img.shields.io/github/v/release/msclock/pybit7z)](https://github.com/msclock/pybit7z/releases)
[![PyPI](https://img.shields.io/pypi/v/pybit7z)](https://pypi.org/project/pybit7z/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pybit7z)](https://pypi.org/project/pybit7z/)

[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![clang-format](https://img.shields.io/badge/clang--format-enabled-blue)](https://github.com/pre-commit/mirrors-clang-format)
[![cmake-format](https://img.shields.io/badge/cmake--format-enabled-blue)](https://github.com/cheshirekow/cmake-format-precommit)
[![codespell](https://img.shields.io/badge/codespell-enabled-blue)](https://github.com/codespell-project/codespell)
[![markdownlint](https://img.shields.io/badge/markdownlint-enabled-blue)](https://github.com/igorshubovych/markdownlint-cli)
[![shellcheck](https://img.shields.io/badge/shellcheck-enabled-blue)](https://github.com/shellcheck-py/shellcheck-py)

<!-- writes more things here -->

## Installation

Package-built has uploaded to pypi and just install with the command:

```bash
pip install pybit7z
```

## Example

### Extract Files from an Archive

```python
import pybit7z

try:
    extractor = pybit7z.BitFileExtractor(pybit7z.FormatSevenZip)
    extractor.extract("path/to/archive.7z", "out/dir/")

    # Extracting a specific file inside an archive
    extractor.extract_matching("path/to/archive.7z", "file.pdf", "out/dir/")

    # Extracting the first file of an archive to a buffer
    buffer: bytes = extractor.extract("path/to/archive.7z")

    # Extracting an encrypted archive
    extractor.set_password("password")
    extractor.extract("path/to/another/archive.7z", "out/dir/")
except pybit7z.BitException as e:
    ... # handle the exception
```

Work on a single archive:

```python
import pybit7z

try:
    # Opening the archive
     archive = pybit7z.BitArchiveReader("path/to/archive.gz", pybit7z.FormatGZip)

    # Testing the archive
    archive.test()

    # Extracting the archive
    archive.extract_to("out/dir/")
except pybit7z.BitException as e:
    ... # handle the exception
```

### Compress Files into an Archive

```python
import pybit7z

try:
    compressor = pybit7z.BitFileCompressor(pybit7z.FormatSevenZip)

    files = ["path/to/file1.jpg", "path/to/file2.pdf"]

    # Creating a simple zip archive
    compressor.compress(files, "output_archive.zip")

    # Creating a zip archive with a custom directory structure
    files_map: dict[str, str] = {
        "path/to/file1.jpg": "alias/path/file1.jpg",
        "path/to/file2.pdf": "alias/path/file2.pdf"
    }
    compressor.compress(files_map, "output_archive2.zip")

    # Compressing a directory
    compressor.compress_directory("dir/path/", "dir_archive.zip")

    # Creating an encrypted zip archive of two files
    compressor.set_password("password")
    compressor.compress_files(files, "protected_archive.zip")

    # Updating an existing zip archive
    compressor.set_update_mode(pybit7z.UpdateMode.Append)
    compressor.compress_files(files, "existing_archive.zip")

    # Compressing a single file into a buffer
    compressor2 = pybit7z.BitFileCompressor(pybit7z.FormatBZip2)
    buffer: bytes = compressor2.compress_file(files[0])
except pybit7z.BitException as e:
    ... # handle the exception
```

Work on a single archive:

```python
import pybit7z

try:
    archive = pybit7z.BitArchiveWriter(pybit7z.FormatSevenZip)

    # Adding the items to be compressed (no compression is performed here)
    archive.add_file("path/to/file.txt")
    archive.add_directory("path/to/dir/")

    # Compressing the added items to the output archive
    archive.compress_to("output.7z")
except pybit7z.BitException as e:
    ... # handle the exception
```

### Read Archive Metadata

```python
import pybit7z

try:
    arc = pybit7z.BitArchiveReader("archive.7z", pybit7z.FormatSevenZip)

    # Printing archive metadata
    print("Archive properties:",
        "\n  Items count: "   , arc.items_count()
        "\n  Folders count: " , arc.folders_count()
        "\n  Files count: "   , arc.files_count()
        "\n  Size: "          , arc.size()
        "\n  Packed size: "   , arc.pack_size())

    # Printing the metadata of the archived items
    print("Archived items")
    for item in arc:
        print("    Item index: "    , item.index(),
            "\n    Name: "          , item.name(),
            "\n    Extension: "     , item.extension(),
            "\n    Path: "          , item.path(),
            "\n    IsDir: "         , item.is_dir(),
            "\n    Size: "          , item.size(),
            "\n    Packed size: "   , item.pack_size(),
            "\n    CRC: "           , item.crc())
except pybit7z.BitException as e:
    ... # handle the exception
```

A complete API reference is available in the [documentation](https://msclock.github.io/pybit7z/api/).


## License

Apache Software License, for more details, see the [LICENSE](https://github.com/msclock/pybit7z/blob/master/LICENSE) file.
