walactv-scrapper

Imported from alejandrofm98/walactv-scrapper (AGENTS.md). Install upstream with npx skills add alejandrofm98/walactv-scrapper. Copyright stays with the author.

AGENTS.md - WALACTV-SCRAPPER

Guia para agentes de codigo que trabajen en walactv-scrapper y en su ecosistema de proyectos hermanos (iptv-api, WalacTV, walactvWeb). Secciones 0-3 son contexto obligatorio antes de tocar nada. Secciones 4-11 son referencia operativa.

0. Ecosistema y posicion del proyecto

walactv-scrapper es el motor de ingestion de datos del ecosistema WalacTV. Produce los catalogos de contenido que iptv-api consume.

   +-------------+        +-------------+
   |  walactvWeb |        |   WalacTV   |
   |  Angular 20 |        |  Android TV |
   +------+------+        +-----+-------+
          |                    |
          v                    v
   +--------------------------------------+
   |          iptv-api (FastAPI)          |
   |     Puerto 3010 · Postgres           |
   +---+----------+-----------+-----------+
       |          |           |
       | lee JSON | escribe   | escribe scraper_failures
       v          v           v
   +--------+ +----------+ +-----------+
   |walactv-| | iptv-data| | Postgres  |
   |scrapper| | volumen  | | tabla     |
   | (este) | | compartido| | scraper_  |
   |        | |  (JSONs) | | failures  |
   +--------+ +----------+ +-----------+

Tabla de proyectos hermanos

1. Contexto rapido

• Stack: Python 3.12, SQLAlchemy 2.0 + psycopg3 (via iptv-db), BeautifulSoup4, requests, Pillow, python-dotenv.
• Entry points: scripts/main.py (scraper principal), scripts/sync_iptv.py (sync IPTV), scripts/sync_replays.py (replays), scripts/scrape_tmdb_metadata.py (TMDB), scripts/generate_content_json.py (cache JSON), scripts/poblar_mapeo_canales.py (mapeo).
• BD: PostgreSQL via SQLAlchemy 2.0 (paquete iptv-db). El DatabasePG mantiene un pool asyncpg legacy para backward compat.
• Docker: 5 Dockerfiles + docker-compose.yaml. Despliegue via Ansible + Ofelia (cron).
• Horarios: main.py (08:00 diario), sync_iptv.py (cada 6h), sync_replays.py (12:00 diario), tmdb (03:00 diario), IntroDB (07:00 diario, opt-in).

2. Arquitectura

2.1 Modulos principales (scripts/)

2.2 Servicios (scripts/services/)

2.3 Utilidades (scripts/utils/)

2.4 Convenciones de codigo

• Clases: PascalCase. Funciones/variables: snake_case. Constantes: UPPER_CASE.
• Docstrings en espanol, breves.
• Imports: stdlib -> terceros -> locales.
• Tipo hints: parcial (mejor en archivos nuevos).
• Errores: try/except con print() para scripts cron, logging para scripts nuevos.

3. Patrones obligatorios

1. Config via scripts/config.py → Settings singleton con @lru_cache.
2. BD via scripts/database.py → DatabasePG (asyncpg pool singleton).
3. Para bulk insert, usar scripts/services/bulk_insert.py con batch size configurable.
4. Scripts deben tener if __name__ == "__main__": guard.
5. Variables sensibles via env vars, NUNCA hardcoded.
6. Para imagenes, usar scripts/services/event_images.py (PIL).
7. Fechas en formato ISO 8601.
8. Naming de tablas: singular snake_case (channels, movies_catalog, series_episodes).

4. Contratos publicos (cross-project)

4.1 Datos que produce este scrapper

• JSONs de catalogo: Escritos en data/json/ (volumen iptv-data compartido). iptv-api los lee de ../walactv-scrapper/data/json/.
• Tabla scraper_failures: Este scrapper escribe filas de fallos de TMDB. iptv-api las lee para alertas.
• Volumen compartido: iptv-data (Docker volume / NFS). Mismo path desde ambos contenedores.
• Red compartida: dokploy-network.

4.2 Datos que consume de iptv-api

• IPTV_API_URL=http://localhost:3010 (via env var).
• API_SECRET_KEY (mismo valor que iptv-api).
• Tabla channels (iptv-api escribe, este scrapper lee para mapeo).

4.3 Variables de entorno comunes

4.4 Dependencia de iptv-db

Este scrapper importa modelos ORM de iptv-db:

• from iptv_db.models import Channel, MovieCatalog, ...
• from iptv_db.engine import get_session_factory, get_sync_session_factory

iptv-db se instala via pip desde el requirements file:

iptv-db @ git+https://github.com/alejandrofm98/iptv-db.git@<commit_hash>

Cuando se actualiza iptv-db (nuevos modelos, columnas), hay que actualizar el hash en todos los requirements files (ver seccion 5).

5. Configuracion y secretos

scripts/config.py carga .env via python-dotenv. Las variables de BD vienen de env vars o del docker/.env.

Reglas:

• Nunca commitear .env ni credenciales.
• docker/.env tiene PG real (ya en .gitignore, no se commitea — FALSO POSITIVO resuelto en F0).
• actualiza_epg.py usa EPG_USER y EPG_PASS via env vars.
• docker/.env-example es la referencia commiteable.

6. Lint, formato, tipos y calidad

Toda la config vive en pyproject.toml.

6.1 Comandos

ruff format scripts/
ruff check scripts/ --fix
mypy scripts/ --config-file pyproject.toml
vulture scripts/ --min-confidence 80
pytest tests/

6.2 Reglas activas (resumen)

• Line length: 100.
• Target Python: 3.12.
• Selectors ruff: E, F, W, I, UP, B, SIM, RUF.
• vulture: umbral 80%.

