nodii-address 0.1.0__tar.gz

nodii_address-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+node_modules/
+dist/
+build/
+coverage/
+.DS_Store
+*.log
+.env
+.env.local
+.env.*.local
+.turbo/
+.bun/
+
+# AI review loop artifacts (scripts/review/ai-review.ts)
+.claude-pre-review.md
+.claude-pre-review.json
+.claude/pending-patches/
+
+# Agent session state (not committed; per-session)
+.claude/endpoints-snapshot.json
+.agent-todo.md
+
+# Python (uv)
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Go
+*.test
+*.out
+go.work.sum
+
+# Generated proto artifacts (regenerate via `bun proto:gen`)
+ts/_generated/
+python/_generated/
+go/_generated/
+
+# Test-stack volumes (docker-compose persistent data)
+infra/test-stack/data/
+# synthetic consumer go binaries
+synthetic-consumers/telemetry/go/nodii-synthetic-telemetry
+synthetic-consumers/pii/go/nodii-synthetic-pii
+synthetic-consumers/auth-sdk/go/nodii-synthetic-auth-sdk

nodii_address-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: nodii-address
+Version: 0.1.0
+Summary: Nodii canonical postal Address value-object + validator (ISO-3166-1 alpha-2; AddressInvalid).
+Project-URL: Homepage, https://github.com/cognion-nucleus/nodii-libs
+Project-URL: Repository, https://github.com/cognion-nucleus/nodii-libs
+Author-email: Nodii <ops@nodii.co>
+License: MIT
+Keywords: address,nodii
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11

nodii_address-0.1.0/README.md

@@ -0,0 +1,51 @@
+# nodii-address
+
+The canonical postal **Address** value-object + validator for the Nodii stack.
+A pure value-object library (no I/O): a dataclass, a validator, and PII-field
+tagging. Geocoding / distributor resolution is **not** here — that stays in
+nodii-geo-service.
+
+```python
+from nodii_address import (
+    validate_address,
+    is_valid_address,
+    AddressInvalid,
+    ADDRESS_PII_FIELDS,
+    Address,
+)
+
+addr = validate_address(
+    {"line1": "221B Baker St", "city": "London", "country_code": "gb"}
+)
+# → Address(line1="221B Baker St", city="London", country_code="GB", ...)
+
+try:
+    validate_address({"line1": "x", "city": "y", "country_code": "ZZ"})
+except AddressInvalid as e:
+    e.code    # "ADDRESS_INVALID" → map to CUSTOMER_ADDRESS_INVALID
+    e.reason  # "COUNTRY_CODE_INVALID"
+    e.field   # "country_code"
+```
+
+## Shape
+
+`{label?, line1, line2?, city, region?, postal_code?, country_code}` — matches
+the gRPC `Address` message. `country_code` is ISO-3166-1 alpha-2 (validated
+against the assigned set). Required: `line1`, `city`, `country_code`.
+
+## Validation
+
+`validate_address(data)` trims string fields, upper-cases `country_code`, drops
+empty optionals (→ `None`), and raises `AddressInvalid` (`.code`, `.reason`,
+`.field`) on a missing required field or an invalid country code.
+`is_valid_address` is the non-raising variant. Per-country postal/region format
+rules are intentionally out of scope (geo-service owns those).
+
+## PII
+
+`ADDRESS_PII_FIELDS` lists the fields that are PII (`line1`, `line2`, `city`,
+`region`, `postal_code`) and must be encrypted under the owning subject's DEK at
+rest by the consumer (via `nodii-pii`). `label` and `country_code` are not PII.
+This library never stores or encrypts.
+
+Shipped in parity with `@nodii/address` (TS) and `nodii.co/nodii-libs/go/address`.

nodii_address-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+# nodii-address — the canonical postal Address value-object + validator.
+
+[project]
+name = "nodii-address"
+version = "0.1.0"
+description = "Nodii canonical postal Address value-object + validator (ISO-3166-1 alpha-2; AddressInvalid)."
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Nodii", email = "ops@nodii.co" },
+]
+keywords = ["nodii", "address"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/cognion-nucleus/nodii-libs"
+Repository = "https://github.com/cognion-nucleus/nodii-libs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nodii_address"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.7",
+    "mypy>=1.13",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=6.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "N",      # pep8-naming
+    "ASYNC",  # flake8-async
+    "S",      # flake8-bandit (security)
+    "PT",     # flake8-pytest-style
+    "RET",    # flake8-return
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "S101",   # use of assert detected — fine in tests
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "S105", "S106"]   # bandit relaxed for tests
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+disallow_untyped_decorators = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--cov=src",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-report=xml",
+]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == \"__main__\":",
+]

