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

Todas heredan de UbigeoError.

Fuentes de datos

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.