resolvekit 0.0.1__py3-none-any.whl

resolvekit/utils/README.md

@@ -0,0 +1,188 @@
+# Utils Module
+
+## Purpose
+
+The utils module contains shared utilities, helpers, and common functionality used across other modules.
+
+## Components
+
+### Core Utilities
+
+1. **Logging** (`logging.py`)
+   - Structured logging configuration
+   - Log levels and formatters
+   - Privacy-aware logging (no query content by default)
+
+2. **Validation** (`validation.py`)
+   - Input validation utilities
+   - Schema validation
+   - Error message generation
+
+3. **Text Utils** (`text.py`)
+   - Common text processing functions
+   - Unicode utilities
+   - String similarity metrics
+
+4. **Date Utils** (`dates.py`)
+   - Date parsing and formatting
+   - Temporal validity checks
+   - ISO date utilities
+
+5. **File Utils** (`files.py`)
+   - File I/O helpers
+   - Path management
+   - Checksum computation
+
+6. **Cache** (`cache.py`)
+   - LRU cache implementations
+   - Cache warming strategies
+   - Cache invalidation
+
+### Data Structures
+
+- `priority_queue.py`: Priority queue for candidate ranking
+- `trie.py`: Trie for prefix matching
+- `bloom_filter.py`: Bloom filter for quick existence checks
+
+### Error Classes
+
+```python
+# errors.py
+
+class ResolvekitError(Exception):
+    """Base exception for resolvekit."""
+    pass
+
+class ConfigError(ResolvekitError):
+    """Configuration error."""
+    pass
+
+class DataPackError(ResolvekitError):
+    """Data pack error."""
+    pass
+
+class ResolutionError(ResolvekitError):
+    """Resolution error."""
+    pass
+
+class ValidationError(ResolvekitError):
+    """Validation error."""
+    pass
+```
+
+### Metrics and Performance
+
+- `metrics.py`: Performance metrics collection
+- `profiling.py`: Profiling utilities
+- `benchmarks.py`: Benchmark utilities
+
+### Testing Utilities
+
+- `test_helpers.py`: Test fixtures and helpers
+- `mock_data.py`: Mock data generators
+- `assertions.py`: Custom assertions
+
+## Common Patterns
+
+### Logging
+
+```python
+from resolvekit.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("Resolver initialized", extra={
+    "data_pack_version": "1.2.0",
+    "overlays": 2
+})
+
+logger.debug("Candidate generation", extra={
+    "query": "[REDACTED]",  # Privacy
+    "candidates_found": 5,
+    "stage": "fts"
+})
+```
+
+### Validation
+
+```python
+from resolvekit.utils.validation import validate_dcid, validate_date
+
+# Validate DCID format
+if not validate_dcid(dcid):
+    raise ValidationError(f"Invalid DCID format: {dcid}")
+
+# Validate date
+try:
+    date_obj = validate_date(date_str)
+except ValidationError as e:
+    logger.error(f"Invalid date: {e}")
+```
+
+### Caching
+
+```python
+from resolvekit.utils.cache import lru_cache
+
+@lru_cache(maxsize=10000)
+def expensive_lookup(key: str) -> Entity | None:
+    """Cached entity lookup."""
+    return database.get_entity(key)
+```
+
+### Text Similarity
+
+```python
+from resolvekit.utils.text import (
+    edit_distance,
+    trigram_similarity,
+    jaccard_similarity
+)
+
+# Compute similarities
+edit_dist = edit_distance("france", "frence")  # 1
+trigram_sim = trigram_similarity("germany", "germeny")  # 0.85
+jaccard_sim = jaccard_similarity("turkey", "türkiye")  # 0.71
+```
+
+### Date Handling
+
+```python
+from resolvekit.utils.dates import parse_date, is_valid_at
+from datetime import date
+
+# Parse various date formats
+d = parse_date("2025-01-01")  # ISO
+d = parse_date("2025-1-1")    # Flexible
+d = parse_date("01/01/2025")  # US format
+
+# Check validity
+entity = get_entity("country/YUG")  # Yugoslavia
+is_valid = is_valid_at(entity, date(1990, 1, 1))  # True
+is_valid = is_valid_at(entity, date(2000, 1, 1))  # False (dissolved)
+```
+
+### Checksums
+
+```python
+from resolvekit.utils.files import compute_checksum, verify_checksum
+
+# Compute SHA-256 checksum
+checksum = compute_checksum("base.sqlite")
+
+# Verify checksum
+if not verify_checksum("base.sqlite", expected_checksum):
+    raise DataPackError("Checksum mismatch - data may be corrupted")
+```
+
+## Design Principles
+
+1. **DRY**: Shared code lives here, not duplicated
+2. **Type-safe**: Full type annotations
+3. **Tested**: High test coverage for utilities
+4. **Documented**: Clear docstrings with examples
+
+## Implementation Priority
+
+**Phase A** - Core utilities (logging, validation, text, dates)
+**Ongoing** - Add utilities as needed by other modules

