Metadata-Version: 2.2
Name: py-stream-zip
Version: 0.1.0
Summary: A stream-based ZIP file extractor in Python, inspired by node-stream-zip.
Author: Your Name
Author-email: David Bald <baldhumanity@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Your Name
        
        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/baldhumanity/py-stream-zip
Project-URL: Repository, https://github.com/baldhumanity/py-stream-zip
Project-URL: Credits, https://github.com/antelle/node-stream-zip
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: requires-python

# py-stream-zip

**py-stream-zip** is a Python library for extracting ZIP files using a stream-based approach. It provides efficient access to ZIP file entries without needing to load the entire file into memory. This package is inspired by and gives credit to [node-stream-zip](https://github.com/antelle/node-stream-zip).

## Features

- Stream-based extraction of ZIP files.
- Reads the central directory and processes entries on the fly.
- Simple, synchronous API for ease of integration.


## Installation

You can install **py-stream-zip** using pip:

```bash
pip install py-stream-zip
```

## Usage

Below is an example demonstrating how to extract a file from a ZIP archive:

```python
from py_stream_zip import StreamZip

zip_path = "path/to/archive.zip"
entry_name = "document.txt"  # The name of the file inside the ZIP

# Create a StreamZip instance (ensuring entries are stored for random access)
zip_archive = StreamZip(zip_path, store_entries=True)

try:
    # Extract and read the content of the specified entry.
    data = zip_archive.entry_data_sync(entry_name)
    print(data.decode("utf-8"))

    # or save to file as binary
    with open("document.txt", "wb") as f:
        f.write(data)

except Exception as ex:
    print(f"Error processing the ZIP file: {ex}")
finally:
    # Always close the archive to free the file handle.
    zip_archive.close()
```

For further reference, check out the provided [test_unzip.py](test_unzip.py) for a complete working example.

## Credits

**py-stream-zip** is inspired by [node-stream-zip](https://github.com/antelle/node-stream-zip). Special thanks to its developers for their contributions to the streaming ZIP extraction technique.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
