congreso-ia 0.2.0
Librería Python para acceder a datos públicos del Congreso de los Diputados de España y periódicos españoles (diputados, votaciones, noticias de política).
License: MIT
Requires Python: >=3.9
Keywords: congreso, diputados, spain, parliament, open-data, scraping, votaciones, intervenciones, newspapers, periodicos, noticias, elpais, elmundo, politics

# congreso-ia

[![PyPI version](https://img.shields.io/pypi/v/congreso-ia.svg)](https://pypi.org/project/congreso-ia/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Librería Python para acceder a datos públicos del **Congreso de los Diputados de España** y **periódicos españoles**. Extrae diputados, votaciones, iniciativas, intervenciones y noticias de política.

## Instalación

```bash
pip install congreso-ia
```

## 🗞️ Scraper de Periódicos (Nuevo!)

Scrapea noticias de **11 periódicos españoles** con funcionalidades avanzadas:

- **Categorías dinámicas** - Descubre secciones automáticamente
- **Caché** - SQLite persistente o en memoria
- **Filtrado por fechas** - Rango desde/hasta
- **Descarga de imágenes** - Guardado local configurable

### Periódicos Disponibles

| Periódico | Clave |
|-----------|-------|
| El País | `elpais` |
| El Mundo | `elmundo` |
| elDiario.es | `eldiario` |
| ABC | `abc` |
| La Vanguardia | `lavanguardia` |
| El Confidencial | `elconfidencial` |
| Público | `publico` |
| La Razón | `larazon` |
| 20 Minutos | `20minutos` |
| El Periódico | `elperiodico` |
| InfoLibre | `infolibre` |

### Uso Básico

```python
from congreso_ia.newspapers import NewspaperClient

with NewspaperClient() as client:
    # Noticias de política de todos los periódicos
    articles = client.fetch_politics(limit_per_source=5)
    
    for article in articles:
        print(f"{article.source}: {article.title}")
```

### Categorías Dinámicas

```python
# Descubrir categorías disponibles (scrapeadas del menú)
categories = client.discover_categories("elpais")
# {'internacional': '/internacional/', 'economía': '/economia/', ...}

# Scrapear una categoría específica
articles = client.fetch_category("elpais", "economía", limit=10)
```

### Filtrado por Fechas

```python
from datetime import date

articles = client.fetch_politics(
    limit_per_source=20,
    desde=date(2024, 1, 1),
    hasta=date(2024, 1, 31)
)
```

### Sistema de Caché

```python
# Caché SQLite (persistente entre sesiones)
client = NewspaperClient(cache="./cache/articles.db")

# Caché en memoria (solo sesión actual)
from congreso_ia.cache import MemoryCache
client = NewspaperClient(cache=MemoryCache(ttl_hours=1))
```

### Descarga de Imágenes

```python
client = NewspaperClient(
    download_images=True,
    images_dir="./data/images/"
)

article = client.fetch_article("https://elpais.com/...")
print(article.image_local_path)  # "./data/images/abc123.jpg"
```

---

## 🏛️ Datos del Congreso

### API Python

```python
from congreso_ia import CongressClient

client = CongressClient()

# Obtener todos los diputados activos
deputies = client.get_deputies()
print(f"{len(deputies)} diputados")

# Filtrar por partido
pp_deputies = client.get_deputies(party="PP")

# Obtener votaciones recientes
votes = client.get_votes()

# Obtener iniciativas
initiatives = client.get_initiatives()

# Buscar intervenciones de un diputado
interventions = client.get_interventions(speaker="Pedro Sanchez")
print(f"{len(interventions)} intervenciones")

# Filtrar por órgano y fecha
from datetime import date
pleno = client.get_interventions(
    speaker="Feijoo",
    organ="Pleno",
    start_date=date(2024, 1, 1)
)
```

### Ejecución paralela con rate limiting

```python
from congreso_ia import CongressClient, parallel_fetch

client = CongressClient()

# Buscar intervenciones de múltiples diputados en paralelo
speakers = ["Sanchez", "Feijoo", "Abascal", "Diaz"]

results = parallel_fetch(
    func=lambda s: client.get_interventions(speaker=s),
    items=speakers,
    max_workers=4,
    requests_per_second=2.0,
    on_progress=lambda done, total, r: print(f"{done}/{total}")
)

for r in results:
    if r.success:
        print(f"{r.item}: {len(r.result)} intervenciones")
```

### Exportar a DataFrame

```python
from congreso_ia import interventions

# Obtener como pandas DataFrame
df = interventions.fetch(speaker="Abascal", as_df=True)

# Exportar a CSV
df.to_csv("intervenciones_abascal.csv", index=False)
```

### CLI

```bash
# Descargar votaciones recientes
congreso scrape votes --latest

# Descargar intervenciones de una legislatura
congreso scrape interventions --legislature 15

# Exportar a diferentes formatos
congreso scrape votes --format parquet
congreso scrape votes --format csv
```

## Datos disponibles

| Recurso | Método | Campos principales |
|---------|--------|-------------------|
| Diputados | `get_deputies()` | nombre, partido, circunscripción, grupo, email |
| Votaciones | `get_votes()` | fecha, título, resultado, votos individuales |
| Iniciativas | `get_initiatives()` | título, tipo, autor, expediente |
| Intervenciones | `get_interventions()` | orador, fecha, órgano, tema, video_url |
| **Artículos** | `NewspaperClient` | título, fuente, fecha, contenido, imagen |

## Filtros

### Periódicos
- `sources`: Lista de periódicos a usar
- `desde` / `hasta`: Rango de fechas
- `category`: Categoría específica (economía, internacional, etc.)

### Diputados
- `party`: Filtrar por partido (ej. "PP", "PSOE")
- `constituency`: Filtrar por circunscripción

### Intervenciones
- `speaker`: Nombre del orador
- `organ`: Tipo de órgano ("Pleno", "Comision")
- `legislature`: Número de legislatura
- `start_date` / `end_date`: Rango de fechas

## Ejemplos

Ver la carpeta `examples/` para más ejemplos:

```bash
python examples/demo_advanced_features.py  # Demo de periódicos
python examples/test_all_newspapers.py      # Probar todos los scrapers
python examples/fetch_deputies.py
python examples/fetch_votes.py
```

## Desarrollo

```bash
# Clonar repositorio
git clone https://github.com/congreso-ia/congreso-ia-scraper.git
cd congreso-ia-scraper

# Instalar en modo desarrollo
pip install -e ".[dev]"

# Ejecutar tests
pytest

# Linter
ruff check .
```

## Disclaimer Legal

Este proyecto **no es una fuente oficial** del Congreso de los Diputados ni de ningún periódico. Es una herramienta de código abierto que utiliza exclusivamente fuentes públicas. El uso de esta herramienta debe cumplir con los términos de servicio de cada sitio web.

## Licencia

Distribuido bajo la licencia MIT. Ver `LICENSE` para más información.