add README
This commit is contained in:
parent
34c5fc2b7b
commit
93b18897a2
|
|
@ -0,0 +1,115 @@
|
||||||
|
# Proyecto PSP — Interfaz de utilidades (Tkinter)
|
||||||
|
|
||||||
|
Descripción
|
||||||
|
-----------
|
||||||
|
Aplicación de escritorio en Python que agrupa varias utilidades en una sola interfaz:
|
||||||
|
navegador, scraping, monitor de recursos, copias de seguridad, reproductor de audio,
|
||||||
|
alarmas y una mini‑app (carreras). La GUI está implementada con Tkinter y aprovecha
|
||||||
|
módulos opcionales para funcionalidades avanzadas.
|
||||||
|
|
||||||
|
Estructura del repositorio
|
||||||
|
--------------------------
|
||||||
|
- `proyecto.py` — Código fuente principal con la GUI y todas las utilidades.
|
||||||
|
- `backup/` — Carpeta destino para copias de seguridad generadas por la app.
|
||||||
|
- `scrapping/` — Carpeta donde se guardan resultados de scraping.
|
||||||
|
- `__pycache__/` — Caché de Python (no versionar).
|
||||||
|
|
||||||
|
Requisitos
|
||||||
|
----------
|
||||||
|
- Python 3.8+
|
||||||
|
- Dependencias requeridas:
|
||||||
|
- psutil
|
||||||
|
- Dependencias opcionales (habilitan funcionalidades extra):
|
||||||
|
- requests, beautifulsoup4 — scraping y OpenWeather
|
||||||
|
- matplotlib — monitor de recursos en ventana gráfica
|
||||||
|
- pygame — reproducción de audio local (fallback a `afplay` en macOS)
|
||||||
|
|
||||||
|
Instalación (recomendado con entorno virtual)
|
||||||
|
----------------------------------------------
|
||||||
|
```sh
|
||||||
|
python -m venv .venv
|
||||||
|
# macOS / Linux
|
||||||
|
source .venv/bin/activate
|
||||||
|
# Windows PowerShell
|
||||||
|
.venv\Scripts\Activate.ps1
|
||||||
|
|
||||||
|
pip install --upgrade pip
|
||||||
|
pip install psutil
|
||||||
|
# opcionales según uso:
|
||||||
|
pip install requests beautifulsoup4 matplotlib pygame
|
||||||
|
```
|
||||||
|
|
||||||
|
Ejecución
|
||||||
|
---------
|
||||||
|
```sh
|
||||||
|
python proyecto.py
|
||||||
|
```
|
||||||
|
La aplicación abrirá la ventana principal; desde ella se accede a todas las utilidades.
|
||||||
|
|
||||||
|
Características principales
|
||||||
|
---------------------------
|
||||||
|
- Visualización y actualización de fecha/hora: función [`proyecto.update_time`](proyecto.py)
|
||||||
|
- Abrir navegador (directo o por diálogo): [`proyecto.launch_browser`](proyecto.py), [`proyecto.launch_browser_prompt`](proyecto.py)
|
||||||
|
- Ejecutar script PowerShell y backup de archivos/carpetas: [`proyecto.run_backup_script`](proyecto.py), [`proyecto._copy_path_to_backup`](proyecto.py), [`proyecto.backup_ui`](proyecto.py)
|
||||||
|
- Scraping web y guardado en `scrapping/`: [`proyecto.scrape_url`](proyecto.py)
|
||||||
|
- Consulta OpenWeather (persistencia de API key): [`proyecto.fetch_weather_xabia`](proyecto.py), borrar key con [`proyecto.clear_openweather_key`](proyecto.py)
|
||||||
|
- Monitor de recursos con matplotlib (si instalado): [`proyecto.open_resource_window`](proyecto.py)
|
||||||
|
- Reproductor de música (pygame o afplay): [`proyecto.play_music_file`](proyecto.py), parada con [`proyecto.stop_music`](proyecto.py)
|
||||||
|
- Alarmas programables: [`proyecto.set_alarm_minutes`](proyecto.py), cancelar con [`proyecto.cancel_alarm`](proyecto.py)
|
||||||
|
- Juego de carreras (canvas): [`proyecto.open_game_race`](proyecto.py)
|
||||||
|
- Abrir aplicaciones macOS con `open`: [`proyecto.launch_app`](proyecto.py)
|
||||||
|
- Monitor de red en la barra de estado: [`proyecto.network_monitor`](proyecto.py)
|
||||||
|
|
||||||
|
Configuración y datos sensibles
|
||||||
|
-------------------------------
|
||||||
|
- OpenWeather API key (opcional) se guarda en:
|
||||||
|
`$HOME/.config/proyecto/openweather.key`
|
||||||
|
Usa la opción "Borrar OpenWeather Key" en la UI o la función [`proyecto.clear_openweather_key`](proyecto.py) para eliminarla.
|
||||||
|
- Carpetas `backup/` y `scrapping/` se crean automáticamente al usar las utilidades correspondientes.
|
||||||
|
|
||||||
|
Buenas prácticas y recomendaciones
|
||||||
|
----------------------------------
|
||||||
|
- Añadir `.gitignore` para excluir `__pycache__/`, `.venv/` y ficheros de configuración local.
|
||||||
|
- Mantener un `requirements.txt` o `pyproject.toml` para el control de dependencias.
|
||||||
|
- Separar funcionalidades en módulos (p. ej. `ui.py`, `utils/backup.py`, `utils/scrape.py`) para mejorar mantenibilidad.
|
||||||
|
- Añadir tests unitarios y/o pruebas de integración manuales para las utilidades críticas.
|
||||||
|
|
||||||
|
Propuestas de archivo adicional sugerido
|
||||||
|
---------------------------------------
|
||||||
|
- `.gitignore` (ejemplo mínimo):
|
||||||
|
```
|
||||||
|
__pycache__/
|
||||||
|
.venv/
|
||||||
|
*.pyc
|
||||||
|
*.key
|
||||||
|
```
|
||||||
|
|
||||||
|
- `requirements.txt` (sugerido):
|
||||||
|
```
|
||||||
|
psutil
|
||||||
|
requests
|
||||||
|
beautifulsoup4
|
||||||
|
matplotlib
|
||||||
|
pygame
|
||||||
|
```
|
||||||
|
|
||||||
|
Contribuir
|
||||||
|
----------
|
||||||
|
1. Abrir un issue describiendo el bug o la mejora.
|
||||||
|
2. Hacer fork y branch con nombre descriptivo.
|
||||||
|
3. Añadir cambios y pruebas manuales.
|
||||||
|
4. Enviar pull request con descripción y pasos para reproducir.
|
||||||
|
|
||||||
|
Solución de problemas comunes
|
||||||
|
-----------------------------
|
||||||
|
- Si falta `matplotlib` verás advertencia: instala `pip install matplotlib`.
|
||||||
|
- Para reproducción de audio en macOS se usa `afplay` como fallback; en Linux/Windows proporciona `pygame`.
|
||||||
|
- Si la consulta a OpenWeather devuelve 401, la app pregunta si quieres borrar la key persistida y reintroducirla.
|
||||||
|
|
||||||
|
Licencia
|
||||||
|
--------
|
||||||
|
Añade un archivo `LICENSE` según la política del proyecto (ej. MIT, Apache‑2.0).
|
||||||
|
|
||||||
|
Contacto
|
||||||
|
--------
|
||||||
|
Abrir un issue en este repositorio para dudas técnicas o propuestas de mejora.
|
||||||
Loading…
Reference in New Issue