resolvekit 0.0.1__py3-none-any.whl

resolvekit/utils/validation.py

@@ -0,0 +1,301 @@
+"""Validation utilities for resolvekit."""
+
+import re
+from datetime import date
+from typing import Any
+
+from resolvekit.constants import CODE_SYSTEMS
+from resolvekit.types import AliasType, EntityType
+from resolvekit.utils.errors import CodeFormatError, ValidationError
+
+
+def validate_dcid(dcid: str) -> bool:
+    """
+    Validate DCID format.
+
+    Args:
+        dcid: DCID to validate
+
+    Returns:
+        True if valid, False otherwise
+
+    Examples:
+        >>> validate_dcid("country/USA")
+        True
+        >>> validate_dcid("invalid")
+        False
+    """
+    if not dcid or not isinstance(dcid, str):
+        return False
+
+    pattern = CODE_SYSTEMS["dcid"]["format"]
+    return bool(re.match(pattern, dcid))
+
+
+def validate_code_format(code: str, code_system: str, strict: bool = True) -> bool:
+    """
+    Validate code format for a given code system.
+
+    Args:
+        code: Code to validate
+        code_system: Code system (iso2, iso3, m49, etc.)
+        strict: If True, raise exception on invalid format
+
+    Returns:
+        True if valid
+
+    Raises:
+        CodeFormatError: If strict=True and code is invalid
+    """
+    if not code or not isinstance(code, str):
+        if strict:
+            raise CodeFormatError(str(code), code_system, "non-empty string")
+        return False
+
+    if code_system not in CODE_SYSTEMS:
+        if strict:
+            raise ValidationError(
+                f"Unknown code system: {code_system}",
+                details={"code_system": code_system},
+            )
+        return False
+
+    pattern = CODE_SYSTEMS[code_system]["format"]
+    is_valid = bool(re.match(pattern, code))
+
+    if not is_valid and strict:
+        example = CODE_SYSTEMS[code_system]["example"]
+        raise CodeFormatError(code, code_system, f"{pattern} (e.g., {example})")
+
+    return is_valid
+
+
+def validate_iso2(code: str, strict: bool = True) -> bool:
+    """Validate ISO 3166-1 alpha-2 code."""
+    return validate_code_format(code, "iso2", strict=strict)
+
+
+def validate_iso3(code: str, strict: bool = True) -> bool:
+    """Validate ISO 3166-1 alpha-3 code."""
+    return validate_code_format(code, "iso3", strict=strict)
+
+
+def validate_iso_numeric(code: str, strict: bool = True) -> bool:
+    """Validate ISO 3166-1 numeric code."""
+    return validate_code_format(code, "iso_numeric", strict=strict)
+
+
+def validate_m49(code: str, strict: bool = True) -> bool:
+    """Validate UN M49 code."""
+    return validate_code_format(code, "m49", strict=strict)
+
+
+def validate_wikidata_qid(qid: str, strict: bool = True) -> bool:
+    """Validate Wikidata QID."""
+    return validate_code_format(qid, "wikidata", strict=strict)
+
+
+def validate_confidence(confidence: float) -> bool:
+    """
+    Validate confidence score.
+
+    Args:
+        confidence: Confidence score
+
+    Returns:
+        True if valid (0.0 <= confidence <= 1.0)
+    """
+    if not isinstance(confidence, int | float):
+        return False
+    return 0.0 <= confidence <= 1.0
+
+
+def validate_date_string(date_str: str) -> bool:
+    """
+    Validate ISO date string format.
+
+    Args:
+        date_str: Date string in ISO format (YYYY-MM-DD)
+
+    Returns:
+        True if valid
+
+    Examples:
+        >>> validate_date_string("2025-01-01")
+        True
+        >>> validate_date_string("2025-1-1")
+        False
+    """
+    if not date_str or not isinstance(date_str, str):
+        return False
+
+    pattern = r"^\d{4}-\d{2}-\d{2}$"
+    if not re.match(pattern, date_str):
+        return False
+
+    # Try parsing to ensure it's a valid date
+    try:
+        year, month, day = map(int, date_str.split("-"))
+        date(year, month, day)
+        return True
+    except ValueError:
+        return False
+
+
+def validate_temporal_range(
+    valid_from: date | None,
+    valid_until: date | None,
+    strict: bool = True,
+) -> bool:
+    """
+    Validate temporal validity range.
+
+    Args:
+        valid_from: Start date (inclusive)
+        valid_until: End date (exclusive)
+        strict: If True, raise exception on invalid range
+
+    Returns:
+        True if valid
+
+    Raises:
+        ValidationError: If strict=True and range is invalid
+    """
+    if valid_from is None and valid_until is None:
+        return True
+
+    if valid_from is not None and valid_until is not None and valid_from >= valid_until:
+        if strict:
+            raise ValidationError(
+                f"Invalid temporal range: valid_from ({valid_from}) "
+                f"must be before valid_until ({valid_until})",
+                details={"valid_from": valid_from, "valid_until": valid_until},
+            )
+        return False
+
+    return True
+
+
+def validate_entity_type(entity_type: str) -> bool:
+    """
+    Validate entity type against EntityType enum values.
+
+    Args:
+        entity_type: Entity type to validate
+
+    Returns:
+        True if valid
+    """
+    return entity_type in {t.value for t in EntityType}
+
+
+def validate_alias_type(alias_type: str) -> bool:
+    """
+    Validate alias type against AliasType enum values.
+
+    Args:
+        alias_type: Alias type to validate
+
+    Returns:
+        True if valid
+    """
+    return alias_type in {t.value for t in AliasType}
+
+
+def validate_language_code(lang_code: str) -> bool:
+    """
+    Validate ISO 639-1 language code (basic validation).
+
+    Args:
+        lang_code: Language code (e.g., "en", "fr")
+
+    Returns:
+        True if format is valid (2 lowercase letters)
+    """
+    if not lang_code or not isinstance(lang_code, str):
+        return False
+    return bool(re.match(r"^[a-z]{2}$", lang_code))
+
+
+def validate_non_empty_string(value: Any, field_name: str = "value") -> str:
+    """
+    Validate that value is a non-empty string.
+
+    Args:
+        value: Value to validate
+        field_name: Field name for error message
+
+    Returns:
+        The validated string
+
+    Raises:
+        ValidationError: If value is not a non-empty string
+    """
+    if not isinstance(value, str):
+        raise ValidationError(
+            f"{field_name} must be a string",
+            details={"field": field_name, "type": type(value).__name__},
+        )
+
+    if not value.strip():
+        raise ValidationError(
+            f"{field_name} must not be empty",
+            details={"field": field_name},
+        )
+
+    return value
+
+
+def validate_precedence(precedence: int) -> bool:
+    """
+    Validate overlay precedence value.
+
+    Args:
+        precedence: Precedence value (0-999)
+
+    Returns:
+        True if valid
+    """
+    return isinstance(precedence, int) and 0 <= precedence <= 999
+
+
+def sanitize_query(query: str) -> str:
+    """
+    Sanitize query string.
+
+    Args:
+        query: Raw query string
+
+    Returns:
+        Sanitized query string
+    """
+    if not isinstance(query, str):
+        return ""
+
+    # Strip whitespace
+    query = query.strip()
+
+    # Collapse multiple spaces
+    query = re.sub(r"\s+", " ", query)
+
+    # Remove control characters
+    query = "".join(char for char in query if ord(char) >= 32 or char in "\n\t")
+
+    return query
+
+
+def validate_schema_version(version: str) -> bool:
+    """
+    Validate semantic version string.
+
+    Args:
+        version: Version string (e.g., "1.2.3")
+
+    Returns:
+        True if valid semantic version
+    """
+    if not version or not isinstance(version, str):
+        return False
+
+    pattern = r"^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$"
+    return bool(re.match(pattern, version))