6.3 Pre-commit y CI

Configurados en F4a. Instalar local: pre-commit install. CI: ver .github/workflows/ci.yml.

6.4 Como correr TODO

ruff format scripts/ && ruff check scripts/ --fix && mypy scripts/ --config-file pyproject.toml && vulture scripts/ --min-confidence 80 && pytest tests/

7. Testing

• Framework: pytest.
• Tests en tests/: conftest.py con fixtures para asyncpg mock, settings mock, datos de ejemplo.
• Patrones:
  • Mockear asyncpg/DB — nada de red en tests unitarios.
  • Tests de normalizacion de sync_iptv (idiomas, paises, calidad).
  • Tests de parsing de HTML del scrapper.
  • Tests de singleton de DatabasePG.

8. Despliegue (Dokploy)

Este proyecto usa Dokploy para despliegue continuo. Cada git push a master despliega automaticamente el nuevo codigo en produccion.

• NO es necesario hacer deploy manual, SSH al servidor, docker compose, etc.
• Solo hacer git push — Dokploy detecta el push y reconstruye + reinicia el contenedor.
• Los crons de Ofelia se configuran en docker-compose.yaml y se actualizan automaticamente con cada deploy.
• Tener en cuenta: cualquier push a master va a produccion inmediatamente. Si necesitas probar sin afectar produccion, trabajar en una rama y hacer PR.

9. Criterios para cambios

1. No romper el pipeline de Ofelia (cron). Cada cambio debe preserving el if __name__ == "__main__" guard.
2. Si modificas tablas o esquemas, actualizar iptv-db/ (Alembic migration). database/schema.sql.legacy es solo referencia historica.
3. Si agregas un script nuevo, registrarlo en docker-compose.yaml y en este archivo.
4. Evitar cambios de estilo en archivos no tocados.

10. Roadmap (no en esta iteracion)

Completado

• Activar pre-commit (F4a)
• CI en GitHub Actions (F4a)
• Migrar DataManagerSupabase a un nombre que refleje que usa PostgreSQL (decidido mantener)
• F3: scrapper migrado de asyncpg/psycopg2 a iptv-db
• F1.5: schema.sql renombrado a .legacy (Alembic unificado en iptv-db)

Pendiente

1. Migrar los 4 modulos de services/ legacy a src/iptv_api/services/ (hecho en F5c) [este era iptv-api]
2. Eliminar dead code: Firebase shim (database.py:568-799) (hecho en F3, ReplayManager eliminado)
3. Migrar print() con emojis a logging framework.
4. Agregar mas tests (target: 80% coverage en sync_iptv y scrapper).
5. Mover actualiza_epg.py a Ofelia schedule.

Cancelado

• F4b: tests con testcontainers

11. Checklist antes de cerrar una tarea

1. Codigo formateado: ruff format sin diffs.
2. Lint limpio: ruff check sin warnings.
3. Tipos: mypy sin errores en modulos tocados.
4. Tests: pytest tests/ pasa.
5. Sin credenciales hardcodeadas (verificar con grep -rn "password\|secret\|key\|token" scripts/ --include="*.py" | grep -v "env\|config\|ENV").
6. Sin emojis en codigo ni comentarios nuevos.
7. Si tocaste tablas o esquemas: generar migration en iptv-db (Alembic) y actualizar hash en requirements.
8. Verificar deploy post-push (ver seccion 12).

12. Verificacion de deploy post-push

Dokploy detecta pushes y redesplega automaticamente. Despues de cada push a la branch principal, verificar que el deploy fue exitoso.

Acceso al server de Dokploy

El server de Dokploy es accesible via SSH usando un alias configurado en ~/.ssh/config (alias: pro). El orquestador puede acceder cuando se lo pidas explicitamente.

No commitees informacion sensible sobre el server (IPs, paths de claves, etc.) en este AGENTS.md. Si necesitas ver que comandos usar, consulta la config SSH local o pregunta al orquestador.

Checklist post-push

Despues de hacer push a la branch principal (master en este repo):

• Esperar 1-2 minutos para que Dokploy detecte el push
• Verificar que el deploy fue exitoso (ver "Comandos utiles" abajo)
• Si hay errores, pedirle al orquestador que investigue via SSH y proponga un fix
• Si el fix es trivial, aplicarlo, commitear, pushear
• Verificar que el siguiente deploy (triggered por el push del fix) ahora funcione

Comandos utiles (via SSH como pro)

# Ver el ultimo log de deploy de una app
ssh pro "ls -t /etc/dokploy/logs/<app-name>/ | head -1 | xargs -I {} cat /etc/dokploy/logs/<app-name>/{}"

# Ver el estado actual de los containers
ssh pro "docker ps -a --format 'table {{.Names}}\t{{.Status}}' | grep walactv"

# Ver logs en vivo de un container
ssh pro "docker logs --tail 50 <container-name>"

# Ver logs de un cron especifico (Ofelia)
ssh pro "journalctl -u ofelia-scheduler --since '10 minutes ago'"

Reemplazar <app-name> y <container-name> segun corresponda:

• App name en Dokploy: walactv-scrapper-gbhx9q
• Containers: walactv-sync-iptv, walactv-sync-replays, walactv-futboltv, walactv-imdb-*, walactv-sync-tmdb-metadata

Errores comunes en deploys

Auto-correccion via orquestador

Si queres que el orquestador verifique el deploy por vos:

1. Decile "verifica el deploy de walactv-scrapper"
2. El orquestador se conecta via SSH y lee los logs
3. Si hay errores, los analiza y propone un fix
4. Vos decis si aplicar el fix o no
5. El orquestador commitearia y pushearia solo si vos lo autorizas

NO dar acceso automatico al orquestador sin autorizacion explicita. El orquestador solo actua cuando se le pide.