feat: Add partial address validation with component cleaning

Add support for partial address validation where optional components like Zip4
can be cleaned/removed while keeping addresses valid. This prevents entire
address parsing from failing due to invalid optional fields.

Key changes:
- Add CleaningOperation dataclass to track cleaning operations
- Extend ParseResult with cleaning tracking fields and methods
- Add allow_partial parameter to parse_auto() functions
- Add component-level validation functions (validate_zip5, validate_zip4)
- Implement partial validation logic that cleans invalid optional components
- Add comprehensive test coverage for partial validation behavior
- Update ruff config for Python 3.9 type annotation compatibility

Addresses issue where addresses with invalid optional components (like malformed
Zip4) would fail completely. Now such components are cleaned and tracked,
allowing the address to remain valid with proper reporting.

BREAKING: parse_auto() now accepts allow_partial=False by default for backward compatibility
FEATURE: New allow_partial=True enables cleaning of invalid optional components
FEATURE: Cleaning operations are tracked with timestamps and reasons
FEATURE: Enhanced ParseResult with cleaning report methods

Author: github-actions

pyproject.toml

@@ -86,6 +86,7 @@ version_variables = [
 select = ["E", "F", "I", "UP", "B", "SIM"]
 ignore = [
     "UP007",  # Use X | Y - not compatible with Pydantic on Python 3.9
+    "UP045",  # Use X | None - not compatible with typer on Python 3.9
 ]
 
 [tool.mypy]

src/ryandata_address_utils/__init__.py

@@ -54,6 +54,7 @@
     Address,
     AddressBuilder,
     AddressField,
+    CleaningOperation,
     ParseResult,
     RyanDataAddressError,
     RyanDataValidationError,
@@ -85,6 +86,8 @@
     CompositeValidator,
     StateValidator,
     ZipCodeValidator,
+    validate_zip4,
+    validate_zip5,
 )
 
 __version__ = "0.5.0"
@@ -104,6 +107,7 @@
     "AddressBuilder",
     "AddressField",
     "ADDRESS_FIELDS",
+    "CleaningOperation",
     "ParseResult",
     "RyanDataAddressError",
     "RyanDataValidationError",
@@ -127,6 +131,8 @@
     "CompositeValidator",
     "StateValidator",
     "ZipCodeValidator",
+    "validate_zip4",
+    "validate_zip5",
     # Convenience functions
     "get_zip_info",
     "is_valid_zip",

src/ryandata_address_utils/models.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+from collections import Counter
 from dataclasses import dataclass, field
+from datetime import datetime
 from enum import Enum
-from typing import Union
+from typing import Any, Union
 
 from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
 from pydantic_core import PydanticCustomError
@@ -670,6 +672,19 @@ class ValidationError:
     value: str | None = None
 
 
+@dataclass
+class CleaningOperation:
+    """Record of a component cleaning operation.
+
+    Tracks when an address component was cleaned/removed during partial validation.
+    """
+
+    component: str
+    original_value: str | None
+    reason: str
+    timestamp: str  # ISO format
+
+
 @dataclass
 class ValidationResult:
     """Result of address validation."""
@@ -692,7 +707,10 @@ def merge(self, other: ValidationResult) -> ValidationResult:
 
 @dataclass
 class ParseResult:
-    """Result of address parsing."""
+    """Result of address parsing.
+
+    Extended to support partial validation with component-level cleaning tracking.
+    """
 
     raw_input: str
     address: Address | None = None
@@ -701,6 +719,10 @@ class ParseResult:
     validation: ValidationResult | None = None
     source: str | None = None  # "us" or "international"
     is_international: bool | None = None
+    # Partial validation tracking fields
+    cleaned_components: dict[str, Any] = field(default_factory=dict)
+    invalid_components: dict[str, dict[str, Any]] = field(default_factory=dict)
+    cleaning_operations: list[CleaningOperation] = field(default_factory=list)
 
     @property
     def is_valid(self) -> bool:
@@ -729,6 +751,57 @@ def to_dict(self) -> dict[str, str | None]:
             return self.address.to_dict()
         return {f: None for f in ADDRESS_FIELDS}
 
+    def add_cleaning_operation(
+        self, component: str, original_value: Any, reason: str
+    ) -> None:
+        """Track a cleaning operation performed during partial validation.
+
+        Args:
+            component: Name of the address component that was cleaned.
+            original_value: The original value before cleaning.
+            reason: Explanation of why the component was cleaned.
+        """
+        self.cleaning_operations.append(
+            CleaningOperation(
+                component=component,
+                original_value=original_value,
+                reason=reason,
+                timestamp=datetime.now().isoformat(),
+            )
+        )
+
+    def has_cleaning_operations(self) -> bool:
+        """Check if any components were cleaned during partial validation.
+
+        Returns:
+            True if any cleaning operations were performed.
+        """
+        return len(self.cleaning_operations) > 0
+
+    def get_cleaning_report(self) -> list[dict[str, Any]]:
+        """Get cleaning operations as a list of dictionaries for export.
+
+        Returns:
+            List of dictionaries with cleaning operation details.
+        """
+        return [
+            {
+                "component": op.component,
+                "original_value": op.original_value,
+                "reason": op.reason,
+                "timestamp": op.timestamp,
+            }
+            for op in self.cleaning_operations
+        ]
+
+    def get_cleaning_summary(self) -> dict[str, int]:
+        """Get summary counts of cleaning operations by component type.
+
+        Returns:
+            Dictionary mapping component names to count of cleaning operations.
+        """
+        return dict(Counter(op.component for op in self.cleaning_operations))
+
 
 class AddressBuilder:
     """Builder for programmatic Address construction.