zxdb/README.MD

ZXDB Downloader

Script que descarga juegos de ZX Spectrum a partir de la base de datos ZXDB (MySQL en Docker).

Requisitos

• Python 3.x
• Docker

Setup

Entorno virtual

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuración

Edita config.py en la raíz del proyecto. Variables principales:

Variable	Descripción
DB_*	Parámetros de conexión a MySQL
DESTINATION_PATH	Carpeta donde se depositan los juegos organizados
CACHE_PATH	Carpeta de caché (evita re-descargar ficheros)
TEMP_FILE	Fichero temporal durante la descarga
SHOULD_CLEAR_DESTINATION_PATH	Si es True, limpia el destino antes de cada ejecución
SHOULD_SPLIT_MODERN_AND_CLASSIC	Divide los juegos en carpetas classics/modern
SHOULD_SORT_BY_YEAR	Organiza por año de lanzamiento
SHOULD_SORT_BY_LETTER	Organiza por primera letra del título
SHOULD_SORT_BY_DEVELOPER	Organiza por desarrollador
WAIT / MIN_WAIT / MAX_WAIT	Control de velocidad de descarga
LAST_CLASSIC_YEAR	Año de corte entre clásicos y modernos
ZXDB_SQL_PATH	Ruta temporal donde se extrae ZXDB_mysql.sql
ZXDB_STATE_FILE	Fichero JSON con el estado del último import

Ejecución

source .venv/bin/activate
python main.py

main.py hace el setup automáticamente al arrancar:

1. Asegura que el contenedor MySQL Docker existe y está corriendo (lo crea si no existe).
2. Comprueba en GitHub si hay una versión más nueva de ZXDB.
3. Si es necesario: descarga ZXDB_mysql.sql.zip e importa en MySQL.
4. Descarga y organiza los juegos.
5. Al terminar (o con Ctrl+C), detiene el contenedor Docker.

El estado del último import se guarda en /tmp/zxdb_state.json. Una segunda ejecución sin cambios en GitHub omite el import.

Para conectar manualmente a MySQL mientras el contenedor está en marcha:

mysql -h 127.0.0.1 -P 3306 -u root -p
# Contraseña: unJEPimbJddHP8
# Luego: use zxdb

Estructura del proyecto

zxdb/
├── main.py             # Punto de entrada: orquesta el flujo principal
├── config.py           # Configuración (credenciales y rutas locales, no en git)
├── requirements.txt    # Dependencias Python
│
└── zxdb/               # Paquete con la lógica del programa
    ├── __init__.py
    ├── database.py     # Conexión a MySQL y ejecución de consultas
    ├── queries.sql     # Consultas SQL (índices 0-3)
    ├── organizer.py    # Construcción de rutas y enriquecimiento de elementos
    ├── downloader.py   # Descargas, caché y descompresión de ficheros
    ├── filesystem.py   # Utilidades de sistema de ficheros y salida por pantalla
    └── setup/
        ├── __init__.py
        ├── __main__.py         # Orquestador: Docker + detección de cambios + import
        ├── database_import.py  # Descarga y extracción de ZXDB_mysql.sql.zip
        └── docker_manager.py   # Gestión del contenedor MySQL e import SQL

Módulos

zxdb/database.py

Gestiona la conexión a MySQL. connect(query_index) devuelve la lista de elementos obtenidos de la base de datos.

zxdb/organizer.py

Construye rutas y enriquece cada elemento con metadatos: game_folder_name, URL completa, nombre de fichero, subcarpeta y flag de ZIP. get_final_destination_folder() aplica la lógica de organización según la configuración.

zxdb/downloader.py

Gestiona las descargas desde internet y el uso de la caché. get_files(elements) itera sobre todos los elementos, sirve desde caché si es posible, o descarga y almacena en caché.

zxdb/filesystem.py

Utilidades de sistema de ficheros: limpiar carpeta de destino, eliminar directorios vacíos, e imprimir el progreso por pantalla.

zxdb/queries.sql

Cuatro consultas SQL (índices 0-3). La consulta 3 (usada por defecto) filtra juegos de ZX Spectrum (m.text like 'ZX-%') y devuelve solo ficheros de cinta, disco, snapshot y pokes.

zxdb/setup/ — Setup de la base de datos

Invocado automáticamente por main.py. También puede ejecutarse de forma independiente con python -m zxdb.setup.

• __main__.py: Orquestador del flujo completo (Docker + detección de cambios + import).
• docker_manager.py: ensure_container(), wait_for_mysql(), db_exists(), import_sql(), stop_container() — gestión del contenedor Docker y del import SQL.
• database_import.py: download_zxdb(destination) — descarga ZXDB_mysql.sql.zip desde GitHub (streaming, ~150 MB) y extrae ZXDB_mysql.sql. Ejecutable directamente con python -m zxdb.setup.database_import.