formatparse 0.6.1

Parse strings using a specification based on the Python format() syntax (Rust implementation)

formatparse

A high-performance, Rust-backed implementation of the parse library for Python. formatparse provides the same API as the original parse library but with significant performance improvements (up to 80x faster) thanks to Rust's zero-cost abstractions and optimized regex engine.

📖 Documentation

Full documentation is available at https://formatparse.readthedocs.io/

The documentation includes:

• Getting Started Guide - Quick introduction and basic usage
• User Guides - Comprehensive guides on patterns, datetime parsing, custom types, and bidirectional patterns
• API Reference - Complete API documentation for all functions and classes
• Examples & Cookbook - Practical examples and common use cases

Features

• 🚀 Blazing Fast: Up to 80x faster than the original Python implementation
• 🔄 Drop-in Replacement: Compatible API with the original parse library
• 🎯 Type-Safe: Rust backend ensures reliability and correctness
• 🔍 Advanced Pattern Matching: Support for named fields, positional fields, and custom types
• 📅 DateTime Parsing: Built-in support for various datetime formats (ISO 8601, RFC 2822, HTTP dates, etc.)
• 🎨 Flexible: Case-sensitive and case-insensitive matching options
• 💾 Optimized: Pattern caching, lazy evaluation, and batch operations for maximum performance

Installation

From PyPI

pip install formatparse

From Source

# Clone the repository
git clone https://github.com/eddiethedean/formatparse.git
cd formatparse

# Install maturin (build tool)
pip install maturin

# Build and install in development mode
maturin develop --manifest-path formatparse-pyo3/Cargo.toml --release

Quick Start

from formatparse import parse, search, findall

# Basic parsing with named fields
result = parse("{name}: {age:d}", "Alice: 30")
print(result.named['name'])  # 'Alice'
print(result.named['age'])   # 30

# Search for patterns in text
result = search("age: {age:d}", "Name: Alice, age: 30, City: NYC")
if result:
    print(result.named['age'])  # 30

# Find all matches
results = findall("ID:{id:d}", "ID:1 ID:2 ID:3")
for result in results:
    print(result.named['id'])
# Output: 1, 2, 3

For more examples and detailed usage, see the documentation.

Performance

formatparse is significantly faster than the original Python parse library, with speedups ranging from 3x to 80x depending on the use case. The Rust backend provides:

• Pattern caching to eliminate regex compilation overhead
• Optimized type conversion paths for common types
• Efficient memory management with pre-allocated data structures
• Reduced Python GIL overhead through batched operations

For detailed benchmark results and performance analysis, see the documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For detailed contribution guidelines, including testing requirements and development setup, see CONTRIBUTING.md.

Testing

The project includes comprehensive test coverage:

• Unit Tests: ~436 Python tests + 50 Rust tests
• Property-Based Tests: 32 Hypothesis-based tests
• Performance Benchmarks: Automated regression testing
• Stress Tests: Large input and scalability testing
• Fuzz Tests: Crash-free input testing
• Coverage: >90% code coverage target

Run tests with:

# All tests
pytest tests/

# With coverage
pytest tests/ --cov=formatparse --cov-report=html

# Benchmarks
pytest tests/test_performance.py --benchmark-only

See CONTRIBUTING.md for more testing information.

License

MIT License - see LICENSE file for details

Credits

Based on the parse library by Richard Jones.