resolvekit/utils/__init__.py

@@ -0,0 +1,48 @@
+"""Utilities module for resolvekit.
+
+For most utilities, import directly from submodules:
+    from resolvekit.utils.text import normalize_unicode
+    from resolvekit.utils.dates import parse_date
+    from resolvekit.utils.validation import validate_dcid
+
+This module only re-exports commonly used items for convenience.
+"""
+
+# Re-export error classes (used throughout codebase)
+from resolvekit.utils.errors import (
+    AmbiguousQueryError,
+    CalibrationError,
+    ChecksumMismatchError,
+    CodeFormatError,
+    ConfigError,
+    DatabaseError,
+    DataPackError,
+    EntityNotFoundError,
+    ExtractionError,
+    HierarchyError,
+    IncompatibleVersionError,
+    ResolvekitError,
+    OverlayError,
+    ResolutionError,
+    TemporalValidityError,
+    ValidationError,
+)
+
+__all__ = [
+    "AmbiguousQueryError",
+    "CalibrationError",
+    "ChecksumMismatchError",
+    "CodeFormatError",
+    "ConfigError",
+    "DataPackError",
+    "DatabaseError",
+    "EntityNotFoundError",
+    "ExtractionError",
+    "HierarchyError",
+    "IncompatibleVersionError",
+    "ResolvekitError",
+    "OverlayError",
+    "ResolutionError",
+    "TemporalValidityError",
+    "ValidationError",
+]

resolvekit/utils/cache.py

@@ -0,0 +1,109 @@
+"""Caching utilities for resolvekit.
+
+This module provides thin wrappers and utilities around Python's standard
+library caching mechanisms. We use functools.lru_cache for function memoization
+and simple dicts for data caching.
+"""
+
+from collections.abc import Callable, Hashable
+from functools import lru_cache as _stdlib_lru_cache
+from typing import Any
+
+# Re-export standard library lru_cache
+lru_cache = _stdlib_lru_cache
+
+__all__ = ["DictCache", "lru_cache", "warm_cache"]
+
+
+class DictCache:
+    """
+    Simple dictionary-based cache for pre-loaded data.
+
+    This is just a thin wrapper around a dict for semantic clarity
+    when caching entities, codes, etc. For most cases, a plain dict is fine.
+
+    Use this when:
+    - You need to cache a known set of data at startup
+    - You want semantic distinction between "cache" and "dict"
+    - You need simple get/set operations with a clear intent
+    """
+
+    def __init__(self, name: str = "cache"):
+        """
+        Initialize dictionary cache.
+
+        Args:
+            name: Cache name for identification
+        """
+        self.name = name
+        self._data: dict[Hashable, Any] = {}
+
+    def load(self, data: dict[Hashable, Any]) -> None:
+        """
+        Load data into cache.
+
+        Args:
+            data: Dictionary of data to cache
+        """
+        self._data = data.copy()
+
+    def get(self, key: Hashable, default: Any = None) -> Any:
+        """Get value from cache."""
+        return self._data.get(key, default)
+
+    def get_many(self, keys: list[Hashable]) -> dict[Hashable, Any]:
+        """Get multiple values from cache."""
+        return {key: self._data[key] for key in keys if key in self._data}
+
+    def set(self, key: Hashable, value: Any) -> None:
+        """Set value in cache."""
+        self._data[key] = value
+
+    def update(self, data: dict[Hashable, Any]) -> None:
+        """Update cache with new data."""
+        self._data.update(data)
+
+    def clear(self) -> None:
+        """Clear all cached data."""
+        self._data.clear()
+
+    def __contains__(self, key: Hashable) -> bool:
+        """Check if key is in cache."""
+        return key in self._data
+
+    def __len__(self) -> int:
+        """Get number of cached items."""
+        return len(self._data)
+
+    def __getitem__(self, key: Hashable) -> Any:
+        """Get item using bracket notation."""
+        return self._data[key]
+
+    def __setitem__(self, key: Hashable, value: Any) -> None:
+        """Set item using bracket notation."""
+        self._data[key] = value
+
+
+def warm_cache(
+    cache: DictCache | dict,
+    loader: Callable[[], dict[Hashable, Any]],
+) -> None:
+    """
+    Warm a cache by loading data.
+
+    Args:
+        cache: Cache to warm (DictCache or plain dict)
+        loader: Function that returns data dictionary
+
+    Example:
+        >>> entity_cache = {}
+        >>> warm_cache(entity_cache, lambda: load_entities_from_db())
+    """
+    data = loader()
+
+    if isinstance(cache, DictCache):
+        cache.load(data)
+    elif isinstance(cache, dict):
+        cache.update(data)
+    else:
+        raise TypeError(f"Unsupported cache type: {type(cache)}")

