rigour 2.2.0__tar.gz → 2.2.2__tar.gz

{rigour-2.2.0 → rigour-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rigour
-Version: 2.2.0
+Version: 2.2.2
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: License :: OSI Approved :: MIT License
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Rust
 Requires-Dist: pyyaml>=5.0.0,<7.0.0
 Requires-Dist: normality>=3.0.1,<4.0.0
+Requires-Dist: prefixdate>=0.5.0,<1.0.0
 Requires-Dist: orjson>=3.0.0,<4.0.0
 Requires-Dist: python-stdnum>=2.0,<3.0.0
 Requires-Dist: jinja2>=3.1.0,<4.0.0

{rigour-2.2.0 → rigour-2.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "rigour"
-version = "2.2.0"
+version = "2.2.2"
 description = "Financial crime domain data validation and normalization library."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -24,6 +24,7 @@ requires-python = ">= 3.10"
 dependencies = [
     "pyyaml >= 5.0.0, < 7.0.0",
     "normality >= 3.0.1, < 4.0.0",
+    "prefixdate >= 0.5.0, < 1.0.0",
     "orjson >= 3.0.0, < 4.0.0",
     "python-stdnum >= 2.0, < 3.0.0",
     "jinja2 >= 3.1.0, < 4.0.0",

rigour-2.2.2/rigour/dates.py

@@ -0,0 +1,203 @@
+"""Compare prefix dates without pretending they are exact instants.
+
+A prefix date such as ``2026`` or ``2026-06`` represents an interval, rather
+than the first instant of that year or month. Use the string wrappers for
+one-off comparisons, or parse a [DateInterval][rigour.dates.DateInterval] once
+when comparing the same value repeatedly.
+
+Age and recency checks use the same comparisons with a shifted reference:
+
+```python
+cutoff = now - max_age
+is_recent = not ended_before(value, cutoff)
+```
+"""
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from functools import lru_cache
+
+from prefixdate import Precision, parse
+
+from rigour.util import MEMO_SMALL
+
+_TIMEZONE_SUFFIX_RE = re.compile(r"(?:Z|[+-]\d{2}(?::?\d{2})?)$")
+_SECOND_TIMESTAMP_RE = re.compile(
+    r"^[12]\d{3}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}"
+    r"(?:Z|[+-]\d{2}(?::?\d{2})?)?$"
+)
+
+
+@dataclass(frozen=True)
+class DateInterval:
+    """Represent every possible instant described by an imprecise date.
+
+    Use this parsed form when applying multiple comparisons to the same prefix
+    date. Both bounds are timezone-aware UTC datetimes and ``end`` is exclusive.
+
+    Attributes:
+        start: Earliest instant represented by the date.
+        end: First instant after the represented interval.
+    """
+
+    start: datetime
+    end: datetime
+
+
+def _ensure_utc(value: datetime) -> datetime:
+    """Adapt legacy naive-UTC values to aware UTC datetimes."""
+    if value.tzinfo is None or value.utcoffset() is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def parse_utc(value: str) -> datetime:
+    """Parse an exact timestamp as an aware UTC datetime.
+
+    Use this at a prefix-date boundary where an exact timestamp may carry an
+    offset. Naive timestamps use the ecosystem convention of implicit UTC.
+
+    Args:
+        value: Canonical second-precision timestamp.
+
+    Returns:
+        The represented instant as a timezone-aware UTC datetime.
+
+    Raises:
+        ValueError: The timestamp is invalid or is not precise to the second.
+    """
+    if _SECOND_TIMESTAMP_RE.fullmatch(value) is None:
+        raise ValueError(f"Invalid exact timestamp: {value!r}")
+    try:
+        timestamp = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ValueError(f"Invalid timestamp: {value!r}") from exc
+    return _ensure_utc(timestamp)
+
+
+@lru_cache(maxsize=MEMO_SMALL)
+def prefix_interval(value: str) -> DateInterval:
+    """Expand a canonical prefix date into its represented UTC interval.
+
+    Use this at the boundary between prefix-date strings and interval comparison.
+    Feed it normalized property values only, not uncleaned source strings. Exact
+    timestamps with offsets are converted to UTC before their one-second interval
+    is constructed.
+
+    Args:
+        value: Canonical prefix date, from year through second precision.
+
+    Returns:
+        The timezone-aware UTC, half-open interval represented by the value.
+
+    Raises:
+        ValueError: The value is invalid or non-canonical, or an imprecise value
+            carries a timezone.
+    """
+    if _SECOND_TIMESTAMP_RE.fullmatch(value) is not None:
+        start = parse_utc(value)
+        return DateInterval(start=start, end=start + timedelta(seconds=1))
+    has_timezone = value.endswith("Z") or (
+        "T" in value and _TIMEZONE_SUFFIX_RE.search(value) is not None
+    )
+    if has_timezone:
+        raise ValueError("timezone suffixes require second precision")
+
+    prefix = parse(value)
+    if prefix.dt is None or prefix.text is None or prefix.precision == Precision.EMPTY:
+        raise ValueError(f"Invalid prefix date: {value!r}")
+    if prefix.text != value:
+        raise ValueError(f"Prefix date is not canonical: {value!r}")
+
+    start = prefix.dt.replace(tzinfo=timezone.utc)
+    precision = prefix.precision
+    if precision == Precision.YEAR:
+        end = start.replace(year=start.year + 1)
+    elif precision == Precision.MONTH:
+        if start.month == 12:
+            end = start.replace(year=start.year + 1, month=1)
+        else:
+            end = start.replace(month=start.month + 1)
+    elif precision == Precision.DAY:
+        end = start + timedelta(days=1)
+    elif precision == Precision.HOUR:
+        end = start + timedelta(hours=1)
+    elif precision == Precision.MINUTE:
+        end = start + timedelta(minutes=1)
+    elif precision == Precision.SECOND:
+        end = start + timedelta(seconds=1)
+    else:
+        raise ValueError(f"Unsupported prefix date precision: {value!r}")
+    return DateInterval(start=start, end=end)
+
+
+def interval_ended_before(value: DateInterval, reference: datetime) -> bool:
+    """Check whether an interval has completely elapsed before a point in time.
+
+    Use this for end dates and age cutoffs when the prefix date has already been
+    parsed.
+
+    Args:
+        value: Interval to compare.
+        reference: Timezone-aware UTC point in time.
+
+    Returns:
+        ``True`` if every instant represented by the interval precedes the
+        reference.
+    """
+    return value.end <= reference
+
+
+def interval_starts_after(value: DateInterval, reference: datetime) -> bool:
+    """Check whether an interval begins strictly after a point in time.
+
+    Use this for start dates and future-date guardrails when the prefix date has
+    already been parsed.
+
+    Args:
+        value: Interval to compare.
+        reference: Timezone-aware UTC point in time.
+
+    Returns:
+        ``True`` if the earliest instant in the interval follows the reference.
+    """
+    return value.start > reference
+
+
+def ended_before(value: str, reference: datetime) -> bool:
+    """Check whether a prefix date has completely elapsed.
+
+    Use this string wrapper for one-off end-date and age-cutoff checks. Parse
+    once with [prefix_interval][rigour.dates.prefix_interval] when making
+    several comparisons against the same value.
+
+    Args:
+        value: Canonical prefix date, from year through second precision.
+        reference: UTC point in time. Legacy naive values are interpreted as
+            UTC; aware values are converted to UTC.
+
+    Returns:
+        ``True`` if every instant represented by the date precedes the
+        reference.
+    """
+    return interval_ended_before(prefix_interval(value), _ensure_utc(reference))
+
+
+def starts_after(value: str, reference: datetime) -> bool:
+    """Check whether a prefix date begins after a point in time.
+
+    Use this string wrapper for one-off start-date and future-date checks. Parse
+    once with [prefix_interval][rigour.dates.prefix_interval] when reusing the
+    same value.
+
+    Args:
+        value: Canonical prefix date, from year through second precision.
+        reference: UTC point in time. Legacy naive values are interpreted as
+            UTC; aware values are converted to UTC.
+
+    Returns:
+        ``True`` if the earliest instant represented by the date follows the
+        reference.
+    """
+    return interval_starts_after(prefix_interval(value), _ensure_utc(reference))

rigour-2.2.2/rigour/ids/imo.py

@@ -0,0 +1,125 @@
+import re
+from typing import Callable, List, Optional, Tuple
+
+from rigour.ids.common import IdentifierFormat
+
+IMO_RE = re.compile(r"(IMO[\s:.#-]*)?(?<!\d)(\d{5,7})(?!\d)")
+
+Checksum = Callable[[List[int]], bool]
+
+
+def _vessel_checksum(digits: List[int]) -> bool:
+    return sum(d * (7 - i) for i, d in enumerate(digits[:6])) % 10 == digits[6]
+
+
+def _company_checksum(digits: List[int]) -> bool:
+    weights = (8, 6, 4, 2, 9, 7)
+    checksum = sum(d * w for d, w in zip(digits, weights))
+    return (11 - checksum % 11) % 10 == digits[6]
+
+
+class IMO(IdentifierFormat):
+    """An IMO number for a ship or a shipping company.
+
+    Ship and company IMO numbers are both seven digits but use different check
+    digit algorithms; this format admits both. Use
+    [is_valid_vessel][rigour.ids.imo.IMO.is_valid_vessel] or
+    [is_valid_company][rigour.ids.imo.IMO.is_valid_company] when the value
+    must belong to one specific scheme, e.g. when minting scheme-specific
+    entity IDs.
+
+    Extraction considers digit runs of five to seven digits, preferring longer
+    runs, then runs carrying an `IMO` prefix, then earlier ones; the first
+    candidate that passes a checksum wins. Runs shorter than seven digits are
+    left-padded with zeros, since data sources commonly strip leading zeros
+    from IMO fields. The all-zero value is rejected.
+    """
+
+    NAME = "imo"
+    TITLE = "IMO"
+    STRONG = True
+
+    @classmethod
+    def is_valid(cls, text: str) -> bool:
+        """Determine if the given text contains a valid IMO number.
+
+        Args:
+            text: A string that may contain an IMO number.
+
+        Returns:
+            True if an IMO number valid in either checksum scheme can be
+            extracted from the text.
+        """
+        return cls._extract(text, (_vessel_checksum, _company_checksum)) is not None
+
+    @classmethod
+    def is_valid_vessel(cls, text: str) -> bool:
+        """Determine if the given text contains a valid ship IMO number.
+
+        Args:
+            text: A string that may contain an IMO number.
+
+        Returns:
+            True if an IMO number valid in the vessel checksum scheme can be
+            extracted from the text.
+        """
+        return cls._extract(text, (_vessel_checksum,)) is not None
+
+    @classmethod
+    def is_valid_company(cls, text: str) -> bool:
+        """Determine if the given text contains a valid company IMO number.
+
+        Args:
+            text: A string that may contain an IMO number.
+
+        Returns:
+            True if an IMO number valid in the company checksum scheme can be
+            extracted from the text.
+        """
+        return cls._extract(text, (_company_checksum,)) is not None
+
+    @classmethod
+    def normalize(cls, text: str) -> Optional[str]:
+        """Extract and normalize an IMO number from the given text.
+
+        Args:
+            text: A string that may contain an IMO number.
+
+        Returns:
+            The number in `IMO0000000` form, or None if the text contains no
+            checksum-valid IMO number.
+        """
+        value = cls._extract(text, (_vessel_checksum, _company_checksum))
+        if value is None:
+            return None
+        return f"IMO{value}"
+
+    @classmethod
+    def _extract(cls, text: str, checksums: Tuple[Checksum, ...]) -> Optional[str]:
+        matches = sorted(
+            IMO_RE.finditer(text),
+            key=lambda m: (-len(m.group(2)), m.group(1) is None, m.start()),
+        )
+        for match in matches:
+            value = match.group(2).zfill(7)
+            digits = [int(d) for d in value]
+            if not any(digits):
+                continue
+            if any(check(digits) for check in checksums):
+                return value
+        return None
+
+    @classmethod
+    def format(cls, value: str) -> str:
+        """Format the given value as an IMO number.
+
+        Args:
+            value: A pre-validated IMO number.
+
+        Returns:
+            The value with an `IMO` prefix.
+        """
+        value = value.replace(" ", "")
+        if not value.startswith("IMO"):
+            value = f"IMO{value}"
+        return value

{rigour-2.2.0 → rigour-2.2.2}/rust/Cargo.lock

@@ -831,7 +831,7 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rigour-core"
-version = "2.2.0"
+version = "2.2.2"
 dependencies = [
  "aho-corasick",
  "bitflags",

{rigour-2.2.0 → rigour-2.2.2}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rigour-core"
-version = "2.2.0"
+version = "2.2.2"
 edition = "2024"
 rust-version = "1.86"
 license = "MIT"

rigour-2.2.0/rigour/ids/imo.py

@@ -1,60 +0,0 @@
-import re
-from typing import Optional
-
-from rigour.ids.common import IdentifierFormat
-
-IMO_RE = re.compile(r"\b(IMO)?(\d{1,7})\b")
-
-
-class IMO(IdentifierFormat):
-    """An IMO number for a ship or shipping company"""
-
-    NAME = "imo"
-    TITLE = "IMO"
-    STRONG = True
-
-    @classmethod
-    def is_valid(cls, text: str) -> bool:
-        """Determine if the given string is a valid IMO number.
-
-        Shorter numeric strings are left-padded with zeros to seven digits
-        before the checksum is verified, since data sources commonly strip
-        leading zeros from IMO fields.
-        """
-        match = IMO_RE.search(text)
-        if match is None:
-            return False
-        value = match.group(2).zfill(7)
-        digits = [int(d) for d in value]
-
-        # Check if it's a vessel IMO number:
-        checksum = sum(d * (7 - i) for i, d in enumerate(digits[:-1])) % 10
-        if checksum == digits[-1]:
-            return True
-
-        # Check if it's a company IMO number:
-        checksum = digits[0] * 8 + digits[1] * 6 + digits[2] * 4
-        checksum += +digits[3] * 2 + digits[4] * 9 + digits[5] * 7
-        checksum = (11 - (checksum % 11)) % 10
-        if checksum == digits[-1]:
-            return True
-
-        return False
-
-    @classmethod
-    def normalize(cls, text: str) -> Optional[str]:
-        """Normalize the given string to a valid IMO number."""
-        match = IMO_RE.search(text)
-        if match is None:
-            return None
-        value = match.group(2).zfill(7)
-        if cls.is_valid(value):
-            return f"IMO{value}"
-        return None
-
-    @classmethod
-    def format(cls, value: str) -> str:
-        value = value.replace(" ", "")
-        if not value.startswith("IMO"):
-            value = f"IMO{value}"
-        return value