geographicol 0.1.0__tar.gz

geographicol-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+coverage/
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.DS_Store

geographicol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 geographicol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geographicol-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: geographicol
+Version: 0.1.0
+Summary: Normalize Colombian addresses into a canonical, structured form. Zero dependencies.
+Project-URL: Repository, https://github.com/geographicol/geographicol
+Author: geographicol
+License-Expression: MIT
+License-File: LICENSE
+Keywords: address,address-normalization,colombia,dian,direccion,igac
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geographicol
+
+Normalize Colombian addresses into one canonical, structured form. Python 3.10+, zero dependencies.
+
+| Input | Canonical (`igac`, default) | `dian` style |
+|---|---|---|
+| `Cra 45 No 12 30 Loc 3` | `KR 45 12 30 LC 3` | `CR 45 12 30 LC 3` |
+| `cl. 26 nº 13-19` | `CL 26 13 19` | `CL 26 13 19` |
+| `Av. Cra 68 #22 - 47` | `AK 68 22 47` | `AK 68 22 47` |
+| `calle 38 a bis sur # 3A-18 este` | `CL 38A BIS SUR 3A 18 ESTE` | `CL 38A BIS SUR 3A 18 ESTE` |
+| `KR45#12-30` | `KR 45 12 30` | `CR 45 12 30` |
+| `Cll 147 No 7 70 To 2 Ap 501` | `CL 147 7 70 TO 2 APTO 501` | `CL 147 7 70 TO 2 AP 501` |
+| `Kr 43A # 1-50 Ed San Fernando Of 801` | `KR 43A 1 50 ED SAN FERNANDO OF 801` | `CR 43A 1 50 ED SAN FERNANDO OF 801` |
+| `Calle 8 # 530` | `CL 8 5 30`, confidence 0.8, warning `AMBIGUOUS_PLATE` | `CL 8 5 30` |
+
+## Install
+
+```sh
+pip install geographicol
+```
+
+## Usage
+
+```python
+from geographicol import is_valid, normalize, parse
+
+normalize("Cra 7 # 45-12 Torre 2 Apto 501")  # "KR 7 45 12 TO 2 APTO 501"
+normalize("Cra 7 # 45-12 Torre 2 Apto 501", style="dian")  # "CR 7 45 12 TO 2 AP 501"
+is_valid("Calle 45")  # False: no cross street
+```
+
+### Styles
+
+| `style` | Codes | Use it for |
+|---|---|---|
+| `"igac"` (default) | IGAC cadastral table: `KR`, `APTO`, `PI` | Cadastre, municipalities, general storage |
+| `"dian"` | DIAN table: `CR`, `AP`, `P` | RUT, tax forms, accounting and ERP software |
+| `"readable"` | Full words: `Carrera 7 # 45-12, Torre 2` | Showing addresses to people |
+
+Every style accepts codes from both tables as input. `strict=True` doubles every confidence penalty.
+
+## `ParsedAddress`
+
+```python
+parse("Cra 7 # 45-12 Torre 2 Apto 501, Bogotá")
+# ParsedAddress(
+#     street_type="KR", street_number=7, street_letter=None, street_quadrant=None,
+#     cross_number=45, cross_letter=None, cross_quadrant=None, plate_number=12,
+#     complements=[
+#         Complement(type="TORRE", code="TO", value="2"),
+#         Complement(type="APARTAMENTO", code="APTO", value="501"),
+#     ],
+#     locality="Bogotá", department=None,
+#     canonical="KR 7 45 12 TO 2 APTO 501",
+#     normalized="Carrera 7 # 45-12, Torre 2, Apartamento 501",
+#     confidence=1.0,
+#     warnings=["LOCALITY_UNVERIFIED"],
+#     raw="Cra 7 # 45-12 Torre 2 Apto 501, Bogotá",
+# )
+```
+
+`ParsedAddress` is a dataclass, so `dataclasses.asdict()` turns it into a plain dict. `parse` never raises. When it can't make sense of the input, it says so through `confidence` (0 to 1) and machine-readable `warnings` instead of guessing silently. The full rules, codes and warning list are in [`docs/nomenclature.md`](https://github.com/geographicol/geographicol/blob/main/docs/nomenclature.md).
+
+## What this library does NOT do
+
+It normalizes the *syntax* of an address, offline, from the string alone. It does not:
+
+- **Geocode:** no coordinates, no maps.
+- **Validate against real addresses:** `KR 999 999 99` parses fine even though it doesn't exist.
+- **Look up cities or neighbourhoods:** `locality` and `department` are captured as written and never checked (warning `LOCALITY_UNVERIFIED`).
+- **Fix typos or fuzzy-match:** `Carerra` is not recognized.
+
+Those need data and infrastructure, and will be part of the geographicol API.
+
+## License
+
+[MIT](https://github.com/geographicol/geographicol/blob/main/LICENSE)

geographicol-0.1.0/README.md

@@ -0,0 +1,77 @@
+# geographicol
+
+Normalize Colombian addresses into one canonical, structured form. Python 3.10+, zero dependencies.
+
+| Input | Canonical (`igac`, default) | `dian` style |
+|---|---|---|
+| `Cra 45 No 12 30 Loc 3` | `KR 45 12 30 LC 3` | `CR 45 12 30 LC 3` |
+| `cl. 26 nº 13-19` | `CL 26 13 19` | `CL 26 13 19` |
+| `Av. Cra 68 #22 - 47` | `AK 68 22 47` | `AK 68 22 47` |
+| `calle 38 a bis sur # 3A-18 este` | `CL 38A BIS SUR 3A 18 ESTE` | `CL 38A BIS SUR 3A 18 ESTE` |
+| `KR45#12-30` | `KR 45 12 30` | `CR 45 12 30` |
+| `Cll 147 No 7 70 To 2 Ap 501` | `CL 147 7 70 TO 2 APTO 501` | `CL 147 7 70 TO 2 AP 501` |
+| `Kr 43A # 1-50 Ed San Fernando Of 801` | `KR 43A 1 50 ED SAN FERNANDO OF 801` | `CR 43A 1 50 ED SAN FERNANDO OF 801` |
+| `Calle 8 # 530` | `CL 8 5 30`, confidence 0.8, warning `AMBIGUOUS_PLATE` | `CL 8 5 30` |
+
+## Install
+
+```sh
+pip install geographicol
+```
+
+## Usage
+
+```python
+from geographicol import is_valid, normalize, parse
+
+normalize("Cra 7 # 45-12 Torre 2 Apto 501")  # "KR 7 45 12 TO 2 APTO 501"
+normalize("Cra 7 # 45-12 Torre 2 Apto 501", style="dian")  # "CR 7 45 12 TO 2 AP 501"
+is_valid("Calle 45")  # False: no cross street
+```
+
+### Styles
+
+| `style` | Codes | Use it for |
+|---|---|---|
+| `"igac"` (default) | IGAC cadastral table: `KR`, `APTO`, `PI` | Cadastre, municipalities, general storage |
+| `"dian"` | DIAN table: `CR`, `AP`, `P` | RUT, tax forms, accounting and ERP software |
+| `"readable"` | Full words: `Carrera 7 # 45-12, Torre 2` | Showing addresses to people |
+
+Every style accepts codes from both tables as input. `strict=True` doubles every confidence penalty.
+
+## `ParsedAddress`
+
+```python
+parse("Cra 7 # 45-12 Torre 2 Apto 501, Bogotá")
+# ParsedAddress(
+#     street_type="KR", street_number=7, street_letter=None, street_quadrant=None,
+#     cross_number=45, cross_letter=None, cross_quadrant=None, plate_number=12,
+#     complements=[
+#         Complement(type="TORRE", code="TO", value="2"),
+#         Complement(type="APARTAMENTO", code="APTO", value="501"),
+#     ],
+#     locality="Bogotá", department=None,
+#     canonical="KR 7 45 12 TO 2 APTO 501",
+#     normalized="Carrera 7 # 45-12, Torre 2, Apartamento 501",
+#     confidence=1.0,
+#     warnings=["LOCALITY_UNVERIFIED"],
+#     raw="Cra 7 # 45-12 Torre 2 Apto 501, Bogotá",
+# )
+```
+
+`ParsedAddress` is a dataclass, so `dataclasses.asdict()` turns it into a plain dict. `parse` never raises. When it can't make sense of the input, it says so through `confidence` (0 to 1) and machine-readable `warnings` instead of guessing silently. The full rules, codes and warning list are in [`docs/nomenclature.md`](https://github.com/geographicol/geographicol/blob/main/docs/nomenclature.md).
+
+## What this library does NOT do
+
+It normalizes the *syntax* of an address, offline, from the string alone. It does not:
+
+- **Geocode:** no coordinates, no maps.
+- **Validate against real addresses:** `KR 999 999 99` parses fine even though it doesn't exist.
+- **Look up cities or neighbourhoods:** `locality` and `department` are captured as written and never checked (warning `LOCALITY_UNVERIFIED`).
+- **Fix typos or fuzzy-match:** `Carerra` is not recognized.
+
+Those need data and infrastructure, and will be part of the geographicol API.
+
+## License
+
+[MIT](https://github.com/geographicol/geographicol/blob/main/LICENSE)

geographicol-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "geographicol"
+version = "0.1.0"
+description = "Normalize Colombian addresses into a canonical, structured form. Zero dependencies."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "geographicol" }]
+keywords = ["colombia", "address", "address-normalization", "direccion", "igac", "dian"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/geographicol/geographicol"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff==0.16.8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/geographicol"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

geographicol-0.1.0/src/geographicol/__init__.py

@@ -0,0 +1,33 @@
+"""Normalize Colombian addresses into a canonical, structured form."""
+
+from __future__ import annotations
+
+from .parse import parse
+from .types import Complement, ComplementType, ParsedAddress, Quadrant, StreetType, Style
+
+__all__ = [
+    "Complement",
+    "ComplementType",
+    "ParsedAddress",
+    "Quadrant",
+    "StreetType",
+    "Style",
+    "is_valid",
+    "normalize",
+    "parse",
+]
+
+
+def normalize(input: str, style: Style = "igac", strict: bool = False) -> str:
+    """The canonical string for ``input``: ``parse(input, style, strict).canonical``."""
+    return parse(input, style=style, strict=strict).canonical
+
+
+def is_valid(input: str) -> bool:
+    """True when confidence is at least 0.7 and both the street and cross numbers are present."""
+    result = parse(input)
+    return (
+        result.confidence >= 0.7
+        and result.street_number is not None
+        and result.cross_number is not None
+    )

geographicol-0.1.0/src/geographicol/codes.py

@@ -0,0 +1,139 @@
+"""Every code table lives here, so a correction is a one-line change.
+
+See docs/nomenclature.md sections 3, 5, 7 and 9.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .types import ComplementType, Quadrant, StreetType
+
+# Input aliases, already normalized (lowercase, no accents). Multi-word aliases are space-separated.
+STREET_ALIASES: dict[StreetType, list[str]] = {
+    "CL": ["calle", "cll", "cl", "cle", "c"],
+    "KR": ["carrera", "cra", "cr", "kr", "kra", "k"],
+    "AV": ["avenida", "av", "avda"],
+    "AK": ["avenida carrera", "av carrera", "av cra", "av kr", "ak"],
+    "AC": ["avenida calle", "av calle", "av cl", "ac"],
+    "DG": ["diagonal", "diag", "dg"],
+    "TV": ["transversal", "transv", "trans", "tv", "tr"],
+    "CIR": ["circular", "circ", "cir", "cq"],
+    "CCV": ["circunvalar", "cvlar", "ccv", "crv", "cv"],
+    "AUTOP": ["autopista", "autop", "auto", "aut"],
+    "VIA": ["via"],
+    "KM": ["kilometro", "km"],
+}
+
+# Output codes and names per style.
+STREET_OUTPUT: dict[StreetType, dict[str, str]] = {
+    "CL": {"igac": "CL", "dian": "CL", "readable": "Calle"},
+    "KR": {"igac": "KR", "dian": "CR", "readable": "Carrera"},
+    "AV": {"igac": "AV", "dian": "AV", "readable": "Avenida"},
+    "AK": {"igac": "AK", "dian": "AK", "readable": "Avenida Carrera"},
+    "AC": {"igac": "AC", "dian": "AC", "readable": "Avenida Calle"},
+    "DG": {"igac": "DG", "dian": "DG", "readable": "Diagonal"},
+    "TV": {"igac": "TV", "dian": "TV", "readable": "Transversal"},
+    "CIR": {"igac": "CIR", "dian": "CIR", "readable": "Circular"},
+    "CCV": {"igac": "CCV", "dian": "CRV", "readable": "Circunvalar"},
+    "AUTOP": {"igac": "AUTOP", "dian": "AUT", "readable": "Autopista"},
+    "VIA": {"igac": "VIA", "dian": "VIA", "readable": "Vía"},
+    "KM": {"igac": "KM", "dian": "KM", "readable": "Kilómetro"},
+}
+
+QUADRANT_ALIASES: dict[str, Quadrant] = {
+    "sur": "SUR",
+    "este": "ESTE",
+    "norte": "NORTE",
+    "oeste": "OESTE",
+    "occidente": "OESTE",
+    "occ": "OESTE",
+}
+
+# Single-letter quadrants, only when standing alone.
+SINGLE_LETTER_QUADRANTS: dict[str, Quadrant] = {"s": "SUR", "e": "ESTE"}
+
+UNCOMMON_QUADRANTS: tuple[Quadrant, ...] = ("NORTE", "OESTE")
+
+# Words that stand for "número". Dropped.
+NUMBER_MARKERS: tuple[str, ...] = ("no", "n", "nro", "num", "numero")
+
+
+@dataclass(frozen=True)
+class ComplementCode:
+    type: ComplementType
+    igac: str
+    dian: str
+    readable: str
+    aliases: tuple[str, ...]
+    name_valued: bool = False
+    """Value runs to the next keyword, a comma or the end, instead of one token."""
+
+
+def _c(
+    type: ComplementType,
+    igac: str,
+    dian: str,
+    readable: str,
+    aliases: str,
+    name_valued: bool = False,
+) -> ComplementCode:
+    return ComplementCode(type, igac, dian, readable, tuple(aliases.split(",")), name_valued)
+
+
+COMPLEMENTS: list[ComplementCode] = [
+    _c("APARTAMENTO", "APTO", "AP", "Apartamento", "apartamento,aparta,apto,apt,ap"),
+    _c("TORRE", "TO", "TO", "Torre", "torre,to,tr"),
+    _c("LOCAL", "LC", "LC", "Local", "local,loc,lc,lo"),
+    _c("OFICINA", "OF", "OF", "Oficina", "oficina,ofi,ofc,of"),
+    _c("PISO", "PI", "P", "Piso", "piso,pi,p"),
+    _c("INTERIOR", "IN", "IN", "Interior", "interior,int,in"),
+    _c("BLOQUE", "BL", "BL", "Bloque", "bloque,blq,bl"),
+    _c("MANZANA", "MZ", "MZ", "Manzana", "manzana,mza,mz"),
+    _c("CASA", "CA", "CA", "Casa", "casa,ca"),
+    _c("ETAPA", "ET", "ET", "Etapa", "etapa,et"),
+    _c("CONJUNTO", "CONJ", "CONJ", "Conjunto", "conjunto,conj,cj", name_valued=True),
+    _c("EDIFICIO", "ED", "ED", "Edificio", "edificio,edif,ed", name_valued=True),
+    _c("BODEGA", "BG", "BG", "Bodega", "bodega,bod,bg"),
+    _c("LOTE", "LT", "LT", "Lote", "lote,lt"),
+    _c("BARRIO", "BR", "BRR", "Barrio", "barrio,brr,br,bo", name_valued=True),
+    # OTRO codes (section 9)
+    _c("OTRO", "PH", "PH", "Penthouse", "penthouse,ph"),
+    _c("OTRO", "GJ", "GJ", "Garaje", "garaje,gj"),
+    _c("OTRO", "SS", "SS", "Semisótano", "semisotano,ss"),
+    _c("OTRO", "CS", "CS", "Consultorio", "consultorio,cs"),
+    _c("OTRO", "UN", "UN", "Unidad", "unidad,un"),
+    _c("OTRO", "URB", "URB", "Urbanización", "urbanizacion,urb", name_valued=True),
+    _c("OTRO", "SEC", "SEC", "Sector", "sector,sec", name_valued=True),
+    _c("OTRO", "LM", "LM", "Local mezzanine", "local mezzanine,lm"),
+    _c("OTRO", "MN", "MN", "Mezzanine", "mezzanine,mn"),
+    _c("OTRO", "TZ", "TZ", "Terraza", "terraza,tz"),
+    _c("OTRO", "CECO", "CC", "Centro comercial", "centro comercial,ceco,cc", name_valued=True),
+    _c("OTRO", "SU", "SUITE", "Suite", "suite,su"),
+    _c("OTRO", "AGN", "AGP", "Agrupación", "agrupacion,agn,agp", name_valued=True),
+    _c("OTRO", "VDA", "VRD", "Vereda", "vereda,vda,vrd", name_valued=True),
+    _c("OTRO", "SMZ", "SM", "Supermanzana", "supermanzana,smz,sm"),
+    _c("OTRO", "PSJ", "PJ", "Pasaje", "pasaje,psj,pj"),
+    _c("OTRO", "PT", "POR", "Portería", "porteria,pt,por"),
+]
+
+COMPLEMENT_BY_IGAC: dict[str, ComplementCode] = {c.igac: c for c in COMPLEMENTS}
+
+# Confidence penalties (section 11).
+PENALTIES: dict[str, float] = {
+    "UNRECOGNIZED_STREET_TYPE": 0.5,
+    "MISSING_CROSS_NUMBER": 0.4,
+    "AMBIGUOUS_PLATE": 0.2,
+    "UNKNOWN_TOKEN": 0.15,
+    "RURAL_ADDRESS": 0.1,
+    "MISSING_PLATE_NUMBER": 0.2,
+    "MISSING_STREET_NUMBER": 0.4,
+    "NAMED_STREET": 0,
+    "AMBIGUOUS_STREET_TYPE": 0.1,
+    "AMBIGUOUS_QUADRANT": 0.05,
+    "UNCOMMON_QUADRANT": 0,
+    "LOCALITY_UNVERIFIED": 0,
+}
+
+# Warnings whose penalty applies once, however often they are raised.
+ONCE_ONLY: tuple[str, ...] = ("AMBIGUOUS_STREET_TYPE", "LOCALITY_UNVERIFIED")

geographicol-0.1.0/src/geographicol/parse.py

@@ -0,0 +1,315 @@
+"""The parsing procedure from docs/nomenclature.md section 12, step by step."""
+
+from __future__ import annotations
+
+from .codes import (
+    COMPLEMENTS,
+    NUMBER_MARKERS,
+    ONCE_ONLY,
+    PENALTIES,
+    QUADRANT_ALIASES,
+    SINGLE_LETTER_QUADRANTS,
+    STREET_ALIASES,
+    UNCOMMON_QUADRANTS,
+    ComplementCode,
+)
+from .render import render
+from .tokenize import Token, tokenize
+from .types import Complement, ParsedAddress, Quadrant, StreetType, Style
+
+# Street aliases as token lists, longest first so "avenida carrera" wins over "avenida".
+_STREET_MATCHERS: list[tuple[StreetType, list[str]]] = sorted(
+    (
+        (street_type, alias.split(" "))
+        for street_type, aliases in STREET_ALIASES.items()
+        for alias in aliases
+    ),
+    key=lambda m: -len(m[1]),
+)
+
+_COMPLEMENT_MATCHERS: list[tuple[ComplementCode, list[str]]] = sorted(
+    ((code, alias.split(" ")) for code in COMPLEMENTS for alias in code.aliases),
+    key=lambda m: -len(m[1]),
+)
+
+
+class _AddressParser:
+    def __init__(self, raw: str) -> None:
+        self.raw = raw
+        self.tokens: list[Token] = []
+        self.i = 0
+        self.a = ParsedAddress(raw=raw)
+        self.raised: list[str] = []
+        """Every warning occurrence, in order. Penalties are counted from this list."""
+
+    def run(self) -> None:
+        segments = self.raw.split(",")
+        self._parse_address_segment(segments[0])
+        for segment in segments[1:]:
+            self._parse_extra_segment(segment)
+
+        if self.a.locality is not None or self.a.department is not None:
+            self._warn("LOCALITY_UNVERIFIED")
+
+    def _warn(self, code: str) -> None:
+        self.raised.append(code)
+
+    def _peek(self, offset: int = 0) -> Token | None:
+        index = self.i + offset
+        return self.tokens[index] if index < len(self.tokens) else None
+
+    # Steps 5 to 9, on the text before the first comma.
+    def _parse_address_segment(self, text: str) -> None:
+        self.tokens = tokenize(text)
+        self.i = 0
+        a = self.a
+
+        a.street_type = self._parse_street_type()
+        if a.street_type is None:
+            self._warn("UNRECOGNIZED_STREET_TYPE")
+
+        if a.street_type is not None and self._is_named_street():
+            self._skip_street_name()
+            self._warn("NAMED_STREET")
+        else:
+            a.street_number = self._parse_number(3)
+            if a.street_number is not None:
+                a.street_letter = self._parse_suffix()
+                a.street_quadrant = self._parse_quadrant()
+        if a.street_number is None:
+            self._warn("MISSING_STREET_NUMBER")
+
+        if a.street_type == "KM":
+            self._warn("RURAL_ADDRESS")
+            # A KM address is a road location: the rest is the road description.
+            rest = self._peek()
+            if rest:
+                a.locality = text[rest.start :].strip()
+            self.i = len(self.tokens)
+        else:
+            self._parse_placa()
+
+        if a.cross_number is None:
+            self._warn("MISSING_CROSS_NUMBER")
+        elif a.plate_number is None:
+            self._warn("MISSING_PLATE_NUMBER")
+
+        self._parse_complements_and_leftovers(text, locality_allowed=True)
+
+    # Step 3: a later comma segment is complements, or else locality, then department.
+    def _parse_extra_segment(self, text: str) -> None:
+        self.tokens = tokenize(text)
+        self.i = 0
+        if not self.tokens:
+            return
+        if self._match_complement():
+            self._parse_complements_and_leftovers(text, locality_allowed=False)
+            return
+        value = text.strip()
+        if self.a.locality is None:
+            self.a.locality = value
+        elif self.a.department is None:
+            self.a.department = value
+        else:
+            for _ in self.tokens:
+                self._warn("UNKNOWN_TOKEN")
+
+    # Step 5.
+    def _parse_street_type(self) -> StreetType | None:
+        for street_type, words in _STREET_MATCHERS:
+            if self._matches_words(words):
+                self.i += len(words)
+                if len(words) == 1 and len(words[0]) == 1:
+                    self._warn("AMBIGUOUS_STREET_TYPE")
+                return street_type
+        return None
+
+    def _matches_words(self, words: list[str]) -> bool:
+        for k, word in enumerate(words):
+            token = self._peek(k)
+            if token is None or token.is_num or token.norm != word:
+                return False
+        return True
+
+    @staticmethod
+    def _is_number_marker(token: Token | None) -> bool:
+        return token is not None and not token.is_num and token.norm in NUMBER_MARKERS
+
+    def _is_named_street(self) -> bool:
+        """A word right after the street type, other than a number marker, starts a street name."""
+        token = self._peek()
+        return token is not None and not token.is_num and not self._is_number_marker(token)
+
+    def _skip_street_name(self) -> None:
+        while (token := self._peek()) and not token.is_num and not self._is_number_marker(token):
+            self.i += 1
+
+    def _parse_number(self, max_digits: int) -> int | None:
+        token = self._peek()
+        if token is None or not token.is_num or len(token.norm) > max_digits:
+            return None
+        self.i += 1
+        return int(token.norm)
+
+    # Letters and BIS after a number (section 4).
+    def _parse_suffix(self) -> str | None:
+        parts: list[str] = []
+        while (token := self._peek()) and not token.is_num:
+            if token.norm == "bis":
+                parts.append("BIS")
+            elif len(token.norm) == 1 and "a" <= token.norm <= "z":
+                # Standing alone, S and E are quadrants and N means "número".
+                if not token.attached and (
+                    token.norm in SINGLE_LETTER_QUADRANTS or token.norm == "n"
+                ):
+                    break
+                parts.append(token.norm.upper())
+            else:
+                break
+            self.i += 1
+        return " ".join(parts) if parts else None
+
+    # Section 5.
+    def _parse_quadrant(self) -> Quadrant | None:
+        token = self._peek()
+        if token is None or token.is_num:
+            return None
+        quadrant = QUADRANT_ALIASES.get(token.norm)
+        if quadrant is None and not token.attached:
+            quadrant = SINGLE_LETTER_QUADRANTS.get(token.norm)
+            if quadrant:
+                self._warn("AMBIGUOUS_QUADRANT")
+        if quadrant is None:
+            return None
+        if quadrant in UNCOMMON_QUADRANTS:
+            self._warn("UNCOMMON_QUADRANT")
+        self.i += 1
+        return quadrant
+
+    # Steps 6-7: number markers, cross street, plate (section 6).
+    def _parse_placa(self) -> None:
+        a = self.a
+        while self._is_number_marker(self._peek()):
+            self.i += 1
+
+        block = self._peek()
+        if block is None or not block.is_num:
+            return
+        if len(block.norm) >= 5:
+            return  # left for the leftovers step: UNKNOWN_TOKEN
+        self.i += 1
+        a.cross_letter = self._parse_suffix()
+        a.cross_quadrant = self._parse_quadrant()
+
+        plate = self._peek()
+        plate_follows = plate is not None and plate.is_num and len(plate.norm) <= 3
+        if (
+            not plate_follows
+            and a.cross_letter is None
+            and a.cross_quadrant is None
+            and len(block.norm) >= 3
+        ):
+            # Glued cross and plate: "1230" -> 12 and 30.
+            a.cross_number = int(block.norm[:-2])
+            a.plate_number = int(block.norm[-2:])
+            self._warn("AMBIGUOUS_PLATE")
+        else:
+            a.cross_number = int(block.norm)
+            if plate_follows and plate is not None:
+                self.i += 1
+                a.plate_number = int(plate.norm)
+        if a.cross_quadrant is None:
+            a.cross_quadrant = self._parse_quadrant()
+
+    def _match_complement(self) -> tuple[ComplementCode, int] | None:
+        for code, words in _COMPLEMENT_MATCHERS:
+            if not self._matches_words(words):
+                continue
+            alias = " ".join(words)
+            following = self._peek(len(words))
+            # "tr" is Torre only once the placa is parsed; "p" is Piso only before a number.
+            if alias == "tr" and self.a.cross_number is None:
+                continue
+            if alias == "p" and (following is None or not following.is_num):
+                continue
+            return code, len(words)
+        return None
+
+    # Steps 8-9.
+    def _parse_complements_and_leftovers(self, text: str, locality_allowed: bool) -> None:
+        while self._peek():
+            match = self._match_complement()
+            if match:
+                code, length = match
+                self.i += length
+                value = self._read_name_value() if code.name_valued else self._read_token_value()
+                if value is None:
+                    self._warn("UNKNOWN_TOKEN")
+                    continue
+                self.a.complements.append(Complement(type=code.type, code=code.igac, value=value))
+                continue
+
+            rest = self.tokens[self.i :]
+            all_words = all(not token.is_num for token in rest)
+            if (
+                locality_allowed
+                and all_words
+                and self.a.cross_number is not None
+                and self.a.locality is None
+            ):
+                self.a.locality = text[rest[0].start :].strip()
+                self.i = len(self.tokens)
+                return
+            self._warn("UNKNOWN_TOKEN")
+            self.i += 1
+
+    def _read_token_value(self) -> str | None:
+        """One token, plus any tokens attached to it: "501B"."""
+        first = self._peek()
+        if first is None or self._match_complement():
+            return None
+        value = first.orig
+        self.i += 1
+        while (token := self._peek()) and token.attached:
+            value += token.orig
+            self.i += 1
+        return value.upper()
+
+    def _read_name_value(self) -> str | None:
+        """Words up to the next complement keyword or the end: "SAN FERNANDO"."""
+        words: list[str] = []
+        while (token := self._peek()) and not self._match_complement():
+            words.append(token.orig)
+            self.i += 1
+        return " ".join(words).upper() if words else None
+
+
+def _score(raised: list[str], strict: bool) -> float:
+    penalty = 0.0
+    counted: set[str] = set()
+    for code in raised:
+        if code in ONCE_ONLY and code in counted:
+            continue
+        counted.add(code)
+        penalty += PENALTIES.get(code, 0)
+    if strict:
+        penalty *= 2
+    return min(1.0, max(0.0, 1 - penalty))
+
+
+def parse(input: str, style: Style = "igac", strict: bool = False) -> ParsedAddress:
+    """Parses a Colombian address.
+
+    Never raises: unparseable input gets confidence 0 and warnings instead.
+    """
+    if input.strip() == "":
+        return ParsedAddress(warnings=["EMPTY_INPUT"], raw=input)
+
+    parser = _AddressParser(input)
+    parser.run()
+    address = parser.a
+    address.canonical = render(address, style)
+    address.normalized = render(address, "readable")
+    address.confidence = _score(parser.raised, strict)
+    address.warnings = list(dict.fromkeys(parser.raised))
+    return address

geographicol-0.1.0/src/geographicol/render.py

@@ -0,0 +1,71 @@
+"""Output styles (docs/nomenclature.md section 10)."""
+
+from __future__ import annotations
+
+from .codes import COMPLEMENT_BY_IGAC, STREET_OUTPUT
+from .types import ParsedAddress, Style
+
+
+def _number_with_suffix(n: int, suffix: str | None, readable: bool) -> str:
+    """ "38" + "A BIS" -> "38A BIS": a leading single letter attaches to the number."""
+    if not suffix:
+        return str(n)
+    parts = suffix.split(" ")
+    if readable:
+        parts = ["Bis" if p == "BIS" else p for p in parts]
+    out = str(n)
+    if len(parts[0]) == 1:
+        out += parts[0]
+        parts = parts[1:]
+    return " ".join([out, *parts])
+
+
+def _title_case(word: str) -> str:
+    return word[0] + word[1:].lower()
+
+
+def _render_codes(a: ParsedAddress, style: str) -> str:
+    parts: list[str] = []
+    if a.street_type:
+        parts.append(STREET_OUTPUT[a.street_type][style])
+    if a.street_number is not None:
+        parts.append(_number_with_suffix(a.street_number, a.street_letter, False))
+    if a.street_quadrant:
+        parts.append(a.street_quadrant)
+    if a.cross_number is not None:
+        parts.append(_number_with_suffix(a.cross_number, a.cross_letter, False))
+    if a.plate_number is not None:
+        parts.append(str(a.plate_number))
+    if a.cross_quadrant:
+        parts.append(a.cross_quadrant)
+    for c in a.complements:
+        code = COMPLEMENT_BY_IGAC.get(c.code)
+        parts += [getattr(code, style) if code else c.code, c.value]
+    return " ".join(parts)
+
+
+def _render_readable(a: ParsedAddress) -> str:
+    head: list[str] = []
+    if a.street_type:
+        head.append(STREET_OUTPUT[a.street_type]["readable"])
+    if a.street_number is not None:
+        head.append(_number_with_suffix(a.street_number, a.street_letter, True))
+    if a.street_quadrant:
+        head.append(_title_case(a.street_quadrant))
+    out = " ".join(head)
+
+    if a.cross_number is not None:
+        cross = _number_with_suffix(a.cross_number, a.cross_letter, True)
+        if a.plate_number is not None:
+            cross += f"-{a.plate_number}"
+        if a.cross_quadrant:
+            cross += f" {_title_case(a.cross_quadrant)}"
+        out = f"{out} # {cross}" if out else f"# {cross}"
+    for c in a.complements:
+        code = COMPLEMENT_BY_IGAC.get(c.code)
+        out += f", {code.readable if code else c.code} {c.value}"
+    return out
+
+
+def render(address: ParsedAddress, style: Style) -> str:
+    return _render_readable(address) if style == "readable" else _render_codes(address, style)

geographicol-0.1.0/src/geographicol/tokenize.py

@@ -0,0 +1,85 @@
+"""Step 4 of the parsing procedure (docs/nomenclature.md section 12)."""
+
+from __future__ import annotations
+
+import unicodedata
+from dataclasses import dataclass
+from typing import Literal
+
+CharClass = Literal["letter", "digit", "separator"]
+
+_LETTERS = set("abcdefghijklmnopqrstuvwxyzñ")
+_DIGITS = set("0123456789")
+
+
+@dataclass(frozen=True)
+class Token:
+    norm: str
+    """Lowercase, accents stripped (ñ kept). Used for matching."""
+    orig: str
+    """The same characters as they appear in the input."""
+    is_num: bool
+    attached: bool
+    """True when no separator stands between this token and the previous one: the "A" in "45A"."""
+    start: int
+    end: int
+
+
+def normalize_char(char: str) -> str:
+    """Normalizes one character for matching."""
+    if char in ("ñ", "Ñ"):
+        return "ñ"
+    if char in ("º", "°"):
+        return "o"
+    decomposed = unicodedata.normalize("NFD", char)
+    # Drop every combining mark (Unicode category M), matching /\p{M}/u in the Node library.
+    return "".join(c for c in decomposed if not unicodedata.category(c).startswith("M")).lower()
+
+
+def _classify(norm: str) -> CharClass:
+    if norm in _LETTERS:
+        return "letter"
+    if norm in _DIGITS:
+        return "digit"
+    return "separator"
+
+
+def tokenize(text: str) -> list[Token]:
+    """Splits on spaces, "#", hyphens, dashes, periods and any other punctuation,
+    and on letter-digit boundaries: "KR45" -> "KR", "45" and "45A" -> "45", "A".
+    """
+    tokens: list[Token] = []
+    cls: CharClass | None = None
+    start = 0
+    norm = ""
+    last_end = -1
+
+    def flush(end: int) -> None:
+        nonlocal cls, last_end
+        if cls is None:
+            return
+        tokens.append(
+            Token(
+                norm=norm,
+                orig=text[start:end],
+                is_num=cls == "digit",
+                attached=bool(tokens) and start == last_end,
+                start=start,
+                end=end,
+            )
+        )
+        last_end = end
+        cls = None
+
+    for offset, char in enumerate(text):
+        char_norm = normalize_char(char)
+        char_cls = _classify(char_norm)
+        if char_cls == "separator":
+            flush(offset)
+        elif cls == char_cls:
+            norm += char_norm
+        else:
+            flush(offset)
+            cls, start, norm = char_cls, offset, char_norm
+    flush(len(text))
+    return tokens

geographicol-0.1.0/src/geographicol/types.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+StreetType = Literal["CL", "KR", "AV", "AK", "AC", "DG", "TV", "CIR", "CCV", "AUTOP", "VIA", "KM"]
+Quadrant = Literal["SUR", "ESTE", "NORTE", "OESTE"]
+ComplementType = Literal[
+    "APARTAMENTO",
+    "TORRE",
+    "LOCAL",
+    "OFICINA",
+    "PISO",
+    "INTERIOR",
+    "BLOQUE",
+    "MANZANA",
+    "CASA",
+    "ETAPA",
+    "CONJUNTO",
+    "EDIFICIO",
+    "BODEGA",
+    "LOTE",
+    "BARRIO",
+    "OTRO",
+]
+Style = Literal["igac", "dian", "readable"]
+
+
+@dataclass(frozen=True)
+class Complement:
+    type: ComplementType
+    code: str
+    """IGAC code, whatever the output style: "APTO", "TO", "PH", ..."""
+    value: str
+
+
+@dataclass
+class ParsedAddress:
+    # Vía principal
+    street_type: StreetType | None = None
+    street_number: int | None = None
+    street_letter: str | None = None
+    street_quadrant: Quadrant | None = None
+
+    # Placa
+    cross_number: int | None = None
+    cross_letter: str | None = None
+    cross_quadrant: Quadrant | None = None
+    plate_number: int | None = None
+
+    complements: list[Complement] = field(default_factory=list)
+
+    locality: str | None = None
+    department: str | None = None
+
+    canonical: str = ""
+    normalized: str = ""
+    confidence: float = 0.0
+    warnings: list[str] = field(default_factory=list)
+    raw: str = ""

geographicol-0.1.0/tests/test_fixtures.py

@@ -0,0 +1,53 @@
+import json
+import re
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from geographicol import parse
+
+FIXTURES_PATH = Path(__file__).resolve().parents[3] / "fixtures" / "addresses.json"
+FIXTURES: list[dict[str, Any]] = json.loads(FIXTURES_PATH.read_text(encoding="utf-8"))
+
+TOLERANCE = 1e-9
+STRING_KEYS = {"canonical", "canonicalDian", "normalized", "warnings"}
+CASES = [
+    pytest.param(group, input, id=f"{group['id']}[{index}]")
+    for group in FIXTURES
+    for index, input in enumerate(group["inputs"])
+]
+
+
+def snake_case(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+def test_at_least_60_groups_with_unique_ids() -> None:
+    assert len(FIXTURES) >= 60
+    assert len({group["id"] for group in FIXTURES}) == len(FIXTURES)
+
+
+@pytest.mark.parametrize(("group", "input"), CASES)
+def test_fixture(group: dict[str, Any], input: str) -> None:
+    result = parse(input)
+    fields = asdict(result)
+    expected = group["expected"]
+
+    for key, value in expected.items():
+        if key in STRING_KEYS:
+            continue
+        assert fields[snake_case(key)] == value, key
+    if "canonical" in expected:
+        assert result.canonical == expected["canonical"]
+    if "canonicalDian" in expected:
+        assert parse(input, style="dian").canonical == expected["canonicalDian"]
+    if "normalized" in expected:
+        assert result.normalized == expected["normalized"]
+    if "warnings" in expected:
+        assert sorted(result.warnings) == sorted(expected["warnings"])
+    if "minConfidence" in group:
+        assert result.confidence >= group["minConfidence"] - TOLERANCE
+    if "maxConfidence" in group:
+        assert result.confidence <= group["maxConfidence"] + TOLERANCE