acis-core 1.0.0__py3-none-any.whl

acis_core/__init__.py

@@ -0,0 +1 @@
+"""Reference data and utilities shared by ACIS clients."""

acis_core/a_numbers.py

@@ -0,0 +1,26 @@
+"""Utilities for working with A-Numbers."""
+
+from __future__ import annotations
+
+import re
+
+from acis_core.exceptions import AcisError
+
+
+class InvalidANumberError(AcisError):
+    """Raised when an A-Number isn't valid."""
+
+
+_NON_DIGITS = re.compile(r"[\s\-]")
+
+
+def normalize_a_number(value: str) -> str:
+    candidate = _NON_DIGITS.sub("", value or "")
+    candidate = candidate.removeprefix("A").removeprefix("a")
+    if not candidate.isdigit() or len(candidate) != 9:
+        raise InvalidANumberError(f"A-Number must be 9 digits, got {value!r}")
+    return candidate
+
+
+def redact(a_number: str) -> str:
+    return f"***{a_number[-4:]}" if len(a_number) >= 4 else "***"

acis_core/exceptions.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class AcisError(Exception):
+    """Base class for failures talking to ACIS."""
+
+    def __init__(self, *args: object, payload: dict[str, Any] | None = None) -> None:
+        super().__init__(*args)
+        self.payload = payload

acis_core/nationalities.py

@@ -0,0 +1,65 @@
+"""Utilities for working with EOIR nationality codes."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+
+from acis_core.exceptions import AcisError
+
+HERE = Path(__file__).parent
+REFERENCE_FILE = HERE / "reference" / "nationality-codes.json"
+
+
+class UnknownNationalityError(AcisError):
+    """Raised when a nationality code or name can't be resolved."""
+
+
+# Placeholder entry in the upstream table; never a valid lookup value.
+UNKNOWN_CODE = "??"
+
+
+@dataclass(frozen=True, kw_only=True)
+class Nationality:
+    code: str
+    name: str
+
+
+@cache
+def _tables() -> tuple[dict[str, Nationality], dict[str, Nationality]]:
+    """Return (by_code, by_name) lookup tables of active nationalities."""
+    raw = json.loads(REFERENCE_FILE.read_text(encoding="utf-8"))
+    by_code: dict[str, Nationality] = {}
+    by_name: dict[str, Nationality] = {}
+    for entry in raw:
+        code = entry["Code"].strip().upper()
+        if not entry.get("IsActive") or code == UNKNOWN_CODE:
+            continue
+        nationality = Nationality(code=code, name=entry["Name"].strip().upper())
+        by_code[nationality.code] = nationality
+        by_name[nationality.name] = nationality
+    return by_code, by_name
+
+
+def get_by_code(code: str) -> Nationality:
+    """Look up strictly by code."""
+    by_code, _ = _tables()
+    try:
+        return by_code[code.strip().upper()]
+    except KeyError:
+        raise UnknownNationalityError(f"Unknown nationality code: {code!r}") from None
+
+
+def resolve(value: str) -> Nationality:
+    """Resolve a code (``MX``) or a name (``mexico``) to a Nationality."""
+    candidate = (value or "").strip().upper()
+    if not candidate:
+        raise UnknownNationalityError("Nationality is required")
+    by_code, by_name = _tables()
+    if candidate in by_code:
+        return by_code[candidate]
+    if candidate in by_name:
+        return by_name[candidate]
+    raise UnknownNationalityError(f"Unknown nationality: {value!r}")

acis_core/outcome.py

@@ -0,0 +1,38 @@
+"""Classification of ACIS response payloads."""
+
+from __future__ import annotations
+
+from enum import StrEnum, auto
+from typing import Any
+
+
+class Outcome(StrEnum):
+    """Classification of an ACIS payload by its pinned ``message`` fragments."""
+
+    OK = auto()
+    CAPTCHA_REJECTED = auto()
+    UNAVAILABLE = auto()
+    NOT_FOUND = auto()
+    INVALID_NATIONALITY = auto()
+    OTHER = auto()
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> Outcome:
+        data = payload.get("Data")
+        if isinstance(data, dict):
+            if data.get("AlienName") and data.get("CaseID"):
+                return cls.OK
+            return cls.OTHER
+        message = payload.get("message") or ""
+        for fragment, outcome in MESSAGES:
+            if fragment in message:
+                return outcome
+        return cls.OTHER
+
+
+MESSAGES = (
+    ("Invalid Captcha Provided", Outcome.CAPTCHA_REJECTED),
+    ("Case information is unavailable", Outcome.UNAVAILABLE),
+    ("No case info found", Outcome.NOT_FOUND),
+    ("Invalid nationality code", Outcome.INVALID_NATIONALITY),
+)