Metadata-Version: 2.1
Name: argentina
Version: 0.1.0
Summary: Herramientas Python para datos públicos argentinos: provincias, departamentos, ciudades, geografía (IGN), economía (INDEC/BCRA), códigos postales, identificadores, EPH y más.
Author: Tobias Yatche
License: MIT
Project-URL: Homepage, https://github.com/tobiasyatche/argentina
Project-URL: Repository, https://github.com/tobiasyatche/argentina
Project-URL: Issues, https://github.com/tobiasyatche/argentina/issues
Project-URL: Changelog, https://github.com/tobiasyatche/argentina/blob/main/CHANGELOG.md
Keywords: argentina,indec,ign,bcra,eph,censo,datos-abiertos,geocoding,argenmap,georef,cuit,dni,codigo-postal,cpa,provincias,departamentos,malvinas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Sociology
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: data
Requires-Dist: pandas ; extra == 'data'
Requires-Dist: requests ; extra == 'data'
Requires-Dist: pyarrow ; extra == 'data'
Requires-Dist: duckdb ; extra == 'data'
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pandas ; extra == 'dev'
Requires-Dist: requests ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: build ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: mkdocs ; extra == 'dev'
Requires-Dist: mkdocs-material ; extra == 'dev'
Requires-Dist: mkdocstrings[python] ; extra == 'dev'
Provides-Extra: economia
Requires-Dist: pandas ; extra == 'economia'
Requires-Dist: requests ; extra == 'economia'
Provides-Extra: elecciones
Requires-Dist: requests ; extra == 'elecciones'
Requires-Dist: pandas ; extra == 'elecciones'
Provides-Extra: feriados
Requires-Dist: requests ; extra == 'feriados'
Provides-Extra: geo
Requires-Dist: geopandas ; extra == 'geo'
Requires-Dist: requests ; extra == 'geo'
Requires-Dist: pyogrio ; extra == 'geo'
Provides-Extra: georef
Requires-Dist: requests ; extra == 'georef'
Provides-Extra: maps
Requires-Dist: folium ; extra == 'maps'

# argentina

Herramientas para trabajar con datos de Argentina en Python.

## Provincias

API inspirada en el paquete `us`.

```python
import argentina as arg

arg.provincias.BUENOS_AIRES
arg.provincias.CORDOBA
arg.provincias.CABA

arg.provincias.lookup("PBA")
arg.provincias.lookup("Córdoba")
arg.provincias.lookup("14")
arg.provincias.lookup("AR-X")

arg.provincias.lookup("PBA").codigo_indec
arg.provincias.lookup("CABA").capital
```

Cada `Provincia` expone `nombre`, `codigo_indec`, `iso_id`, `region` y `capital`.
`lookup` acepta nombre (con o sin tildes), código INDEC, ID ISO 3166-2 o alias
comunes (`PBA`, `CABA`, `bs as`, `TDF`, etc.) y es case-insensitive.
`arg.provincias.listar()` devuelve las 24 provincias.

## Departamentos

API simple para departamentos argentinos.

```python
import argentina as arg

arg.departamentos.lookup("06441")

arg.departamentos.lookup("Rosario")

arg.departamentos.por_provincia("Buenos Aires")
```

`lookup` acepta el código de departamento o un nombre **único** dentro del set
embebido. Nombres ambiguos entre provincias (por ejemplo `"Capital"`) devuelven
`None`: para esos casos hay que usar el código (`"14014"`) o un alias específico.

`por_provincia` acepta el nombre de la provincia (con o sin tildes) o su código
INDEC, y devuelve una tupla de `Departamento`.

Por ahora el set incluye un subconjunto representativo de departamentos
(no todos los del país) — la idea es validar la API antes de expandir.

## Geo

El subpaquete `arg.geo` concentra herramientas geoespaciales.

### Shapes

