gzip-txt 1.0.0
A Python library for reading and writing gzip-compressed text files
License: MIT
Requires Python: >=3.10

# gzip-txt

A lightweight Python library for reading and writing gzip-compressed text files with UTF-8 encoding.

## Features

- **Simple API**: Two static methods (`read` and `write`) for all operations
- **UTF-8 encoding**: Automatic handling of UTF-8 encoding for international characters
- **Flexible writing**: Supports writing strings or iterables of strings
- **Type safety**: Supports both `str` and `Path` objects for file paths
- **Error handling**: Comprehensive exception hierarchy for precise error handling
- **Zero dependencies**: Uses only Python standard library (gzip)

## Installation

```bash
pip install gzip-txt
```

## Quick Start

### Reading a gzip-compressed text file

```python
from gzip_txt import GzipTxt

# Read a gzip-compressed text file
content = GzipTxt.read("data.txt.gz")

# content is a string
print(content)
```

### Writing to a gzip-compressed text file

```python
from gzip_txt import GzipTxt

# Write a string to a gzip-compressed text file
GzipTxt.write("output.txt.gz", "Hello, World!")

# Write multiple lines from an iterable
lines = ["Line 1", "Line 2", "Line 3"]
GzipTxt.write("output.txt.gz", lines)
```

### Using Path objects

```python
from pathlib import Path
from gzip_txt import GzipTxt

# Both str and Path objects are supported
path = Path("data.txt.gz")
content = GzipTxt.read(path)

GzipTxt.write(Path("output.txt.gz"), "Example text")
```

## API Reference

### GzipTxt

Main utility class for reading and writing gzip-compressed text files. All methods are static.

#### `GzipTxt.read(path)`

Read a gzip-compressed text file.

**Parameters:**

- `path` (str | Path): Path to the gzip-compressed text file.

**Returns:**

- str: Text content as a string.

**Raises:**

- `GzipTxtReadError`: If reading fails due to:
  - File not found
  - Invalid gzip format
  - Encoding errors
  - I/O errors

**Example:**

```python
from gzip_txt import GzipTxt

content = GzipTxt.read("data.txt.gz")
```

#### `GzipTxt.write(path, content)`

Write content to a gzip-compressed text file.

The file is written with UTF-8 encoding. If content is a string, it is written as-is. If content is an iterable of strings, each string is written as a line (no newline is added automatically).

**Parameters:**

- `path` (str | Path): Path to the output file.
- `content` (str | Iterable[str]): Text content to write. Can be:
  - A string: written as-is
  - An iterable of strings: each string is written as a line

**Raises:**

- `GzipTxtWriteError`: If writing fails due to:
  - Permission denied
  - Disk space issues
  - I/O errors
- `TypeError`: If content is not a string or iterable of strings.

**Example:**

```python
from gzip_txt import GzipTxt

# Write a string
GzipTxt.write("output.txt.gz", "Hello, World!")

# Write multiple lines
lines = ["Line 1", "Line 2", "Line 3"]
GzipTxt.write("output.txt.gz", lines)
```

### Exceptions

#### `GzipTxtError`

Base exception class for all gzip-txt related errors.

**Attributes:**

- `message`: Primary error message (required)
- `file_path`: Path to the file that caused the error (optional)

#### `GzipTxtReadError`

Raised when reading a gzip-compressed text file fails.

This exception indicates that an error occurred during the read operation, such as file not found, invalid gzip format, encoding errors, or I/O errors.

**Attributes:**

- `message`: Human-readable error message describing the issue
- `file_path`: Path to the file that caused the error (optional)

**Example:**

```python
from gzip_txt import GzipTxt, GzipTxtReadError

try:
    content = GzipTxt.read("nonexistent.txt.gz")
except GzipTxtReadError as e:
    print(f"Error reading file: {e.message}")
    print(f"File path: {e.file_path}")
```

#### `GzipTxtWriteError`

Raised when writing a gzip-compressed text file fails.

This exception indicates that an error occurred during the write operation, such as permission denied, disk space issues, or I/O errors.

**Attributes:**

- `message`: Human-readable error message describing the issue
- `file_path`: Path to the file that caused the error (optional)

**Example:**

```python
from gzip_txt import GzipTxt, GzipTxtWriteError

try:
    GzipTxt.write("/readonly/output.txt.gz", "Hello, World!")
except GzipTxtWriteError as e:
    print(f"Error writing file: {e.message}")
    print(f"File path: {e.file_path}")
```

## Requirements

- Python >= 3.10

No external dependencies required. This package uses only Python standard library modules (`gzip`).

## License

MIT License