nodii_address-0.1.0/src/nodii_address/__init__.py

@@ -0,0 +1,409 @@
+"""nodii-address — the canonical postal Address value-object + validator.
+
+A pure value-object library (NO I/O): an ``Address`` dataclass, a
+``validate_address`` validator surfacing a typed ``AddressInvalid`` (mapped by
+consumers to CUSTOMER_ADDRESS_INVALID), and the PII-field tagging. Geocoding /
+distributor resolution is explicitly NOT here — it stays in nodii-geo-service
+(``geo.DistributionResolver``). Request 5235eb58 (nodii-customer-service).
+
+PII posture: line1/line2/city/region/postal_code are PII under the OWNING
+subject's DEK (the consuming service encrypts via nodii-pii); ``label`` is a
+non-PII tag and ``country_code`` is non-PII. This lib only TAGS which fields are
+PII (see ``ADDRESS_PII_FIELDS``) — it never stores or encrypts.
+
+Cross-lang parity with @nodii/address (TS) + go/address.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+__version__ = "0.0.1"
+
+LIB_NAME = "address"
+
+#: Fields of :class:`Address` that carry PII and MUST be encrypted under the
+#: owning subject's DEK at rest. ``label`` and ``country_code`` are NOT PII.
+ADDRESS_PII_FIELDS: tuple[str, ...] = (
+    "line1",
+    "line2",
+    "city",
+    "region",
+    "postal_code",
+)
+
+AddressInvalidReason = Literal[
+    "LINE1_REQUIRED",
+    "CITY_REQUIRED",
+    "COUNTRY_CODE_REQUIRED",
+    "COUNTRY_CODE_INVALID",
+    "NOT_AN_OBJECT",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Address:
+    """Canonical postal address (gRPC ``Address`` message shape).
+
+    Required: ``line1``, ``city``, ``country_code``. Optional: ``label``,
+    ``line2``, ``region``, ``postal_code``. ``country_code`` is ISO-3166-1
+    alpha-2 (uppercase).
+    """
+
+    line1: str
+    city: str
+    country_code: str
+    label: str | None = None
+    line2: str | None = None
+    region: str | None = None
+    postal_code: str | None = None
+
+
+class AddressInvalid(ValueError):  # noqa: N818 — contract-specified name (spec 5235eb58 + TS/Go parity); not "AddressInvalidError"
+    """Raised by :func:`validate_address`. Consumers map ``.code`` (stable
+    string) to their transport status — for nodii-customer-service that is
+    ``CUSTOMER_ADDRESS_INVALID``.
+    """
+
+    code = "ADDRESS_INVALID"
+
+    def __init__(self, reason: AddressInvalidReason, field: str | None = None) -> None:
+        self.reason: AddressInvalidReason = reason
+        self.field = field
+        msg = (
+            f'address invalid: {reason} (field "{field}")'
+            if field
+            else f"address invalid: {reason}"
+        )
+        super().__init__(msg)
+
+
+# ISO-3166-1 alpha-2 — the official assigned set (249 codes), byte-identical to
+# the TS + Go ports so validation is cross-lang identical. Sorted; user-assigned
+# ranges (e.g. XK) excluded.
+ISO_3166_1_ALPHA2: frozenset[str] = frozenset(
+    [
+        "AD",
+        "AE",
+        "AF",
+        "AG",
+        "AI",
+        "AL",
+        "AM",
+        "AO",
+        "AQ",
+        "AR",
+        "AS",
+        "AT",
+        "AU",
+        "AW",
+        "AX",
+        "AZ",
+        "BA",
+        "BB",
+        "BD",
+        "BE",
+        "BF",
+        "BG",
+        "BH",
+        "BI",
+        "BJ",
+        "BL",
+        "BM",
+        "BN",
+        "BO",
+        "BQ",
+        "BR",
+        "BS",
+        "BT",
+        "BV",
+        "BW",
+        "BY",
+        "BZ",
+        "CA",
+        "CC",
+        "CD",
+        "CF",
+        "CG",
+        "CH",
+        "CI",
+        "CK",
+        "CL",
+        "CM",
+        "CN",
+        "CO",
+        "CR",
+        "CU",
+        "CV",
+        "CW",
+        "CX",
+        "CY",
+        "CZ",
+        "DE",
+        "DJ",
+        "DK",
+        "DM",
+        "DO",
+        "DZ",
+        "EC",
+        "EE",
+        "EG",
+        "EH",
+        "ER",
+        "ES",
+        "ET",
+        "FI",
+        "FJ",
+        "FK",
+        "FM",
+        "FO",
+        "FR",
+        "GA",
+        "GB",
+        "GD",
+        "GE",
+        "GF",
+        "GG",
+        "GH",
+        "GI",
+        "GL",
+        "GM",
+        "GN",
+        "GP",
+        "GQ",
+        "GR",
+        "GS",
+        "GT",
+        "GU",
+        "GW",
+        "GY",
+        "HK",
+        "HM",
+        "HN",
+        "HR",
+        "HT",
+        "HU",
+        "ID",
+        "IE",
+        "IL",
+        "IM",
+        "IN",
+        "IO",
+        "IQ",
+        "IR",
+        "IS",
+        "IT",
+        "JE",
+        "JM",
+        "JO",
+        "JP",
+        "KE",
+        "KG",
+        "KH",
+        "KI",
+        "KM",
+        "KN",
+        "KP",
+        "KR",
+        "KW",
+        "KY",
+        "KZ",
+        "LA",
+        "LB",
+        "LC",
+        "LI",
+        "LK",
+        "LR",
+        "LS",
+        "LT",
+        "LU",
+        "LV",
+        "LY",
+        "MA",
+        "MC",
+        "MD",
+        "ME",
+        "MF",
+        "MG",
+        "MH",
+        "MK",
+        "ML",
+        "MM",
+        "MN",
+        "MO",
+        "MP",
+        "MQ",
+        "MR",
+        "MS",
+        "MT",
+        "MU",
+        "MV",
+        "MW",
+        "MX",
+        "MY",
+        "MZ",
+        "NA",
+        "NC",
+        "NE",
+        "NF",
+        "NG",
+        "NI",
+        "NL",
+        "NO",
+        "NP",
+        "NR",
+        "NU",
+        "NZ",
+        "OM",
+        "PA",
+        "PE",
+        "PF",
+        "PG",
+        "PH",
+        "PK",
+        "PL",
+        "PM",
+        "PN",
+        "PR",
+        "PS",
+        "PT",
+        "PW",
+        "PY",
+        "QA",
+        "RE",
+        "RO",
+        "RS",
+        "RU",
+        "RW",
+        "SA",
+        "SB",
+        "SC",
+        "SD",
+        "SE",
+        "SG",
+        "SH",
+        "SI",
+        "SJ",
+        "SK",
+        "SL",
+        "SM",
+        "SN",
+        "SO",
+        "SR",
+        "SS",
+        "ST",
+        "SV",
+        "SX",
+        "SY",
+        "SZ",
+        "TC",
+        "TD",
+        "TF",
+        "TG",
+        "TH",
+        "TJ",
+        "TK",
+        "TL",
+        "TM",
+        "TN",
+        "TO",
+        "TR",
+        "TT",
+        "TV",
+        "TW",
+        "TZ",
+        "UA",
+        "UG",
+        "UM",
+        "US",
+        "UY",
+        "UZ",
+        "VA",
+        "VC",
+        "VE",
+        "VG",
+        "VI",
+        "VN",
+        "VU",
+        "WF",
+        "WS",
+        "YE",
+        "YT",
+        "ZA",
+        "ZM",
+        "ZW",
+    ]  # noqa: SIM905 — split-string keeps the 249-code set byte-identical to TS/Go
+)
+
+
+def is_valid_country_code(code: str) -> bool:
+    """``True`` iff ``code`` is an assigned ISO-3166-1 alpha-2 code (uppercase)."""
+    return code in ISO_3166_1_ALPHA2
+
+
+def _trim_or_empty(v: Any) -> str:
+    return v.strip() if isinstance(v, str) else ""
+
+
+def _opt_trim(v: Any) -> str | None:
+    s = _trim_or_empty(v)
+    return s or None
+
+
+def validate_address(data: Mapping[str, Any]) -> Address:
+    """Validate + normalize an address. Returns a clean :class:`Address` (string
+    fields trimmed; empty optionals dropped; ``country_code`` upper-cased) or
+    raises :class:`AddressInvalid`.
+
+    Rules: ``line1``, ``city``, ``country_code`` required + non-empty;
+    ``country_code`` must be a valid ISO-3166-1 alpha-2 code. Per-country
+    postal/region format rules are intentionally OUT of scope (geo-service).
+    """
+    if not isinstance(data, Mapping):
+        raise AddressInvalid("NOT_AN_OBJECT")
+    line1 = _trim_or_empty(data.get("line1"))
+    if line1 == "":
+        raise AddressInvalid("LINE1_REQUIRED", "line1")
+    city = _trim_or_empty(data.get("city"))
+    if city == "":
+        raise AddressInvalid("CITY_REQUIRED", "city")
+    cc_raw = _trim_or_empty(data.get("country_code"))
+    if cc_raw == "":
+        raise AddressInvalid("COUNTRY_CODE_REQUIRED", "country_code")
+    country_code = cc_raw.upper()
+    if not is_valid_country_code(country_code):
+        raise AddressInvalid("COUNTRY_CODE_INVALID", "country_code")
+    return Address(
+        line1=line1,
+        city=city,
+        country_code=country_code,
+        label=_opt_trim(data.get("label")),
+        line2=_opt_trim(data.get("line2")),
+        region=_opt_trim(data.get("region")),
+        postal_code=_opt_trim(data.get("postal_code")),
+    )
+
+
+def is_valid_address(data: Mapping[str, Any]) -> bool:
+    """Non-throwing variant: ``True`` iff ``data`` validates."""
+    try:
+        validate_address(data)
+        return True
+    except AddressInvalid:
+        return False
+
+
+__all__ = [
+    "ADDRESS_PII_FIELDS",
+    "ISO_3166_1_ALPHA2",
+    "LIB_NAME",
+    "Address",
+    "AddressInvalid",
+    "AddressInvalidReason",
+    "__version__",
+    "is_valid_address",
+    "is_valid_country_code",
+    "validate_address",
+]

nodii_address-0.1.0/tests/test_smoke.py

@@ -0,0 +1,95 @@
+"""nodii-address validator tests (parity with @nodii/address TS + go/address)."""
+
+import pytest
+
+from nodii_address import (
+    ADDRESS_PII_FIELDS,
+    Address,
+    AddressInvalid,
+    is_valid_address,
+    is_valid_country_code,
+    validate_address,
+)
+
+
+def test_full_address_trims_and_uppercases_country() -> None:
+    a = validate_address(
+        {
+            "label": " home ",
+            "line1": " 221B Baker St ",
+            "line2": " Flat 2 ",
+            "city": " London ",
+            "region": " Greater London ",
+            "postal_code": " NW1 6XE ",
+            "country_code": "gb",
+        }
+    )
+    assert a == Address(
+        line1="221B Baker St",
+        city="London",
+        country_code="GB",
+        label="home",
+        line2="Flat 2",
+        region="Greater London",
+        postal_code="NW1 6XE",
+    )
+
+
+def test_minimal_address_empty_optionals_become_none() -> None:
+    a = validate_address(
+        {"line1": "1 Main St", "city": "Bengaluru", "country_code": "IN", "region": "  "}
+    )
+    assert a.line1 == "1 Main St"
+    assert a.city == "Bengaluru"
+    assert a.country_code == "IN"
+    assert a.region is None
+    assert a.postal_code is None
+    assert a.label is None
+
+
+@pytest.mark.parametrize(
+    ("data", "reason", "field"),
+    [
+        ({"city": "X", "country_code": "US"}, "LINE1_REQUIRED", "line1"),
+        ({"line1": "L", "country_code": "US"}, "CITY_REQUIRED", "city"),
+        ({"line1": "L", "city": "X"}, "COUNTRY_CODE_REQUIRED", "country_code"),
+        (
+            {"line1": "L", "city": "X", "country_code": "ZZ"},
+            "COUNTRY_CODE_INVALID",
+            "country_code",
+        ),
+    ],
+)
+def test_address_invalid_reasons(data: dict, reason: str, field: str) -> None:
+    with pytest.raises(AddressInvalid) as exc:
+        validate_address(data)
+    assert exc.value.reason == reason
+    assert exc.value.field == field
+    assert exc.value.code == "ADDRESS_INVALID"
+
+
+def test_not_an_object() -> None:
+    for bad in (None, 42, "str", ["a"]):
+        with pytest.raises(AddressInvalid) as exc:
+            validate_address(bad)  # type: ignore[arg-type]
+        assert exc.value.reason == "NOT_AN_OBJECT"
+
+
+def test_is_valid_country_code() -> None:
+    assert is_valid_country_code("US") is True
+    assert is_valid_country_code("IN") is True
+    assert is_valid_country_code("GB") is True
+    assert is_valid_country_code("ZZ") is False
+    assert is_valid_country_code("us") is False  # lowercase not in the set
+    assert is_valid_country_code("USA") is False
+
+
+def test_is_valid_address() -> None:
+    assert is_valid_address({"line1": "L", "city": "C", "country_code": "FR"}) is True
+    assert is_valid_address({"line1": "L", "city": "C", "country_code": "XX"}) is False
+
+
+def test_pii_fields_tag() -> None:
+    assert ADDRESS_PII_FIELDS == ("line1", "line2", "city", "region", "postal_code")
+    assert "label" not in ADDRESS_PII_FIELDS
+    assert "country_code" not in ADDRESS_PII_FIELDS