peru-ubigeo 1.0.0

Consulta y validación de códigos ubigeo peruanos (INEI + RENIEC) para integraciones SUNAT.

peru-ubigeo

Librería Python agnóstica de framework para consulta y validación de códigos ubigeo peruanos. Diseñada para integración con librerías de documentos electrónicos SUNAT (einvoice, GRE, SIRE, CPE).

---

Características

• Sistema de código dual — códigos INEI + RENIEC con mapeo por distrito
• Modelos Pydantic v2 — Country, Department, Province, District, tipo validado UbigeoCode
• Sin dependencia de framework — Python puro; compatible con FastAPI, Django, Tryton o scripts independientes
• Arquitectura Hexagonal — cambia la fuente de datos sin tocar la lógica de negocio
• Datos embebidos estáticos — sin llamadas a red; los datos se actualizan con cada nueva versión del paquete
• Tipado completo — PEP 561 (py.typed), compatible con mypy modo estricto
• Python 3.11+ — tipado moderno en todo el código

---

Instalación

pip install peru-ubigeo

---

Inicio rápido

from peru_ubigeo import UbigeoRegistry

registry = UbigeoRegistry()

# ── Búsqueda ──────────────────────────────────────────────────────────
district = registry.get_by_code("150101")        # INEI (por defecto)
print(district.name)                             # LIMA
print(district.department_code)                  # 15
print(district.province_code)                    # 1501

district = registry.get_by_reniec_code("150101") # búsqueda RENIEC

# ── Consultas jerárquicas ─────────────────────────────────────────────
departments = registry.get_departments()          # list[Department] — 25 en total
provinces   = registry.get_provinces("15")        # list[Province]
districts   = registry.get_districts("15", "01") # list[District]

# ── Validación ───────────────────────────────────────────────────────
registry.is_valid_code("150101")   # True
registry.is_valid_code("XXXXXX")   # False

# ── Normalización ────────────────────────────────────────────────────
registry.normalize(" 150101 ")     # "150101"  (elimina espacios)
registry.normalize("10101")        # "010101"  (rellena con ceros a la izquierda)

---

Arquitectura

peru_ubigeo/
├── __init__.py                # API pública
├── py.typed                   # Marcador PEP 561
├── domain/
│   ├── __init__.py
│   ├── models.py              # Modelos Pydantic v2 + tipo UbigeoCode
│   ├── exceptions.py          # Jerarquía UbigeoError
│   └── ports.py               # UbigeoRepositoryPort (ABC)
├── application/
│   ├── __init__.py
│   └── registry.py            # UbigeoRegistry (casos de uso)
├── infrastructure/
│   ├── __init__.py
│   └── json_repository.py     # Adaptador JsonUbigeoRepository
└── data/
    ├── inei/                  # ubigeo_inei.json
    └── reniec/                # ubigeo_reniec.json

Dirección de dependencias: infrastructure → application → domain

---

Repositorio personalizado

Inyecta cualquier fuente de datos que implemente UbigeoRepositoryPort:

from peru_ubigeo import UbigeoRegistry
from peru_ubigeo.domain.ports import UbigeoRepositoryPort

class MyDatabaseRepository(UbigeoRepositoryPort):
    ...

registry = UbigeoRegistry(repository=MyDatabaseRepository())

---

Manejo de errores

from peru_ubigeo import (
    UbigeoRegistry,
    InvalidUbigeoCodeError,
    UbigeoNotFoundError,
    DataSourceError,
)

registry = UbigeoRegistry()

try:
    district = registry.get_by_code("XYZ")
except InvalidUbigeoCodeError as e:
    print(e)  # mensaje en español
except UbigeoNotFoundError as e:
    print(e)  # mensaje en español
except DataSourceError as e:
    print(e)  # mensaje en español

Excepción	Cuándo se lanza
InvalidUbigeoCodeError	El código no tiene 6 dígitos numéricos
UbigeoNotFoundError	Formato válido pero sin coincidencia en los datos
DataSourceError	Archivo JSON faltante o corrupto

Todas heredan de UbigeoError.

---

Fuentes de datos

Fuente	Estándar	Uso
INEI	Códigos geográficos nacionales oficiales	Por defecto
RENIEC	Códigos del registro civil (pueden diferir del INEI)	Documentos electrónicos SUNAT

Los datos están embebidos estáticamente en el paquete; las actualizaciones se distribuyen como nuevas versiones.

---

Desarrollo

git clone https://github.com/csotelo/peru-ubigeo
cd peru-ubigeo
pip install -e ".[dev]"

# Ejecutar tests
pytest

# Tests con reporte de cobertura
pytest --cov=peru_ubigeo --cov-report=term-missing

---

Integración con librerías SUNAT

UbigeoCode es un tipo validado que puedes importar directamente en peru-einvoice, peru-gre, peru-sire y peru-cpe:

from peru_ubigeo import UbigeoRegistry, UbigeoCode

def build_address(ubigeo_str: str) -> dict:
    registry = UbigeoRegistry()
    code: UbigeoCode = registry.normalize(ubigeo_str)
    district = registry.get_by_code(code)
    return {
        "ubigeo": code,
        "district": district.name,
        "province": district.province_code,
        "department": district.department_code,
    }

---

Licencia

Distribuido bajo la licencia Apache 2.0. Ver LICENSE para más detalles.

Copyright 2024 Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

Descargo de responsabilidad

Este proyecto no es un producto oficial de SUNAT, INEI ni RENIEC.

peru-ubigeo es una librería open source desarrollada de forma independiente por la comunidad. Los datos de ubigeo incluidos provienen de fuentes públicas oficiales (INEI y RENIEC), pero este paquete no está respaldado, afiliado ni avalado por ninguna entidad del Estado peruano.

El uso de esta librería es bajo la responsabilidad del desarrollador. Se recomienda verificar los datos con las fuentes oficiales ante cualquier uso en producción que tenga implicancias legales o tributarias.