"""unsprawl.core.regions.
A nested namespace for region codes that supports IDE auto-complete.
Target syntax
-------------
- `Region.SG`
- `Region.US.CA.SF`
Each node exposes:
- `.CODE` : a hyphenated ISO-like identifier (e.g., 'US-CA-SF')
- `.DOT` : a dot-serialized identifier (e.g., 'US.CA.SF')
Design notes
------------
This is intentionally *data-light* and import-safe.
It is a convenience namespace, not a database of the world.
"""
from __future__ import annotations
from dataclasses import dataclass
[docs]
@dataclass(frozen=True, slots=True)
class _RegionNode:
"""Immutable region node.
The node stores a tuple of path segments, e.g. ('US', 'CA', 'SF').
"""
_parts: tuple[str, ...]
@property
def CODE(self) -> str: # noqa: N802 (public contract)
"""Hyphenated region code (default serialization)."""
return "-".join(self._parts)
@property
def DOT(self) -> str: # noqa: N802 (public contract)
"""Dot-serialized region code."""
return ".".join(self._parts)
[docs]
def __str__(self) -> str:
return self.CODE
[docs]
class _RegionNamespace:
"""A simple namespace that supports attribute chaining.
This pattern keeps the ergonomics of `Region.US.CA.SF` without needing
metaclasses or dynamic module generation.
"""
# Singapore
SG = _RegionNode(("SG",))
[docs]
class US: # noqa: D106 (namespace)
CODE = "US" # for parity; rarely used
DOT = "US"
[docs]
class CA: # noqa: D106 (namespace)
CODE = "US-CA"
DOT = "US.CA"
# San Francisco (county/city placeholder)
SF = _RegionNode(("US", "CA", "SF"))
# Public exports
Region = _RegionNamespace()
RegionNode = _RegionNode