postali-api 0.1.0__py3-none-any.whl

postali/__init__.py

@@ -0,0 +1,65 @@
+"""Cliente oficial de la API gratuita de códigos postales de Postali.
+
+México, Colombia y España. Sin API key, sin dependencias.
+
+    >>> from postali import Postali
+    >>> Postali("mx").cp("06700").asentamientos[0].nombre
+    'Roma Norte'
+
+Documentación de la API: https://postali.app/api/docs
+"""
+
+from ._client import (
+    BULK_MAX,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_USER_AGENT,
+    SEARCH_MAX_LENGTH,
+    Postali,
+)
+from ._errors import DOCS_URL, PostaliError
+from ._models import (
+    Asentamiento,
+    BulkItem,
+    BulkResult,
+    Colonia,
+    CpResult,
+    Estado,
+    EstadosResult,
+    MunicipioItem,
+    MunicipioResult,
+    MunicipiosResult,
+    SearchHit,
+    SearchResult,
+    ValidateResult,
+)
+from ._normalize import COUNTRIES, CP_LENGTH, normalize_cp
+from ._version import __version__
+
+__all__ = [
+    "Postali",
+    "PostaliError",
+    "normalize_cp",
+    "COUNTRIES",
+    "CP_LENGTH",
+    "BULK_MAX",
+    "SEARCH_MAX_LENGTH",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_USER_AGENT",
+    "DOCS_URL",
+    "Asentamiento",
+    "BulkItem",
+    "BulkResult",
+    "Colonia",
+    "CpResult",
+    "Estado",
+    "EstadosResult",
+    "MunicipioItem",
+    "MunicipioResult",
+    "MunicipiosResult",
+    "SearchHit",
+    "SearchResult",
+    "ValidateResult",
+    "__version__",
+]

