JailDesigner
f967af541c
- Reemplaza zxdb.py por main.py + paquete zxdb/ (database, organizer, downloader, filesystem) - Añade zxdb/setup/: orquestador Docker, descarga e import de ZXDB automáticos - main.py integra el setup al arrancar y detiene el contenedor al salir (try/finally) - Elimina DB_HOST de config.py: la conexión usa siempre 127.0.0.1 (port mapping Docker) - Actualiza requirements.txt a versiones más recientes y elimina logging (stdlib) - Actualiza README con el nuevo flujo de uso Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
110 lines
4.7 KiB
Markdown
110 lines
4.7 KiB
Markdown
# ZXDB Downloader
|
|
|
|
Script que descarga juegos de ZX Spectrum a partir de la base de datos [ZXDB](https://github.com/zxdb/ZXDB) (MySQL en Docker).
|
|
|
|
## Requisitos
|
|
|
|
- Python 3.x
|
|
- Docker
|
|
|
|
## Setup
|
|
|
|
### Entorno virtual
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`.
|