Refactorización completa: modularización, setup automático y mejoras de configuración
- 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>
This commit is contained in:
@@ -1,52 +1,109 @@
|
||||
## Anotacions
|
||||
Per a connectar-se a la base de dades local (que està al container de MySQL)
|
||||
# ZXDB Downloader
|
||||
|
||||
mysql -h 172.18.0.2 -P 3306 -u root -p
|
||||
Script que descarga juegos de ZX Spectrum a partir de la base de datos [ZXDB](https://github.com/zxdb/ZXDB) (MySQL en Docker).
|
||||
|
||||
Password
|
||||
## Requisitos
|
||||
|
||||
unJEPimbJddHP8
|
||||
- Python 3.x
|
||||
- Docker
|
||||
|
||||
Si la base de dades ja existeix, per seleccionar-la
|
||||
## Setup
|
||||
|
||||
use zxdb
|
||||
### Entorno virtual
|
||||
|
||||
Per descarregar una nova versió, baixar-la desde
|
||||
[GitHub - zxdb/ZXDB: Open database with historical information about Sinclair machines](https://github.com/zxdb/ZXDB)
|
||||
Per executar el fitxer .sql, amb la base de dades zxdb activa:
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
source /ruta/fichero.sql
|
||||
### Configuración
|
||||
|
||||
Per instalar els requisits del script de python
|
||||
Edita `config.py` en la raíz del proyecto. Variables principales:
|
||||
|
||||
pip install -r requirements.txt
|
||||
| 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 |
|
||||
|
||||
Per crear un entorn virtual "zxdbenv"
|
||||
## Ejecución
|
||||
|
||||
python3 -m venv zxdbenv
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
python main.py
|
||||
```
|
||||
|
||||
Per activar el entorn "zxdbenv"
|
||||
`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.
|
||||
|
||||
source zxdbenv/bin/activate
|
||||
El estado del último import se guarda en `/tmp/zxdb_state.json`. Una segunda ejecución sin cambios en GitHub omite el import.
|
||||
|
||||
Exemple de fitxer .env
|
||||
Para conectar manualmente a MySQL mientras el contenedor está en marcha:
|
||||
|
||||
DB_USER=root
|
||||
DB_PASSWORD=unJEPimbJddHP8
|
||||
DB_HOST=172.18.0.2
|
||||
DB_PORT=3306
|
||||
DB_NAME=zxdb
|
||||
|
||||
DESTINATION_PATH=/home/sergio/zx/zxdb/games/
|
||||
CACHE_PATH=/home/sergio/zx/zxdb/cache/games/
|
||||
TEMP_FILE=/tmp/zxdb.download.tmp
|
||||
|
||||
SHOULD_CLEAR_DESTINATION_PATH=True
|
||||
SHOULD_SPLIT_MODERN_AND_CLASSIC=True
|
||||
SHOULD_SORT_BY_YEAR=True
|
||||
SHOULD_SORT_BY_LETTER=True
|
||||
|
||||
WAIT=True
|
||||
MIN_WAIT=2
|
||||
MAX_WAIT=4
|
||||
LAST_CLASSIC_YEAR=1993
|
||||
```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`.
|
||||
|
||||
Reference in New Issue
Block a user