Huffify

Description

Huffify allows you to compress text using Huffman algorithm. Huffify focuses on flexibility - you can choose various encoders, Huffman tree nodes, and file managers to achieve the best compression quality.

Historical note: The Huffman algorithm was developed by David A. Huffman in 1952. Read more about David and his algorithm

Installation

Using pip:

pip install huffify

Using poetry:

poetry add huffify

Usage

Command Line Interface

Huffify provides a convenient command-line interface for common operations:

# Compress a file (auto-generates filename: input_a1b2c3d4.huf)
huffify compress input.txt

# Compress with custom filename (outputs: custom_name.huf)
huffify compress input.txt --filename=custom_name

# Compress to specific directory
huffify compress input.txt /path/to/output/dir

# Decompress a file (must have .huf extension)
huffify decompress compressed.huf output.txt

# View encoding table for a text
huffify table "Hello, World!"

# Run benchmarks
huffify benchmark

The CLI commands in detail:

• compress: Compresses a text file using Huffman coding

  • Automatically generates .huf files with unique identifiers
  • Shows compression statistics including original size, compressed size, and compression ratio
  • Usage:
    • Basic: huffify compress <input_file> [output_dir]
    • With custom filename: huffify compress <input_file> [output_dir] --filename=<name>
  • Examples:
    • huffify compress input.txt . → Creates input_a1b2c3d4.huf
    • huffify compress input.txt . -filename=custom → Creates custom.huf
    • huffify compress input.txt /output/dir → Creates /output/dir/input_a1b2c3d4.huf

• decompress: Decompresses a previously compressed file

  • Only accepts files with .huf extension
  • Restores the original text content
  • Usage: huffify decompress <compressed_file.huf> <output_file>

• table: Displays the Huffman encoding table for a given text

  • Shows character-to-code mappings used in compression
  • Usage: huffify table "<text>"

Python API

Basic usage:

from huffify import HuffmanCodec
from huffify.core.heap_nodes import Node, LexicographicNode
from huffify.core.encoders import MVPEncoder

# You can use LexicographicNode for idempotent results
codec = HuffmanCodec(node=Node, encoder=MVPEncoder)
message = "The sun shines bright today."

# Here is the "FinalDataSet", which can be saved as file
encoded_message = codec.encode(message)

# Also you can decode this "FinalDataSet" to get original message
decoded_message = codec.decode(encoded_message)

File operations:

from huffify import Huffify
from huffify.core.file_manager import Picklefier

# Create compressor with preferred file manager
file_compressor = Huffify(file_manager=Picklefier)

# Compress and save to file
file_compressor.save(path="output.huf", message="The sun shines bright today.")

# Load and decompress from file
decoded_message = file_compressor.load(path="output.huf")

Project Structure

Huffify/
├── src/
│   └── huffify/
│       ├── core/           # Core compression functionality
│       │   ├── codec.py    # Huffman encoding/decoding
│       │   ├── nodes.py    # Tree node implementations
│       │   ├── encoders.py # Data encoding strategies
│       │   └── file_manager.py  # File I/O operations
│       ├── presentation/   # User interfaces
│       │   ├── cli.py      # Command-line interface
│       │   └── benchmark.py # Performance testing
│       └── utils/          # Shared utilities
├── tests/                  # Test suite
├── docs/                   # Documentation
└── examples/               # Usage examples

Features

• Flexible compression with customizable components:
  • Multiple node types for tree construction
  • Pluggable encoders for different encoding strategies
  • Extensible file manager system
• Command-line interface for common operations
• Comprehensive benchmarking suite
• Type hints and documentation
• Extensive test coverage

Contributing

We welcome contributions! Please check out our Contributing Guide for guidelines on how to proceed.

License

This project is licensed under the MIT License - see the LICENSE file for details.