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

pip install gzip-txt

Quick Start

Reading a gzip-compressed text file

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

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

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:

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:

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:

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:

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