resolvekit/utils/dates.py

@@ -0,0 +1,339 @@
+"""Date and temporal utilities for resolvekit.
+
+Date parsing powered by python-dateutil for robust format handling.
+"""
+
+from datetime import date, datetime
+from typing import Any
+
+from dateutil import parser as dateutil_parser
+
+from resolvekit.utils.errors import ValidationError
+
+
+def parse_date(date_input: str | date | datetime | None) -> date | None:
+    """
+    Parse various date formats to date object.
+
+    Powered by python-dateutil for robust parsing of many formats:
+    - ISO format: "2025-01-01"
+    - Flexible: "2025-1-1", "Jan 1, 2025", "1st January 2025"
+    - Various formats: "01/02/2025", "2025/01/01", "20250101"
+
+    Args:
+        date_input: Date as string, date, datetime, or None
+
+    Returns:
+        date object or None
+
+    Raises:
+        ValidationError: If date string cannot be parsed
+
+    Examples:
+        >>> parse_date("2025-01-01")
+        date(2025, 1, 1)
+        >>> parse_date("Jan 1, 2025")
+        date(2025, 1, 1)
+        >>> parse_date("2025-1-1")
+        date(2025, 1, 1)
+        >>> parse_date(None)
+        None
+    """
+    if date_input is None:
+        return None
+
+    if isinstance(date_input, date):
+        return date_input
+
+    if isinstance(date_input, datetime):
+        return date_input.date()
+
+    if isinstance(date_input, str):
+        try:
+            # Use dateutil for robust parsing
+            # dayfirst=False prefers MM/DD/YYYY (US format) for ambiguous dates
+            parsed = dateutil_parser.parse(date_input, dayfirst=False)
+            return parsed.date()
+        except (ValueError, TypeError, dateutil_parser.ParserError) as e:
+            raise ValidationError(
+                f"Invalid date format: '{date_input}'. Could not parse date string.",
+                details={"date_input": date_input, "error": str(e)},
+            ) from e
+
+    raise ValidationError(
+        f"Invalid date type: {type(date_input).__name__}",
+        details={"type": type(date_input).__name__},
+    )
+
+
+def format_date(d: date | None, format_str: str = "%Y-%m-%d") -> str | None:
+    """
+    Format date object to string.
+
+    Args:
+        d: Date object or None
+        format_str: Format string (default: ISO format)
+
+    Returns:
+        Formatted date string or None
+
+    Examples:
+        >>> from datetime import date
+        >>> format_date(date(2025, 1, 1))
+        '2025-01-01'
+    """
+    if d is None:
+        return None
+    return d.strftime(format_str)
+
+
+def is_valid_at(
+    as_of: date,
+    valid_from: date | None = None,
+    valid_until: date | None = None,
+) -> bool:
+    """
+    Check if entity/membership is valid at a given date.
+
+    Args:
+        as_of: Date to check validity at
+        valid_from: Start of validity period (inclusive), None = always valid from past
+        valid_until: End of validity period (exclusive), None = still valid
+
+    Returns:
+        True if valid at the given date
+
+    Examples:
+        >>> from datetime import date
+        >>> is_valid_at(date(2020, 1, 1), date(2019, 1, 1), date(2021, 1, 1))
+        True
+        >>> is_valid_at(date(2022, 1, 1), date(2019, 1, 1), date(2021, 1, 1))
+        False
+    """
+    # Check valid_from (inclusive)
+    if valid_from is not None and as_of < valid_from:
+        return False
+
+    # Check valid_until (exclusive)
+    return not (valid_until is not None and as_of >= valid_until)
+
+
+def get_current_date() -> date:
+    """
+    Get current date.
+
+    Returns:
+        Today's date
+    """
+    return date.today()
+
+
+def parse_year(year_input: str | int) -> int:
+    """
+    Parse year from string or int.
+
+    Args:
+        year_input: Year as string or int
+
+    Returns:
+        Year as integer
+
+    Raises:
+        ValidationError: If year is invalid
+
+    Examples:
+        >>> parse_year("2025")
+        2025
+        >>> parse_year(2025)
+        2025
+    """
+    try:
+        year = int(year_input)
+        if year < 1000 or year > 9999:
+            raise ValidationError(
+                f"Year out of range: {year}. Expected 1000-9999",
+                details={"year": year},
+            )
+        return year
+    except (ValueError, TypeError) as e:
+        raise ValidationError(
+            f"Invalid year: {year_input}",
+            details={"year_input": year_input, "error": str(e)},
+        ) from e
+
+
+def date_range(start: date, end: date) -> list[date]:
+    """
+    Generate list of dates between start and end (inclusive).
+
+    Args:
+        start: Start date
+        end: End date
+
+    Returns:
+        List of dates
+
+    Examples:
+        >>> from datetime import date, timedelta
+        >>> dates = date_range(date(2025, 1, 1), date(2025, 1, 3))
+        >>> len(dates)
+        3
+    """
+    from datetime import timedelta
+
+    if start > end:
+        return []
+
+    dates = []
+    current = start
+    while current <= end:
+        dates.append(current)
+        current += timedelta(days=1)
+
+    return dates
+
+
+def years_between(start: date, end: date) -> int:
+    """
+    Calculate number of years between two dates.
+
+    Args:
+        start: Start date
+        end: End date
+
+    Returns:
+        Number of years (approximate)
+
+    Examples:
+        >>> from datetime import date
+        >>> years_between(date(2020, 1, 1), date(2025, 1, 1))
+        5
+    """
+    return (end - start).days // 365
+
+
+def get_validity_status(
+    as_of: date | None = None,
+    valid_from: date | None = None,
+    valid_until: date | None = None,
+) -> str:
+    """
+    Get human-readable validity status.
+
+    Args:
+        as_of: Date to check (default: today)
+        valid_from: Start of validity
+        valid_until: End of validity
+
+    Returns:
+        Status string: "current", "historical", "future", or "always"
+
+    Examples:
+        >>> from datetime import date
+        >>> get_validity_status(date(2025, 1, 1), date(2020, 1, 1), date(2030, 1, 1))
+        'current'
+    """
+    if as_of is None:
+        as_of = get_current_date()
+
+    if valid_from is None and valid_until is None:
+        return "always"
+
+    if valid_from and as_of < valid_from:
+        return "future"
+
+    if valid_until and as_of >= valid_until:
+        return "historical"
+
+    return "current"
+
+
+def compare_dates(d1: date | None, d2: date | None) -> int:
+    """
+    Compare two dates.
+
+    Args:
+        d1: First date (None is treated as negative infinity)
+        d2: Second date (None is treated as negative infinity)
+
+    Returns:
+        -1 if d1 < d2, 0 if equal, 1 if d1 > d2
+
+    Examples:
+        >>> from datetime import date
+        >>> compare_dates(date(2025, 1, 1), date(2024, 1, 1))
+        1
+        >>> compare_dates(None, date(2024, 1, 1))
+        -1
+    """
+    if d1 is None and d2 is None:
+        return 0
+    if d1 is None:
+        return -1
+    if d2 is None:
+        return 1
+
+    if d1 < d2:
+        return -1
+    elif d1 > d2:
+        return 1
+    else:
+        return 0
+
+
+def temporal_overlap(
+    range1_start: date | None,
+    range1_end: date | None,
+    range2_start: date | None,
+    range2_end: date | None,
+) -> bool:
+    """
+    Check if two temporal ranges overlap.
+
+    Args:
+        range1_start: Start of first range (inclusive)
+        range1_end: End of first range (exclusive)
+        range2_start: Start of second range (inclusive)
+        range2_end: End of second range (exclusive)
+
+    Returns:
+        True if ranges overlap
+
+    Examples:
+        >>> from datetime import date
+        >>> temporal_overlap(date(2020, 1, 1), date(2021, 1, 1),
+        ...                  date(2020, 6, 1), date(2021, 6, 1))
+        True
+        >>> temporal_overlap(date(2020, 1, 1), date(2021, 1, 1),
+        ...                  date(2021, 1, 1), date(2022, 1, 1))
+        False  # Exclusive end
+    """
+    # Convert None to infinities for comparison
+    # None for start means beginning of time (very old date)
+    # None for end means end of time (very future date)
+    min_date = date(1000, 1, 1)
+    max_date = date(9999, 12, 31)
+
+    start1 = range1_start if range1_start is not None else min_date
+    end1 = range1_end if range1_end is not None else max_date
+    start2 = range2_start if range2_start is not None else min_date
+    end2 = range2_end if range2_end is not None else max_date
+
+    # Ranges overlap if one starts before the other ends
+    return start1 < end2 and start2 < end1
+
+
+def get_date_or_none(value: Any) -> date | None:
+    """
+    Safely convert value to date or None.
+
+    Args:
+        value: Value to convert
+
+    Returns:
+        date object or None (never raises)
+    """
+    try:
+        return parse_date(value)
+    except (ValidationError, ValueError, TypeError):
+        return None