Geometrías oficiales de provincias y departamentos servidas por el
**Instituto Geográfico Nacional (IGN)** vía WFS GeoServer. Ver fuente:
[Capas SIG del IGN](https://www.ign.gob.ar/NuestrasActividades/InformacionGeoespacial/CapasSIG).

API recomendada:

```python
import argentina as arg

gdf = arg.geo.shapes.provincias()       # 24 polígonos del IGN
gdf = arg.geo.shapes.departamentos()    # 529 polígonos del IGN
```

Las columnas que devuelve son las del IGN: `gid`, `entidad`/`objeto`, `fna`
(nombre completo), `gna`, `nam` (nombre corto), `in1` (código INDEC), `fdc`,
`sag` y `geometry` (CRS EPSG:4326 / WGS 84).

Instalación del extra geoespacial:

```bash
pip install "argentina[geo]"
```

También se puede pasar una URL alternativa con `url=...` (por ejemplo si tenés
una capa propia en otro servidor). Los archivos descargados se cachean en
`~/.cache/argentina/shapes/<nombre>/` — la primera llamada baja el ZIP del
IGN (~45 MB provincias, ~57 MB departamentos), las siguientes son
instantáneas. Pasá `overwrite=True` para forzar redescarga. Acepta archivos
`.gpkg`, `.geojson` o `.shp` dentro del ZIP (prefiere `.gpkg`).

El paquete base no depende de `geopandas` ni `requests` para usar este módulo:
todo se importa de forma diferida adentro de las funciones. Si llamás a
`geo.shapes.*` sin haber instalado el extra `[geo]`, vas a ver un `ImportError`
con la instrucción de instalación.

#### Compatibilidad

El módulo anterior `arg.shapes` sigue funcionando como wrapper:

```python
arg.shapes.provincias(url="...")  # equivalente a arg.geo.shapes.provincias
```

Es solo por compatibilidad — la API nueva es `arg.geo.shapes`.

## Economía

El módulo `argentina.economia` da acceso a **493 series económicas oficiales** de Argentina (INDEC, BCRA y SSPM), descargables desde la API de Series de Tiempo de datos.gob.ar.

Es un módulo **opcional**: requiere instalar `pandas` y `requests`, que no vienen con el paquete base.

Instalación:

```bash
pip install "argentina[economia]"
```

Después se importa explícitamente:

```python
import argentina.economia as economia
# o
from argentina import economia
```

(No está en `from argentina import *` ni se carga al hacer `import argentina`, para mantener el paquete base liviano y sin `pandas`/`requests`.)

Incluye la familia completa del IPC base dic 2016 (núcleo, regulados, estacionales, bienes, servicios y 12 capítulos × 7 regiones), EMAE, IPI, ISAC, oferta y demanda globales, salarios, empleo, hidrocarburos y más.

Ejemplo básico:

```python
from argentina.economia import ipc_nacional

df = ipc_nacional(start_date="2020-01-01")
print(df.head())
```

Acceder a cualquier serie del catálogo por alias:

```python
from argentina.economia import serie

df = serie("emae_desestacionalizada", start_date="2020-01-01")
```

O directamente por ID:

```python
from argentina.economia import obtener_serie

df = obtener_serie("148.3_INIVELNAL_DICI_M_26")
```

### Explorar el catálogo

```python
from argentina.economia import SERIES

print(len(SERIES))                       # 493
print(list(SERIES.keys())[:10])          # aliases disponibles
print(SERIES["ipc_nacional"])            # metadata de una serie
```

Cada entrada del catálogo trae `id`, `descripcion`, `fuente`, `frecuencia`, `tema` y `dataset`.

### Buscar series por palabra clave

`buscar` filtra el catálogo local (sin red) por una palabra que aparezca en el
alias, descripción o dataset:

```python
from argentina.economia import buscar

buscar("salario").head()
buscar("petroleo")
```

Devuelve un `DataFrame` con `alias`, `id`, `frecuencia`, `tema` y `descripcion`.

Para ver la lista completa con descripciones, ver [SERIES_DISPONIBLES.md](SERIES_DISPONIBLES.md).

## Clean

Funciones básicas de limpieza de texto y columnas.

```python
import argentina as arg

arg.clean.quitar_tildes("Córdoba")
arg.clean.normalizar_texto("  Código   de Provincia ")
arg.clean.snake_case("Código de Provincia")
```

## Personas

Funciones básicas para limpiar, validar y normalizar identificadores y
nombres argentinos.

```python
import argentina as arg

arg.personas.limpiar_dni("12.345.678")
arg.personas.validar_dni("12.345.678")

arg.personas.limpiar_cuit("20-12345678-3")
arg.personas.extraer_dni_de_cuit("20-12345678-3")

arg.personas.normalizar_nombre(" María   Laura ")
arg.personas.primer_nombre("María Laura")
arg.personas.apellido_principal("Pérez Gómez")
```

### Validación y formato de CUIT/CUIL

```python
arg.personas.calcular_digito_cuit("2012345678")
arg.personas.validar_cuit("20-12345678-6")
arg.personas.validar_cuit("20-12345678-3")
arg.personas.validar_cuit("20-12345678-3", digito=False)

arg.personas.tipo_cuit("20-12345678-6")
arg.personas.formatear_dni("12345678")
arg.personas.formatear_cuit("20123456786")
```

`validar_cuit` valida **dígito verificador** por default usando el algoritmo
oficial (multiplicadores `5 4 3 2 7 6 5 4 3 2`, mod 11, con los wrap-around
`10→9` y `11→0`). Si solo querés chequear el largo (11 dígitos) sin validar
dígito, pasá `digito=False`. `tipo_cuit` clasifica por prefijo en
`"persona_fisica"` (20/23/24/27) o `"persona_juridica"` (30/33/34).
`formatear_dni`/`formatear_cuit` devuelven los strings canónicos
`12.345.678` y `XX-XXXXXXXX-X`.

Sigue todo sintáctico — no consulta AFIP, no usa pandas ni APIs externas.

## Postal

Funciones para validar y parsear códigos postales argentinos.

```python
import argentina as arg

arg.postal.validar_cp4("1425")
arg.postal.validar_cpa("C1425ABC")
arg.postal.extraer_cp4("C1425ABC")
arg.postal.provincia_por_cpa("X5000AAA")
arg.postal.validar_cpa_provincia("X5000AAA", "Córdoba")
```

Soporta los dos formatos vigentes:

- **CP4** — código postal tradicional de 4 dígitos (ej. `"1425"`).
- **CPA** — Código Postal Argentino de 8 caracteres: letra de provincia + 4
  dígitos + 3 letras (ej. `"C1425ABC"`).

`tipo_codigo_postal` discrimina entre los dos, `extraer_cp4` te devuelve los 4
dígitos a partir de cualquiera de los dos formatos, y `provincia_por_cpa` usa
la letra inicial para identificar la jurisdicción. `validar_cpa_provincia`
chequea consistencia contra `arg.provincias` (acepta nombres con tildes,
ISO, código INDEC, etc.).

Todo es sintáctico — no valida que el código existe físicamente. Para
georreferenciación postal (mapear CPs a polígonos, validar contra un
municipio real) están los placeholders en `arg.geo.postal`.

## Educación

Funciones básicas para identificadores y categorías educativas argentinas.

```python
import argentina as arg

arg.educacion.limpiar_cue("0201234-00")
arg.educacion.validar_cue("020123400")

arg.educacion.extraer_jurisdiccion_cue(
    "020123400"
)

arg.educacion.normalizar_sector("público")
arg.educacion.normalizar_ambito("urbano")
arg.educacion.normalizar_nivel("secundario")
```

## Basemaps

Fondos cartográficos argentinos para Folium.

Instalación:

```bash
pip install "argentina[maps]"
```

```python
import argentina as arg
import folium

m = folium.Map(location=[-34.6037, -58.3816], zoom_start=4, tiles=None)

arg.geo.basemaps.add_argenmap(m)
arg.geo.basemaps.add_creditos_argentina(m)
arg.geo.basemaps.add_layer_control(m)

m.save("mapa.html")
```

`add_argenmap` agrega como fondo el servicio **Argenmap del IGN** (tiles TMS
oficiales). Usar tiles argentinos ayuda a que la toponimia preserve el nombre
oficial de las **Islas Malvinas** (los proveedores extranjeros suelen rotularlas
como "Falkland Islands"; las etiquetas viven dentro del raster y no se pueden
reescribir desde el cliente).

`add_creditos_argentina` agrega un overlay HTML fijo con la attribution. `add_layer_control`
agrega el control de capas de Folium para alternar entre fondos.

`folium` es opcional — instalar con el extra `[maps]`. Si llamás a `basemaps.*`
sin tenerlo instalado vas a ver un `ImportError` con la instrucción.

## Salud

Funciones básicas para normalizar variables frecuentes en datos
administrativos de salud.

```python
import argentina as arg

arg.salud.normalizar_sexo("femenino")
arg.salud.normalizar_sexo("varón")

arg.salud.normalizar_tipo_documento("dni")
arg.salud.limpiar_matricula("M.P. 12345")

arg.salud.grupo_etario(3)
arg.salud.edad_en_anios("2015-05-10", "2026-05-12")
```

`normalizar_sexo` mapea variantes (`femenino`/`mujer`/`f`,
`masculino`/`varón`/`hombre`/`m`, `no binario`/`otro`/`x`) a `F`/`M`/`X`.
`grupo_etario` clasifica edades en franjas estándar (`0`, `1-4`, `5-9`, `10-14`,
…, `55-64`, `65+`). `edad_en_anios` toma fechas como string ISO o `date` y
respeta si ya cumplió años en la fecha de referencia.

Solo stdlib — sin curvas OMS, sin z-scores, sin pandas.

## Elecciones

Limpieza y normalización de variables electorales argentinas.

```python
import argentina as arg

arg.elecciones.limpiar_mesa("Mesa 01234")
arg.elecciones.limpiar_circuito(" 12-A ")

arg.elecciones.normalizar_categoria("Presidente")
arg.elecciones.normalizar_tipo_eleccion("PASO")

arg.elecciones.validar_anio_eleccion(2023)
```

`arg.elecciones` (core) corre con stdlib pura — sin internet, sin pandas.

Para wrappers sobre APIs electorales (resultados, escrutinios) está el
submódulo opcional `arg.elecciones.api`, que importa `requests`/`pandas` de
forma diferida:

```python
import argentina as arg

print(arg.elecciones.api.disponible())
# {'requests': True, 'pandas': True}

datos = arg.elecciones.api.obtener_json(
    "https://URL_OFICIAL/resultados.json"
)
```

Instalación del extra:

```bash
pip install "argentina[elecciones]"
```

Importar `argentina.elecciones` no requiere internet ni el extra — sólo lo
necesitás si llamás a las funciones de `api`. **No** hace scraping de padrón ni
consulta datos personales.

## Fechas

Funciones para parsear y normalizar fechas frecuentes en datos
administrativos argentinos.

```python
import argentina as arg

arg.fechas.parsear_fecha("31/12/2024")
arg.fechas.fecha_iso("31/12/2024")
arg.fechas.es_fecha_valida("31/12/2024")

arg.fechas.edad_en_anios(
    "10/05/2015",
    "12/05/2026",
)

arg.fechas.anio_lectivo("15/02/2024")
arg.fechas.cohorte_nacimiento("10/05/2015")
arg.fechas.mes_anio("31/12/2024")
```

`parsear_fecha` acepta los formatos más frecuentes en bases argentinas:
`dd/mm/yyyy`, `dd-mm-yyyy`, `yyyy-mm-dd`, `yyyy/mm/dd`, y las variantes con año
de 2 dígitos. También acepta `date`/`datetime` directamente y los devuelve sin
re-parsear. `fecha_iso` reformatea cualquier formato soportado a `YYYY-MM-DD`.

`anio_lectivo` toma el calendario escolar argentino (arranca en marzo): enero y
febrero quedan asignados al ciclo del año anterior. El mes de inicio es
configurable con `mes_inicio=`. `cohorte_nacimiento` devuelve solo el año, y
`mes_anio` lo reformatea a `YYYY-MM` para usar como clave de agregación
mensual.

Solo stdlib — sin pandas, sin feriados, sin calendarios oficiales.

## Feriados

Consulta de feriados argentinos desde una API pública
([argentinadatos.com](https://argentinadatos.com)). Datos dinámicos, sin
hardcodear nada y sin scraping.

Instalación:

```bash
pip install "argentina[feriados]"
```

```python
import argentina as arg

arg.feriados.obtener(2026)
arg.feriados.es_feriado("2026-05-25")
arg.feriados.detalle("2026-05-25")
arg.feriados.proximo("2026-05-01")
```

`obtener(anio)` baja la lista completa de feriados del año y la cachea con
`lru_cache` (32 años en memoria). Las funciones derivadas — `es_feriado`,
`detalle`, `proximo` — reutilizan ese cache, así que después de la primera
llamada por año no vuelven a pegar a la red.

`proximo(desde=...)` busca en el año en curso y, si no encuentra, salta al
siguiente — útil para "qué feriado viene a partir de hoy" cerca de fin de año.

`requests` es opcional — instalar con el extra `[feriados]`. Importar
`argentina` o `argentina.feriados` no requiere red ni el extra; las llamadas a
la API son diferidas dentro de las funciones.

## Teléfonos

Funciones básicas para limpiar y normalizar teléfonos argentinos.

```python
import argentina as arg

arg.telefonos.limpiar("+54 9 11 1234-5678")
arg.telefonos.validar("+54 9 11 1234-5678")

arg.telefonos.extraer_caracteristica("+54 9 351 1234567")

arg.telefonos.es_celular("+54 9 11 1234-5678")

arg.telefonos.normalizar_e164("+54 9 11 1234-5678")
```

Maneja los formatos más frecuentes (`+54`, `54`, `0`, `9`, `15`, paréntesis,
guiones, espacios) y los reduce a un número nacional de 10 dígitos. `validar`
acepta el número si tiene exactamente 10 dígitos después de quitar prefijos.
`extraer_caracteristica` devuelve `"11"` para AMBA y los 3 dígitos iniciales
para el resto (heurística simple). `es_celular` reconoce los marcadores
clásicos `9` (internacional) y `15` (local). `normalizar_e164` produce el
formato canónico `+549...` para celulares y `+54...` para fijos —
si pasás `celular=True/False` forzás el resultado.

Todo es sintáctico — no consulta operadores ni valida que la línea exista.

## Direcciones

Funciones básicas para normalizar y parsear direcciones argentinas.

```python
import argentina as arg

direccion = "Av. Santa Fe 3253 Piso 2 Depto B"

arg.direcciones.normalizar(direccion)
arg.direcciones.extraer_calle(direccion)
arg.direcciones.extraer_altura(direccion)
arg.direcciones.extraer_piso(direccion)
arg.direcciones.extraer_departamento(direccion)
arg.direcciones.parsear(direccion)
```

`normalizar` baja a minúsculas, saca tildes y puntuación, colapsa espacios y
unifica abreviaturas frecuentes (`avenida`/`avda`/`av.` → `av`,
`departamento`/`dpto`/`dto` → `depto`, `pje` → `pasaje`, etc.). El resto de las
funciones operan sobre la dirección normalizada:

- `extraer_altura` — primer número de hasta 5 dígitos.
- `extraer_calle` — todo lo que está antes de la altura.
- `extraer_piso` — busca `piso N` o `p N`, también `PB`.
- `extraer_departamento` — busca `depto X`, `unidad X` o `uf X`.
- `tiene_altura` — bool.
- `parsear` — un dict con todos los campos en una sola llamada.

Solo stdlib — sin geocoding, sin APIs externas, sin pandas. Para
georreferenciación queda pendiente un módulo `arg.geo.direcciones` aparte.

## Geo: direcciones

Georreferenciación de direcciones argentinas usando [Georef](https://datosgobar.github.io/georef-ar-api/).

Instalación:

```bash
pip install "argentina[georef]"
```

```python
import argentina as arg

resultado = arg.geo.direcciones.georreferenciar(
    direccion="Av. Santa Fe 3253",
    provincia="CABA",
)
# {'nomenclatura': 'AV SANTA FE 3253, Comuna 14, ...',
#  'ubicacion': {'lat': -34.588..., 'lon': -58.410...},
#  'provincia': {'nombre': 'Ciudad Autónoma de Buenos Aires', ...}, ...}

lat, lon = arg.geo.direcciones.coordenadas(
    direccion="Av. Santa Fe 3253",
    provincia="CABA",
)
```

`georreferenciar` (alias: `normalizar_georef`) acepta filtros opcionales por
`provincia`, `departamento`, `localidad` y `max_resultados`. Devuelve el primer
resultado de la API como `dict`, o `None` si no hay match. `coordenadas`
extrae directamente la tupla `(lat, lon)` del primer resultado.

`argentina.direcciones` (sin `geo`) hace **parseo local** sin red. La capa con
red, normalización oficial y coordenadas reales es `argentina.geo.direcciones`,
que importa `requests` de forma diferida — instalar el extra `[georef]`.

## Bancos

Funciones para identificadores bancarios argentinos.

```python
import argentina as arg

arg.bancos.limpiar_cbu(
    "0170 0001 4000 0001 2345 67"
)

arg.bancos.validar_cbu(
    "2850590940090418135201"
)

arg.bancos.formatear_cbu(
    "2850590940090418135201"
)

arg.bancos.banco_por_cbu(
    "0170099120000067797370"
)

arg.bancos.validar_alias(
    "MI.ALIAS.CBU"
)
```

`validar_cbu` chequea **los dos dígitos verificadores reales** (algoritmo
oficial: bloques `[0:7]+dv` y `[8:21]+dv`, pesos
`7 1 3 9 7 1 3` y `3 9 7 1 3 9 7 1 3 9 7 1 3`, `(10 - suma % 10) % 10`).
`codigo_banco_cbu` extrae los primeros 3 dígitos y `banco_por_cbu` los resuelve
contra `arg.bancos.BANCOS` (tabla mínima embebida — extensible).

`validar_alias` aplica las reglas básicas (6–20 chars, letras/números/`.`/`-`,
mayúsculas). `limpiar_alias` normaliza espacios y mayúsculas. `validar_cvu`
hace por ahora el chequeo mínimo (22 dígitos) — los CVU de billeteras
virtuales comparten el largo del CBU pero conviven con esquemas distintos por
proveedor.

Solo stdlib — no consulta bancos online ni promete validación bancaria real.

## Ciudades

Set curado de las principales ciudades del país (todas las capitales provinciales
+ grandes aglomerados urbanos como Rosario, Mar del Plata, Bahía Blanca, etc.),
con datos del Censo Nacional 2022 (INDEC).

```python
import argentina as arg

arg.ciudades.lookup("Rosario")
arg.ciudades.lookup("CABA")          # alias
arg.ciudades.lookup("mardel")        # alias
arg.ciudades.lookup("tucuman")       # alias para San Miguel de Tucumán

arg.ciudades.top(5)                  # 5 más pobladas
arg.ciudades.por_provincia("Buenos Aires")
arg.ciudades.listar()                # todas
for c in arg.ciudades:               # iterable
    print(c.nombre, c.poblacion_2022)
```

Cada `Ciudad` trae `nombre`, `provincia_codigo`, `provincia_nombre`,
`poblacion_2022`, `lat` y `lon`. La población corresponde al municipio/partido/
comuna (no al aglomerado urbano completo).

**Población provincial:** `argentina.provincias.Provincia` también tiene
`poblacion_2022` y `capital_lat`/`capital_lon` ahora — útil para ranking
nacional, mapas con marcadores, etc.

```python
top5 = sorted(arg.provincias, key=lambda p: p.poblacion_2022, reverse=True)[:5]
for p in top5:
    print(f"{p.nombre}: {p.poblacion_2022:,}".replace(",", "."))
```

Datos: Censo Nacional de Población, Hogares y Viviendas 2022 (INDEC).

## Data

`argentina.data` está pensado para datasets públicos argentinos de mayor tamaño
(microdatos EPH, Censo, etc.) que no tiene sentido empaquetar y que conviene
descargar o consultar bajo demanda.

Instalación:

```bash
pip install "argentina[data]"
```

Esto suma `pandas`, `requests`, `pyarrow` y `duckdb`. Ninguno se importa al
hacer `import argentina` — todo es diferido.

### EPH (microdatos)

Descarga los microdatos trimestrales oficiales de la **Encuesta Permanente de
Hogares (INDEC)** y los devuelve como `pandas.DataFrame`. La primera llamada
baja el ZIP del INDEC (~3-5 MB), lo cachea en `~/.cache/argentina/eph/T<N>_<año>/`
y lee el txt. Las siguientes son cache hits (sin red).

```python
import argentina as arg

# Personas (encuesta individual)
ind = arg.data.eph(anio=2024, periodo="trimestral", numero=1, tipo="individual")
# Hogares
hog = arg.data.eph(anio=2024, periodo="trimestral", numero=1, tipo="hogar")
```

Soporta:

- `periodo` (aliases: `"T"`, `"trim"`, `"trimestre"`, `"trimestral"`). La
  semestral (pre-2003) queda como `NotImplementedError`.
- `numero`: 1-4.
- `tipo`: `"individual"` / `"personas"` o `"hogar"` / `"hogares"`.
- `cache_dir`: directorio alternativo de cache.

Las columnas son las del INDEC tal cual (`CODUSU`, `CH04` sexo, `CH06` edad,
`PONDERA` ponderador, `P21` ingreso, `ESTADO` ocupación, `REGION`, etc.).

### Censo 2022

Arquitectura **DuckDB + Parquet remoto**: `arg.data.censo(...)` arma una query
`SELECT ... FROM read_parquet('https://...')` y trae solo las filas/columnas
pedidas (no descarga el dataset entero).

```python
df = arg.data.censo(
    anio=2022,
    tabla="personas",
    provincia="Córdoba",       # cualquier identificador de arg.provincias.lookup
    departamento="14014",       # opcional
    limite=10000,
)
```

**Estado:** el INDEC todavía no publica microdatos del Censo 2022 como parquets
oficiales accesibles vía HTTPS. `CENSO_PARQUETS_2022` viene vacío por default.
Para usarlo, configurá la URL (mirror propio o, cuando aparezca, oficial):

```python
import argentina.data.censo as c
c.CENSO_PARQUETS_2022["personas"] = "https://mi-mirror/personas.parquet"

# o pasarla directamente
arg.data.censo(anio=2022, url="https://mi-mirror/personas.parquet", limite=100)
```

Si llamás `arg.data.eph(...)` o `arg.data.censo(...)` sin haber instalado el
extra `[data]`, vas a ver un `ImportError` con la instrucción de instalación.