resolvekit-0.0.1.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: resolvekit
+Version: 0.0.1
+Summary: A local, offline-first entity and place resolution system that maps messy place/entity strings and codes to canonical entities with calibrated confidence scores
+Keywords: entity-resolution,geocoding,place-names,data-commons,iso-codes,offline,disambiguation,normalization
+Author: Jorge Rivera
+Author-email: Jorge Rivera <jorge.rivera@one.org>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: rapidfuzz>=3.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: sqlmodel>=0.0.24
+Requires-Python: >=3.11
+Project-URL: Documentation, https://github.com/jm-rivera/resolvekit
+Project-URL: Homepage, https://github.com/jm-rivera/resolvekit
+Project-URL: Repository, https://github.com/jm-rivera/resolvekit
+Description-Content-Type: text/markdown
+
+# resolvekit
+An open offline resolver for places and entities

resolvekit-0.0.1.dist-info/RECORD

@@ -0,0 +1,70 @@
+resolvekit/README.md,sha256=y3wwMUUhTa-74Th-9egHjLT_eU4Ezdt346N-1DniXDc,3341
+resolvekit/__init__.py,sha256=P27cp_CtpQIYq-5s492dbwmoNOydR_b7D4SA2IwRXGI,1453
+resolvekit/api/README.md,sha256=m9YT0X23bvnK8DfjKKJsXxLlTabqgCn31gyEfvQpKV0,4402
+resolvekit/api/__init__.py,sha256=IyQGE-3MV2YHJ9_M2ALuXnHdawf5vFeWja9DKnDXYvU,200
+resolvekit/api/convenience.py,sha256=k14RTIZ8ECfbl-Lw9HuJQ5VsaPIjqaoGBONabYQs2KU,1537
+resolvekit/api/resolver.py,sha256=EkKRg7qPZdQnTcVThlwzKcG18FJ4-LYaxmvv7TKXqBk,16402
+resolvekit/builders/README.md,sha256=Rgi5CYSjzx3HFF8BOXlwP5pwCueBO0TyZY_H3YaLAKs,4408
+resolvekit/builders/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+resolvekit/calibration/README.md,sha256=3AK1svhKwDl1qmuMe2UQpuWQzm5n1G2oCzL8E9DAYkU,10308
+resolvekit/calibration/__init__.py,sha256=xrHDRZrX-dEoLELn-akglIQwhiZoYbXliUjc9_AbVOk,378
+resolvekit/calibration/calibrator.py,sha256=S2D78NPcxtkMXg12oeWzrbpZY63mTFqYJx-h9lfq-ps,5751
+resolvekit/calibration/features.py,sha256=brZW13GY8q7nvlGapBpc6t5tCJg5jwGS5c5rTdUf6z0,5057
+resolvekit/calibration/models.py,sha256=OswPHOg6VibnIdlyOMcFpoPZcSDiyP0I8mjuMdTdxN4,2681
+resolvekit/cli/README.md,sha256=RqMHx6sGos9lqSBQOshxNaCbDEfOL7AchbYeIl06hyo,4357
+resolvekit/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+resolvekit/cli/main.py,sha256=UL2le9Sq0hIiM5QkgZZUwdh2tnLxR02bZqd1ALoSbKU,738
+resolvekit/config.py,sha256=yQzJrRo4vC9mdq4_sHFufiMEpMYpJ17Qs74TsCgUPRs,3317
+resolvekit/constants.py,sha256=BhQjtFJXkZR0rSxy45zzyPxtTzUM3ygfwi47GaFgnrs,5815
+resolvekit/constraints/README.md,sha256=GhUNgqNyamOnWtiQRwqr85OtxPxY3nohcQwI-Uskt7M,3329
+resolvekit/constraints/__init__.py,sha256=YI78gvQmplkA49si1kEB2-lMmdX_MO7DN18XfcEkwtQ,603
+resolvekit/constraints/constraint_engine.py,sha256=vuAM29gwT040sWPKRhrwGN-9qkVlpVev3RYpTJQEIZQ,4134
+resolvekit/constraints/hierarchy_validator.py,sha256=tAdyEnq4Rg93Y5sjIu6V_M20_OmVyGyBtLiIvHGvutQ,5658
+resolvekit/constraints/membership_validator.py,sha256=qvUDZoOU1erAKPdIDOaK7mUtMnrOXPBCkVOKinZ7cqQ,1915
+resolvekit/constraints/protocols.py,sha256=7de5utULltgZbxCMchh3PoF67pIvy8i1vv4Utarn0Kk,924
+resolvekit/constraints/temporal_validator.py,sha256=mAtIwErmj0coko1ujmT4zWn7b-QmVvumgDlH_PgIz8U,1378
+resolvekit/constraints/type_validator.py,sha256=2K8gNvN3xzc2eesPuUOdXzVLWEIYT-LTZx9S24JEMPE,1281
+resolvekit/data/README.md,sha256=3SP439S6KSeaWlrk_nfvAuU8Px0LIAsUgKXmit8OHUA,4249
+resolvekit/data/__init__.py,sha256=Vc81HnWrrDgafjN-klJawwLHyY7KU-E1zTpj7DhlpCY,405
+resolvekit/data/alias_repository.py,sha256=L-ej7a75Dog0kFLqDIYtED0BMlDwHvBgN3x2MzbN2P8,6972
+resolvekit/data/code_repository.py,sha256=Xs3JSKVEYE8UkTldL3xjNiTon804zlaBNwTOZ6ycuUs,2780
+resolvekit/data/context_filters.py,sha256=u8pWVLRyryG7UuiozSzj5AmmuK2-y-97oev7_6_-iCg,1692
+resolvekit/data/db_manager.py,sha256=tocuQVbh8E5pxRApyLiRFOi5JRqhWZbPJ5JSFRZvuG8,6293
+resolvekit/data/entity_repository.py,sha256=CndYSBinzhr7VFQFfRRLyHRMBS19_PN4nkDYgmNW2Kk,15258
+resolvekit/data/membership_repository.py,sha256=IVDubcfjzHbp8sRxwIvg7lVG4xNh9jUQKEyRjpES51o,3701
+resolvekit/data/query_builder.py,sha256=KJONi8a9vBQJxOEzZAOCFrTRU-5-V8I9QvgkGXyeeiY,5824
+resolvekit/data/schema.py,sha256=g72TjBXkzJm1rJBMxi_FFD02fqUCtS2vWqtl9wfLBi0,3926
+resolvekit/disambiguation/README.md,sha256=vq_qvhuGmrzRRjDjmZWH1bAOWwk8YdzoyYkx5pZoQyo,2423
+resolvekit/disambiguation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+resolvekit/extraction/README.md,sha256=YOjXgoWxylQiyonrbSduUSkLV-zzxT37gv7jyiSc0_I,5397
+resolvekit/extraction/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+resolvekit/matchers/README.md,sha256=BCCY60z0net_niFEwrAumiQctW24w2v4yzru7p8C1r8,2466
+resolvekit/matchers/__init__.py,sha256=LodewJZ-SK4gb7ThKYLC1MewQoMh9PTevxyY5xibiAY,2339
+resolvekit/matchers/alias_exact.py,sha256=q-wbFzUGDorJ-vkbmWVUUa8AFSKPzkR7QKj4g1OJFxM,1910
+resolvekit/matchers/canonical_name.py,sha256=A5dIES0EZnM4nzThsntBxknawH92Z_cXDXCf20r2WTc,1876
+resolvekit/matchers/cascade.py,sha256=8indUpJua1Y3-qgz1QCxh_O_USKZ3hzr3d8NRopr3-o,4593
+resolvekit/matchers/code_validators.py,sha256=XOaTnlpbE1RiJ7NpesSwRkZ_Jd9JGVbmC2tWqZRlMSk,7693
+resolvekit/matchers/exact_code.py,sha256=DpTLuL7b1fj-3mwAeUxiJhgV6UapEcLlt8VdpMt1vE8,6162
+resolvekit/matchers/fts_matcher.py,sha256=LZ8Gx11krLHqumrMtKvnld6xwUI8lCcdQtMs7VZvHvg,3132
+resolvekit/matchers/fuzzy_matcher.py,sha256=NMr7PQrpSB9jtMCVCtwex8-Rqe1b1bT_lsF1LbWvl3w,4060
+resolvekit/matchers/priorities.py,sha256=rkNXAsjUZ7VjNFlMMXjE4QU1-aW_s0TaMP9BG4fVUv8,5572
+resolvekit/matchers/protocols.py,sha256=5lh1FWoqxVEAVhK3nLJ6bE4HoaU-Mdrv2eUnZI68h8A,1840
+resolvekit/normalization/README.md,sha256=sTFiMLohy4QYxau1yXC1PFuxzh98A55D9J41EFQOI7c,5660
+resolvekit/normalization/__init__.py,sha256=D4O8UDgyLaFR293JhSBVZneI8UMlUDlCE8iyBMOgOw8,198
+resolvekit/normalization/normalizer.py,sha256=qYe8r-1XVokjy7JfdY-w_c-Q5B2MI7B5oIAwjea_0L8,4430
+resolvekit/overlays/README.md,sha256=27J3NZyrNHdiN_ZMcRwN2nsFNROkX_Gs3HJfcT9AOJ0,5696
+resolvekit/overlays/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+resolvekit/types.py,sha256=-x49oUSz0gbkqDxhWCzs_tgwTc3KkT7ZMrgDpYDzEgg,17845
+resolvekit/utils/README.md,sha256=uEkPsEJEPlzihsBr1fq8C_aySKucwp9AtKF6s6-oBvs,4218
+resolvekit/utils/__init__.py,sha256=NpRdvjDYdZk9Ro94COtwZWsbzGNBsyvATzhJrSwLktA,1173
+resolvekit/utils/cache.py,sha256=l29xSSRORe9tzhQldwy0DCgUuozU7ElOMJw5gpBLJbU,3144
+resolvekit/utils/dates.py,sha256=vftaufH6iDYUC0TS5iIXCqZkV705jjUi0MrqjCYE2FY,8606
+resolvekit/utils/errors.py,sha256=2QuTqko1soyG7HPQmh7ulbWj3zGz2I26eCHDkZMj5zs,4168
+resolvekit/utils/files.py,sha256=JFBqzaSOb5pjWk_sYUsI10vuZ8sH1BF2QE510EqkK4A,8332
+resolvekit/utils/logging.py,sha256=OOXbAmw87XRMrNktzGXTe04c5PxPtf5IAURwReB-D_U,6325
+resolvekit/utils/text.py,sha256=OwVzNSXyFWLM4idKBZfLDoeEYKuS3itWJ_fotjSk2Cg,10971
+resolvekit/utils/validation.py,sha256=T1mB4bSmNQGV7ivnbOjsGtzpkQhochNeHPiB_OUL9gI,7424
+resolvekit-0.0.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+resolvekit-0.0.1.dist-info/entry_points.txt,sha256=9J3lM9GnLnIJgVRv-Z8sQ4l-to8EhoJEx1SuXnkqF2g,48
+resolvekit-0.0.1.dist-info/METADATA,sha256=v6qY2k78_KkHuWUSQ_NXUQwst2ewcCynnQLzUkM3WOM,1638
+resolvekit-0.0.1.dist-info/RECORD,,

resolvekit-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

resolvekit-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+resolvekit = resolvekit:main
+