Skip to content

v0.5.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Dec 08:49
· 42 commits to main since this release
v0.5.0
c064b4c

Release Notes - v0.5.0

🚀 Major Features

International Address Parsing Support

  • New parse_auto() method: Automatically routes between US and international parsing

    • Attempts US parsing first, falls back to libpostal for international addresses
    • Smart detection of international addresses based on content analysis
    • Maintains backward compatibility with existing US parsing

  • InternationalAddress Model: New Pydantic model for structured international address components

    • Fields: HouseNumber, Road, City, State, PostalCode, Country, CountryCode
    • Compatible with libpostal's international parsing capabilities

  • Enhanced Service Methods:

    • parse_international(): Direct libpostal-based parsing
    • parse_auto(): Intelligent routing between US and international parsers
    • Automatic fallback on US validation failure

🛠️ CI/CD & Quality Improvements

Codecov Integration

  • Coverage Reporting: Automated coverage collection and upload

    • pytest-cov integration with XML and terminal output
    • Coverage badge in README showing live percentages
    • Support for all Python versions (3.9-3.13)

  • Test Analytics: Comprehensive test execution insights

    • Test failure tracking and flaky test detection
    • Performance analytics and historical trends
    • JUnit XML output with detailed test metadata

Build Optimization

  • Libpostal Caching: Dramatically improved CI build times

    • Cache libpostal installation (~5-10 min → ~10-30 sec)
    • Persistent caching across workflow runs
    • Conditional installation (rebuild only on cache miss)

  • Workflow Enhancements:

    • Protected branch support with CODECOV_TOKEN
    • Separate coverage and test analytics uploads
    • Improved error handling and resilience

🧪 Testing Enhancements

International Address Test Suite

  • Comprehensive Coverage: 40+ international address formats tested

    • European, Asian, Middle Eastern, and global address formats
    • Unicode support and special character handling
    • Complex multi-line international addresses

  • Advanced Test Cases:

    • International parsing edge cases
    • Fallback behavior validation
    • Cross-format compatibility testing

📚 Documentation & Developer Experience

README Updates

  • Codecov Badge: Live coverage percentage display
  • International Parsing Guide: Complete setup and usage instructions
  • Enhanced Examples: International address parsing demonstrations

Code Quality

  • Linting Consistency: Ruff formatting applied across codebase
  • Type Safety: Enhanced mypy coverage and error handling

🔧 Technical Details

Dependencies

  • New Optional Dependencies: libpostal integration (when available)
  • CI Dependencies: pytest-cov, codecov-cli for analytics
  • Build Dependencies: Enhanced libpostal installation scripts

Breaking Changes

  • Deprecation Notice: parse_auto_route() deprecated in favor of parse_auto()
  • Warning: Deprecation warnings added for smooth migration

Performance

  • CI Speed: 80-90% reduction in build times with caching
  • Memory: Optimized international parsing with lazy loading
  • Compatibility: Maintained across Python 3.9-3.13

🐛 Bug Fixes & Stability

International Parsing

  • Robust Fallback: Graceful degradation when libpostal unavailable
  • Error Handling: Improved validation error messages
  • Edge Cases: Better handling of malformed international addresses

CI/CD Reliability

  • Cache Management: Smart cache invalidation and rebuilding
  • Upload Resilience: Guaranteed analytics upload even on test failures
  • Cross-Platform: Consistent behavior across all supported Python versions

📈 Metrics & Analytics

Coverage Tracking

  • Baseline: 77% overall code coverage achieved
  • Breakdown: Detailed per-module coverage reporting
  • Trends: Historical coverage tracking and alerts

Test Analytics

  • Execution Times: Performance monitoring for test suites
  • Failure Patterns: Automated detection of flaky tests
  • Suite Health: Comprehensive test suite metrics

Migration Guide

For Existing Users

  1. No Action Required: All existing APIs remain functional
  2. Optional Enhancement: Use parse_auto() for international address support
  3. Deprecation: Replace parse_auto_route() with parse_auto()

For CI/CD

  1. Automatic: Codecov integration works out-of-the-box
  2. Token Required: Add CODECOV_TOKEN to repository secrets
  3. Caching: Builds automatically benefit from libpostal caching

This release significantly expands the library's capabilities for global address processing while maintaining robust CI/CD infrastructure and comprehensive testing coverage.

Assets 4
Loading