postali/_client.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from ._errors import API_ERROR_CODES, PostaliError
+from ._models import (
+    BulkItem,
+    BulkResult,
+    CpResult,
+    Estado,
+    EstadosResult,
+    MunicipioResult,
+    MunicipiosResult,
+    SearchResult,
+    ValidateResult,
+)
+from ._normalize import COUNTRIES, normalize_cp
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://postali.app"
+DEFAULT_TIMEOUT = 10.0
+#: Máximo de códigos que acepta ``POST /bulk`` por petición.
+BULK_MAX = 100
+#: Longitud máxima de ``q`` en ``search``.
+SEARCH_MAX_LENGTH = 100
+# Cloudflare rechaza (403) el User-Agent por defecto de urllib ("Python-urllib/x.y").
+DEFAULT_USER_AGENT = f"postali-py/{__version__} (+https://postali.app)"
+
+_Timeout = Union[float, None]
+
+
+class Postali:
+    """Cliente síncrono de la API de Postali.
+
+    >>> from postali import Postali
+    >>> postali = Postali(country="mx")
+    >>> postali.cp("06700").municipio
+    'Cuauhtémoc'
+
+    :param country: ``"mx"`` (por defecto), ``"co"`` o ``"es"``.
+    :param base_url: URL base de la API. Por defecto ``https://postali.app``.
+    :param timeout: segundos por petición (``None`` = sin límite). Por defecto 10.
+    :param user_agent: cabecera ``User-Agent`` a enviar.
+    """
+
+    def __init__(
+        self,
+        country: str = "mx",
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: _Timeout = DEFAULT_TIMEOUT,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        if country not in COUNTRIES:
+            raise ValueError(f"País no soportado: {country!r}. Usa 'mx', 'co' o 'es'.")
+        self.country = country
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._root = f"{self.base_url}/api/v1/{country}"
+
+    def __repr__(self) -> str:
+        return f"Postali(country={self.country!r}, base_url={self.base_url!r})"
+
+    # ------------------------------------------------------------------ lookup
+
+    def cp(self, codigo: Union[str, int]) -> CpResult:
+        """Estado, municipio y asentamientos de un código postal.
+
+        Lanza ``PostaliError`` con ``code="not_found"`` si el CP no existe.
+        """
+        return CpResult.from_dict(self._get(f"/cp/{self._cp(codigo)}"))
+
+    def validate(self, codigo: Union[str, int]) -> ValidateResult:
+        """Comprueba si un CP existe. El resultado es *truthy* si es válido."""
+        return ValidateResult.from_dict(self._get(f"/validate/{self._cp(codigo)}"))
+
+    # ------------------------------------------------------------------ search
+
+    def search(self, q: str, *, limit: Optional[int] = None) -> SearchResult:
+        """Búsqueda difusa por colonia, municipio o CP (para autocompletar)."""
+        query = q.strip() if isinstance(q, str) else ""
+        if not query:
+            raise PostaliError("invalid_query", "La búsqueda está vacía.", status=400)
+        if len(query) > SEARCH_MAX_LENGTH:
+            raise PostaliError(
+                "invalid_query", f"La búsqueda excede {SEARCH_MAX_LENGTH} caracteres.", status=400
+            )
+        params: List[Tuple[str, str]] = [("q", query)]
+        if limit is not None:
+            params.append(("limit", str(int(limit))))
+        return SearchResult.from_dict(self._get(f"/search?{urllib.parse.urlencode(params)}"))
+
+    # --------------------------------------------------------------- geografía
+
+    def estados(self) -> EstadosResult:
+        """Regiones de nivel 1 (estados / departamentos / provincias)."""
+        return EstadosResult.from_dict(self._get("/estados"))
+
+    def estado(self, slug: str) -> Estado:
+        """Detalle de una región."""
+        return Estado.from_dict(self._get(f"/estado/{_slug(slug, 'estado')}"))
+
+    def municipios(self, estado_slug: str) -> MunicipiosResult:
+        """Municipios de una región, ordenados por nombre."""
+        return MunicipiosResult.from_dict(
+            self._get(f"/estado/{_slug(estado_slug, 'estado')}/municipios")
+        )
+
+    def municipio(self, estado_slug: str, municipio_slug: str) -> MunicipioResult:
+        """Asentamientos de un municipio (máx. 1000; ver ``truncated``)."""
+        return MunicipioResult.from_dict(
+            self._get(
+                f"/municipio/{_slug(estado_slug, 'estado')}/{_slug(municipio_slug, 'municipio')}"
+            )
+        )
+
+    # -------------------------------------------------------------------- bulk
+
+    def bulk(self, codigos: Sequence[Union[str, int]]) -> BulkResult:
+        """Resuelve muchos CPs a la vez.
+
+        Normaliza cada código, marca como ``valid=False`` los que no tienen
+        formato válido (sin enviarlos) y parte la lista en lotes de 100.
+        Los resultados conservan el orden de entrada.
+        """
+        if isinstance(codigos, (str, bytes)) or not codigos:
+            raise PostaliError("invalid_query", "`codigos` debe ser una lista no vacía.", status=400)
+        results: List[Optional[BulkItem]] = [None] * len(codigos)
+        pending: List[Tuple[int, str]] = []
+        for i, raw in enumerate(codigos):
+            cp = normalize_cp(raw, self.country)
+            if cp is None:
+                results[i] = BulkItem(cp=str(raw), valid=False)
+            else:
+                pending.append((i, cp))
+        for start in range(0, len(pending), BULK_MAX):
+            chunk = pending[start : start + BULK_MAX]
+            data = self._request("POST", "/bulk", {"cps": [cp for _, cp in chunk]})
+            items = data.get("results", []) if isinstance(data, dict) else []
+            for j, (i, cp) in enumerate(chunk):
+                results[i] = BulkItem.from_dict(items[j]) if j < len(items) else BulkItem(cp=cp, valid=False)
+        final = [r if r is not None else BulkItem(cp="", valid=False) for r in results]
+        return BulkResult(total=len(final), results=final)
+
+    # ---------------------------------------------------------------- internos
+
+    def _cp(self, codigo: Union[str, int]) -> str:
+        cp = normalize_cp(codigo, self.country)
+        if cp is None:
+            raise PostaliError(
+                "invalid_cp",
+                f"{codigo!r} no tiene el formato de CP de {self.country.upper()}.",
+                status=400,
+            )
+        return cp
+
+    def _get(self, path: str) -> Dict[str, Any]:
+        return self._request("GET", path)
+
+    def _request(self, method: str, path: str, body: Any = None) -> Dict[str, Any]:
+        headers = {"User-Agent": self.user_agent, "Accept": "application/json"}
+        data: Optional[bytes] = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(self._root + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                status = resp.status
+                raw = resp.read()
+        except urllib.error.HTTPError as e:
+            try:
+                raw_err = e.read()
+            except Exception:
+                raw_err = b""
+            raise _to_error(e.code, raw_err) from None
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, (socket.timeout, TimeoutError)):
+                raise self._timeout_error() from e
+            raise PostaliError(
+                "network_error", f"No se pudo contactar con Postali: {e.reason}"
+            ) from e
+        except (socket.timeout, TimeoutError) as e:
+            raise self._timeout_error() from e
+        except OSError as e:
+            raise PostaliError("network_error", f"No se pudo contactar con Postali: {e}") from e
+
+        parsed = _parse_json(raw)
+        if not isinstance(parsed, dict):
+            raise PostaliError("http_error", "Respuesta de Postali vacía o no es JSON.", status=status)
+        return parsed
+
+    def _timeout_error(self) -> PostaliError:
+        return PostaliError("timeout", f"La petición a Postali superó {self.timeout} s.")
+
+
+def _slug(value: str, name: str) -> str:
+    s = value.strip() if isinstance(value, str) else ""
+    if not s:
+        raise PostaliError("invalid_query", f"Falta `{name}`.", status=400)
+    return urllib.parse.quote(s, safe="")
+
+
+def _parse_json(raw: bytes) -> Any:
+    try:
+        return json.loads(raw.decode("utf-8")) if raw else None
+    except (ValueError, UnicodeDecodeError):
+        return None
+
+
+def _to_error(status: int, raw: bytes) -> PostaliError:
+    data = _parse_json(raw)
+    err = data.get("error") if isinstance(data, dict) else None
+    if isinstance(err, dict) and isinstance(err.get("code"), str):
+        code = err["code"] if err["code"] in API_ERROR_CODES else "http_error"
+        raw_msg, raw_docs = err.get("message"), err.get("docs_url")
+        message = raw_msg if isinstance(raw_msg, str) else f"HTTP {status}"
+        docs = raw_docs if isinstance(raw_docs, str) else None
+        return PostaliError(code, message, status=status, docs_url=docs)
+    if status == 404:
+        code = "not_found"
+    elif status == 429:
+        code = "rate_limited"
+    elif status >= 500:
+        code = "internal_error"
+    else:
+        code = "http_error"
+    snippet = raw[:200].decode("utf-8", "replace").strip()
+    msg = f"HTTP {status}" + (f": {snippet}" if snippet and not snippet.startswith("<") else "")
+    return PostaliError(code, msg, status=status)

postali/_errors.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Optional
+
+DOCS_URL = "https://postali.app/api/docs#errors"
+
+#: Códigos que devuelve la API en ``{"error": {"code": ...}}``.
+API_ERROR_CODES = frozenset(
+    {"invalid_cp", "invalid_query", "not_found", "rate_limited", "internal_error"}
+)
+
+
+class PostaliError(Exception):
+    """Error de la API de Postali o del transporte.
+
+    ``code`` es uno de:
+
+    - ``invalid_cp``, ``invalid_query``, ``not_found``, ``rate_limited``,
+      ``internal_error``: los devuelve la API.
+    - ``timeout``: se superó el timeout.
+    - ``network_error``: no se pudo conectar (DNS, TLS, conexión rechazada…).
+    - ``http_error``: respuesta no exitosa sin cuerpo de error reconocible.
+
+    ``status`` es el status HTTP, o ``0`` si no hubo respuesta.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status: int = 0,
+        docs_url: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.docs_url = docs_url or DOCS_URL
+
+    def __repr__(self) -> str:
+        return f"PostaliError(code={self.code!r}, status={self.status}, message={self.message!r})"

postali/_models.py

@@ -0,0 +1,256 @@
+"""Modelos de respuesta.
+
+Son ``dataclasses`` inmutables con los mismos nombres de campo que el JSON de
+la API, así que ``r.asentamientos[0].nombre`` funciona igual que en la
+documentación. ``from_dict`` ignora campos desconocidos para que una versión
+nueva de la API no rompa clientes antiguos.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Mapping, Optional
+
+
+def _opt_str(d: Mapping[str, Any], key: str) -> Optional[str]:
+    v = d.get(key)
+    return v if isinstance(v, str) else None
+
+
+@dataclass(frozen=True)
+class Asentamiento:
+    """Colonia, fraccionamiento, barrio o zona postal dentro de un CP."""
+
+    nombre: str
+    tipo: str
+    asenta_slug: str
+    ciudad: Optional[str] = None  #: ``None`` en CO y ES.
+    zona: Optional[str] = None  #: ``"Urbano"`` / ``"Rural"``; ``None`` en CO y ES.
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "Asentamiento":
+        return cls(
+            nombre=d["nombre"],
+            tipo=d["tipo"],
+            asenta_slug=d["asenta_slug"],
+            ciudad=_opt_str(d, "ciudad"),
+            zona=_opt_str(d, "zona"),
+        )
+
+
+@dataclass(frozen=True)
+class CpResult:
+    """Respuesta de ``GET /api/v1/{country}/cp/{codigo}``."""
+
+    cp: str
+    estado: str
+    estado_slug: str
+    municipio: str
+    municipio_slug: str
+    asentamientos: List[Asentamiento] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "CpResult":
+        return cls(
+            cp=d["cp"],
+            estado=d["estado"],
+            estado_slug=d["estado_slug"],
+            municipio=d["municipio"],
+            municipio_slug=d["municipio_slug"],
+            asentamientos=[Asentamiento.from_dict(a) for a in d.get("asentamientos", [])],
+        )
+
+
+@dataclass(frozen=True)
+class ValidateResult:
+    """Respuesta de ``GET /api/v1/{country}/validate/{codigo}``."""
+
+    cp: str
+    valid: bool
+    asentamientos: int  #: Número de asentamientos que cubre el CP.
+
+    def __bool__(self) -> bool:
+        return self.valid
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "ValidateResult":
+        return cls(cp=d["cp"], valid=bool(d["valid"]), asentamientos=int(d["asentamientos"]))
+
+
+@dataclass(frozen=True)
+class SearchHit:
+    cp: str
+    nombre: str
+    tipo: str
+    municipio: str
+    estado: str
+    estado_slug: str
+    municipio_slug: str
+    asenta_slug: str
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "SearchHit":
+        return cls(
+            cp=d["cp"],
+            nombre=d["nombre"],
+            tipo=d["tipo"],
+            municipio=d["municipio"],
+            estado=d["estado"],
+            estado_slug=d["estado_slug"],
+            municipio_slug=d["municipio_slug"],
+            asenta_slug=d["asenta_slug"],
+        )
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    """Respuesta de ``GET /api/v1/{country}/search``."""
+
+    query: str
+    results: List[SearchHit] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "SearchResult":
+        return cls(query=d["query"], results=[SearchHit.from_dict(h) for h in d.get("results", [])])
+
+
+@dataclass(frozen=True)
+class Estado:
+    """Región de nivel 1: estado (MX), departamento (CO) o provincia (ES)."""
+
+    nombre: str
+    slug: str
+    total_asentamientos: int
+    total_municipios: int
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "Estado":
+        return cls(
+            nombre=d["nombre"],
+            slug=d["slug"],
+            total_asentamientos=int(d["total_asentamientos"]),
+            total_municipios=int(d["total_municipios"]),
+        )
+
+
+@dataclass(frozen=True)
+class EstadosResult:
+    """Respuesta de ``GET /api/v1/{country}/estados``."""
+
+    total: int
+    estados: List[Estado] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "EstadosResult":
+        return cls(total=int(d["total"]), estados=[Estado.from_dict(e) for e in d.get("estados", [])])
+
+
+@dataclass(frozen=True)
+class MunicipioItem:
+    nombre: str
+    slug: str
+    total_asentamientos: int
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "MunicipioItem":
+        return cls(nombre=d["nombre"], slug=d["slug"], total_asentamientos=int(d["total_asentamientos"]))
+
+
+@dataclass(frozen=True)
+class MunicipiosResult:
+    """Respuesta de ``GET /api/v1/{country}/estado/{slug}/municipios``."""
+
+    estado: str
+    estado_slug: str
+    total: int
+    municipios: List[MunicipioItem] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "MunicipiosResult":
+        return cls(
+            estado=d["estado"],
+            estado_slug=d["estado_slug"],
+            total=int(d["total"]),
+            municipios=[MunicipioItem.from_dict(m) for m in d.get("municipios", [])],
+        )
+
+
+@dataclass(frozen=True)
+class Colonia:
+    """Asentamiento dentro de un municipio (incluye su CP)."""
+
+    cp: str
+    nombre: str
+    tipo: str
+    asenta_slug: str
+    ciudad: Optional[str] = None
+    zona: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "Colonia":
+        return cls(
+            cp=d["cp"],
+            nombre=d["nombre"],
+            tipo=d["tipo"],
+            asenta_slug=d["asenta_slug"],
+            ciudad=_opt_str(d, "ciudad"),
+            zona=_opt_str(d, "zona"),
+        )
+
+
+@dataclass(frozen=True)
+class MunicipioResult:
+    """Respuesta de ``GET /api/v1/{country}/municipio/{estado}/{municipio}``."""
+
+    estado: str
+    estado_slug: str
+    municipio: str
+    municipio_slug: str
+    total_asentamientos: int
+    truncated: bool  #: ``True`` si hay más de 1000 asentamientos y la lista se recortó.
+    colonias: List[Colonia] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "MunicipioResult":
+        return cls(
+            estado=d["estado"],
+            estado_slug=d["estado_slug"],
+            municipio=d["municipio"],
+            municipio_slug=d["municipio_slug"],
+            total_asentamientos=int(d["total_asentamientos"]),
+            truncated=bool(d["truncated"]),
+            colonias=[Colonia.from_dict(c) for c in d.get("colonias", [])],
+        )
+
+
+@dataclass(frozen=True)
+class BulkItem:
+    """Resultado individual de ``bulk``."""
+
+    cp: str
+    valid: bool
+    asentamientos: int = 0
+    estado: Optional[str] = None
+    estado_slug: Optional[str] = None
+    municipio: Optional[str] = None
+    municipio_slug: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> "BulkItem":
+        return cls(
+            cp=d["cp"],
+            valid=bool(d["valid"]),
+            asentamientos=int(d.get("asentamientos") or 0),
+            estado=_opt_str(d, "estado"),
+            estado_slug=_opt_str(d, "estado_slug"),
+            municipio=_opt_str(d, "municipio"),
+            municipio_slug=_opt_str(d, "municipio_slug"),
+        )
+
+
+@dataclass(frozen=True)
+class BulkResult:
+    """Respuesta de ``POST /api/v1/{country}/bulk`` (mismo orden que la entrada)."""
+
+    total: int
+    results: List[BulkItem] = field(default_factory=list)

postali/_normalize.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import re
+from typing import Dict, Optional, Tuple, Union
+
+#: Países soportados (ISO 3166-1 alfa-2, minúsculas).
+COUNTRIES: Tuple[str, ...] = ("mx", "co", "es")
+
+#: Longitud del código postal por país.
+CP_LENGTH: Dict[str, int] = {"mx": 5, "co": 6, "es": 5}
+
+_WS = re.compile(r"\s+")
+
+
+def normalize_cp(value: Union[str, int], country: str = "mx") -> Optional[str]:
+    """Normaliza un código postal.
+
+    - Acepta ``str`` o ``int``.
+    - Quita espacios.
+    - Restaura el cero inicial que Excel, un CSV o ``int()`` suelen comerse:
+      ``"6700"`` → ``"06700"`` (MX), ``"8001"`` → ``"08001"`` (ES),
+      ``"50001"`` → ``"050001"`` (CO).
+
+    Se añade como máximo **un** cero y nunca delante de otro cero: en los tres
+    países ningún CP empieza por ``00``, así que una entrada más corta es un CP
+    incompleto, no uno recortado.
+
+    Devuelve ``None`` si el resultado no tiene el formato del país.
+    """
+    if country not in CP_LENGTH:
+        raise ValueError(f"País no soportado: {country!r}. Usa 'mx', 'co' o 'es'.")
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        return None
+    length = CP_LENGTH[country]
+    cp = _WS.sub("", str(value))
+    if not cp.isascii() or not cp.isdigit():
+        return None
+    if len(cp) == length - 1 and not cp.startswith("0"):
+        cp = "0" + cp
+    return cp if len(cp) == length else None

postali/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

postali_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: postali-api
+Version: 0.1.0
+Summary: Cliente oficial de la API gratuita de códigos postales de Postali (México, Colombia, España). Sin dependencias.
+Project-URL: Homepage, https://postali.app
+Project-URL: Documentation, https://postali.app/api/docs
+Project-URL: Repository, https://github.com/gomflo/postali-py
+Project-URL: Issues, https://github.com/gomflo/postali-py/issues
+Author-email: Postali <hi@postali.app>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,codigo postal,colombia,colonias,cp,códigos postales,geonames,mexico,postal code,sepomex,spain,zip code
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# postali
+
+Cliente oficial para Python de la **API gratuita de códigos postales de [Postali](https://postali.app)**: México, Colombia y España.
+
+- Sin API key, sin registro, sin cuota mensual.
+- Cero dependencias: sólo la biblioteca estándar (`urllib`). Python 3.9+.
+- Respuestas tipadas como `dataclasses` inmutables (`py.typed` incluido).
+- Restaura el cero inicial que se pierde en Excel, un CSV o `int()` (`6700` → `"06700"`).
+
+**Documentación de la API:** https://postali.app/api/docs · **Sitio:** https://postali.app
+
+## Instalación
+
+```bash
+pip install postali-api
+```
+
+El paquete se instala como `postali-api` y se importa como `postali`.
+
+## Uso rápido
+
+```python
+from postali import Postali
+
+postali = Postali("mx")
+print(postali.cp("06700").asentamientos[0].nombre)  # Roma Norte
+```
+
+## Ejemplos
+
+### Autocompletar la colonia en un formulario de dirección
+
+Un endpoint de tu backend (aquí con Flask) que el formulario llama cuando el usuario termina de escribir el CP:
+
+```python
+from flask import Flask, jsonify
+from postali import Postali, PostaliError
+
+app = Flask(__name__)
+postali = Postali("mx")
+
+@app.get("/direccion/<cp>")
+def direccion(cp: str):
+    try:
+        r = postali.cp(cp)  # "6700" también funciona
+    except PostaliError as e:
+        if e.code in ("not_found", "invalid_cp"):
+            return jsonify(error="CP no encontrado"), 404
+        raise
+    return jsonify(
+        estado=r.estado,
+        municipio=r.municipio,
+        colonias=[a.nombre for a in r.asentamientos],
+    )
+```
+
+¿Buscas por nombre de colonia en lugar de CP?
+
+```python
+for hit in postali.search("roma norte", limit=5).results:
+    print(hit.cp, hit.nombre, hit.municipio, hit.estado)
+```
+
+### Validar un CP
+
+```python
+if not postali.validate("06700"):   # ValidateResult es truthy si el CP existe
+    raise ValueError("Ese código postal no existe.")
+```
+
+`validate` lanza `PostaliError` con `code == "invalid_cp"` si el texto ni siquiera tiene formato de CP (p. ej. `"abc"`), sin hacer la petición.
+
+### Limpiar una columna de CPs (CSV / pandas)
+
+```python
+r = postali.bulk(["06700", "44100", 6700, "abc"])
+for item in r.results:           # mismo orden que la entrada
+    print(item.cp, item.valid, item.municipio)
+# 06700 True Cuauhtémoc · 44100 True Guadalajara · 06700 True Cuauhtémoc · abc False None
+```
+
+`bulk` normaliza cada código, marca los que no tienen formato válido como `valid=False` y parte la lista en lotes de 100.
+
+### Colombia y España
+
+```python
+Postali("co").cp("050001").municipio   # 'Medellín'
+Postali("es").cp(8001).municipio       # "08001" → 'Barcelona'
+```
+
+## API
+
+`Postali(country="mx", *, base_url="https://postali.app", timeout=10.0, user_agent=...)`
+
+| Método | Endpoint | Devuelve |
+|---|---|---|
+| `cp(codigo)` | `GET /api/v1/{country}/cp/{codigo}` | `CpResult` |
+| `validate(codigo)` | `GET /api/v1/{country}/validate/{codigo}` | `ValidateResult` |
+| `search(q, limit=None)` | `GET /api/v1/{country}/search?q=` | `SearchResult` |
+| `estados()` | `GET /api/v1/{country}/estados` | `EstadosResult` |
+| `estado(slug)` | `GET /api/v1/{country}/estado/{slug}` | `Estado` |
+| `municipios(estado_slug)` | `GET /api/v1/{country}/estado/{slug}/municipios` | `MunicipiosResult` |
+| `municipio(estado_slug, municipio_slug)` | `GET /api/v1/{country}/municipio/{estado}/{municipio}` | `MunicipioResult` |
+| `bulk(codigos)` | `POST /api/v1/{country}/bulk` | `BulkResult` |
+
+"Estado" es el nivel 1 de cada país: estado en México, departamento en Colombia, provincia en España. Los campos de cada resultado se llaman igual que en el JSON de la API.
+
+### Errores
+
+Todo error de la API o de red se lanza como `PostaliError`, con `code`, `status`, `message` y `docs_url`:
+
+```python
+from postali import PostaliError
+
+try:
+    postali.cp("00000")
+except PostaliError as e:
+    print(e.code, e.status, e.message)  # not_found 404 No se encontró el recurso solicitado.
+```
+
+| `code` | Cuándo |
+|---|---|
+| `invalid_cp` | El CP no tiene el formato del país |
+| `invalid_query` | Falta `q`, está vacía o hay un parámetro inválido |
+| `not_found` | El CP, estado o municipio no existe |
+| `rate_limited` | Demasiadas peticiones desde tu IP |
+| `internal_error` | Error del servidor (5xx) |
+| `timeout` | Se superó el `timeout` |
+| `network_error` | No se pudo conectar |
+| `http_error` | Otra respuesta no exitosa |
+
+### Normalización de CPs
+
+```python
+from postali import normalize_cp
+
+normalize_cp("6700")          # '06700'
+normalize_cp(" 76 148 ")      # '76148'
+normalize_cp("50001", "co")   # '050001'
+normalize_cp("670")           # None (incompleto)
+```
+
+Se añade como máximo un cero, y nunca delante de otro cero: ningún CP de México, Colombia o España empieza por `00`.
+
+## Datos y atribución
+
+Datos: Sepomex vía [Postali](https://postali.app) / GeoNames ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)) para CO y ES.
+
+## English
+
+`postali` is the official zero-dependency Python client (stdlib `urllib`, Python 3.9+) for the free [Postali](https://postali.app) postal-code API covering Mexico, Colombia and Spain. No API key required.
+
+```python
+from postali import Postali
+r = Postali("mx").cp("06700")          # "mx" | "co" | "es"
+print(r.estado, r.municipio, [a.nombre for a in r.asentamientos])
+```
+
+Responses are typed frozen dataclasses; errors raise `PostaliError` with `code` (`invalid_cp`, `not_found`, `rate_limited`, `timeout`…), `status` and `docs_url`. Postal codes that lost their leading zero (`6700`) are restored automatically. API reference: https://postali.app/api/docs
+
+Data: Sepomex via Postali / GeoNames (CC BY 4.0) for CO and ES.
+
+## Licencia
+
+MIT © Postali

postali_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+postali/__init__.py,sha256=Pi0KqTUCct3L5wbS4GxD8ckLfTLo-vNMuxtxTk_Ckvc,1330
+postali/_client.py,sha256=e-_hLEzxP8wbm0xQl6uWWJ8DtUnjzEx-wZTl1UqP3fM,9577
+postali/_errors.py,sha256=R3A0WfW2_W_nL85rjXuihAzoHp7--csw-QDlCgSLO-c,1258
+postali/_models.py,sha256=lZvFNylY_mlBOVqHyLeU540qZZWB91OkdROIEt8GjiM,7224
+postali/_normalize.py,sha256=lcWHbmLV1MbZVrZeqg_M8iRnUz36us9dcsHCr2ZxnCA,1426
+postali/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+postali/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+postali_api-0.1.0.dist-info/METADATA,sha256=TjwKRWptH8CmPDOuXlpfumFi5fTEAaAaK4FA_OAKskY,7060
+postali_api-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+postali_api-0.1.0.dist-info/licenses/LICENSE,sha256=2D5CDjLSink4hYeKI8tJ0V9UnEdloIjpsY0crBHYX7s,1081
+postali_api-0.1.0.dist-info/RECORD,,

postali_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

postali_api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postali <hi@postali.app>
+
+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.