Compare-Bot

IL TUO BOT DI FIDUCIA PER FARE IL MONELLO CON I VIDEO!

Mini progetto realizzato per il corso di Quality Development UNICT DMI 2025/2026 - Docente Borzì S.

Bot Telegram per il download di contenuti multimediali (video e audio) da piattaforme come YouTube, Instagram, TikTok e molte altre.

---

Indice

• Panoramica
• Comandi
• Funzionalità
  • Download multimediale
  • Beauty of the Day
  • Internazionalizzazione (i18n)
• Architettura
• Tech Stack
• Setup
• Variabili d'ambiente
• Testing
• CI/CD
• Team

---

Panoramica

CompareBot è un bot Telegram asincrono che permette di scaricare contenuti multimediali da oltre 1000 piattaforme supportate da yt-dlp. Offre supporto multilingua (italiano e inglese), un sistema di pulsanti inline per la selezione del formato e della risoluzione, e una funzionalità giornaliera di ispirazione visiva tramite l'API Pixabay.

---

Comandi

Comando	Descrizione
/start	Messaggio di benvenuto personalizzato con il nome dell'utente
/download <url>	Scarica audio (MP3) o video (MP4) da un URL supportato
/beauty	Invia la "beauty of the day" — un'immagine casuale di una bella ragazza
/service	Mostra l'elenco dei servizi disponibili
/about	Informazioni sul progetto e sul team
/lang <it|en>	Cambia la lingua dell'interfaccia del bot

---

Funzionalità

Download multimediale

Il comando /download <url> avvia il flusso di download:

1. Validazione URL — l'URL viene verificato tramite la libreria validators
2. Scelta del formato — l'utente seleziona tramite pulsanti inline:
   • Audio (MP3) — estrae l'audio alla migliore qualita disponibile
   • Video (MP4) — presenta un secondo menù per la scelta della risoluzione
3. Scelta della risoluzione (solo video) — 360p, 480p o 720p
4. Download — il file viene scaricato in modo asincrono tramite yt-dlp con merge audio/video via ffmpeg
5. Invio e pulizia — il file viene inviato all'utente su Telegram e rimosso automaticamente dal server

Vincoli:

• Limite dimensione file Telegram: 50 MB
• I file temporanei vengono salvati con prefisso UUID univoco

Beauty of the Day

Il comando /beauty invia un'immagine casuale dalla Pixabay API:

• Query di ricerca: woman,models,real,beauty,pose
• Cache giornaliera: l'immagine viene scaricata una sola volta al giorno
• Lock di concorrenza: previene download multipli simultanei
• 150 immagini per chiamata API per massimizzare la varietà

Internazionalizzazione (i18n)

Il bot supporta italiano e inglese:

• I file di traduzione si trovano in lang/it.json e lang/en.json
• La preferenza linguistica dell'utente viene salvata in users.json
• Gli ID utente vengono hashati con SHA-256 + salt prima dello storage per proteggere la privacy
• Lingua di default: inglese
• Fallback: se una chiave di traduzione manca, viene restituita la chiave stessa

---

Architettura

CompareBot/
├── main.py                  # Entry point — polling con 256 update concorrenti
├── src/
│   ├── handlers.py          # Gestione comandi (/start, /download, /about, /service, /beauty, /lang)
│   ├── buttons.py           # Menu inline, selezione formato/risoluzione, logica di download
│   ├── messages.py          # Recupero stringhe localizzate
│   ├── logo.py              # Logo ASCII art
│   └── core/
│       ├── downloader.py    # Wrapper yt-dlp + ffmpeg per estrazione audio/video
│       ├── beauty.py        # Integrazione API Pixabay con cache giornaliera
│       └── i18n.py          # Sistema di internazionalizzazione e gestione preferenze utente
├── lang/
│   ├── en.json              # Traduzioni inglese
│   └── it.json              # Traduzioni italiano
├── tests/
│   ├── test_handlers.py     # Test dei command handler
│   ├── test_buttons.py      # Test pulsanti inline e logica download
│   ├── test_messages.py     # Test recupero messaggi
│   └── core/
│       ├── test_downloader.py   # Test funzionalita downloader
│       ├── test_beauty.py       # Test feature beauty
│       └── test_i18n.py         # Test sistema i18n
├── img/
│   └── logo.png             # Logo del progetto
├── .github/workflows/
│   ├── lint.yml             # Pipeline di linting
│   └── test.yml             # Pipeline di testing
├── requirements.txt         # Dipendenze di produzione
├── requirements_dev.txt     # Dipendenze di sviluppo
├── pyproject.toml           # Configurazione tool (isort, mypy, pytest, coverage)
├── .flake8                  # Configurazione Flake8
├── .pylintrc                # Configurazione Pylint
├── .env.example             # Template variabili d'ambiente
└── localTest.sh             # Script per test locali

---

Tech Stack

Dipendenze di produzione

Pacchetto	Ruolo
python-telegram-bot[job-queue]	Framework bot Telegram asincrono con job queue
yt-dlp	Downloader universale per video/audio (1000+ piattaforme)
python-dotenv	Gestione variabili d'ambiente da file .env
requests	Chiamate HTTP (API Pixabay)
validators	Validazione URL
ffmpeg (sistema)	Encoding e merge audio/video — richiesto nel PATH

Dipendenze di sviluppo

Pacchetto	Ruolo
pytest + pytest-asyncio	Framework di testing con supporto async
pytest-mock + pytest-cov	Mocking e report di copertura
black	Formattatore di codice
flake8	Linter
isort	Ordinamento import
mypy	Type checker statico
pylint	Analisi statica avanzata
types-requests, types-yt-dlp	Type stub per librerie esterne

---

Setup

Prerequisiti: Git, Python 3.10+, ffmpeg installato nel sistema.

1. Clona il repository

git clone git@github.com:sean8819/CompareBot.git
cd CompareBot

2. Crea e attiva il virtual environment

python -m venv .venv
source .venv/bin/activate

3. Installa le dipendenze

pip install -r requirements.txt
pip install -r requirements_dev.txt   # opzionale, per sviluppo

4. Configura le variabili d'ambiente

cp .env.example .env
# Modifica .env con i tuoi token

5. Avvia il bot

python main.py

---

Variabili d'ambiente

Variabile	Obbligatoria	Descrizione
BOT_TOKEN	Si	Token del bot Telegram (da BotFather)
PIXABAY_TOKEN	Si	Chiave API Pixabay
HASH_SALT	No	Salt per l'hashing degli ID utente (default: fallback_salt)

---

Testing

Il progetto include 55+ test unitari con copertura su tutti i moduli:

File di test	Focus
test_handlers.py	Command handler, validazione parametri, contesto utente
test_buttons.py	Generazione menu, gestione pulsanti, logica download, errori
test_downloader.py	Opzioni yt-dlp, download media, validazione dimensione file
test_beauty.py	Cache immagini, verifica freschezza, integrazione downloader
test_i18n.py	Funzioni hash, database utenti, recupero lingua, fallback
test_messages.py	Funzioni di recupero messaggi

Eseguire i test:

pytest tests/ -v --cov=src --cov-report=term-missing

Eseguire tutti i controlli locali (lint + type check + test):

bash localTest.sh

Lo script esegue in sequenza: black, mypy, pylint, flake8, isort e pytest con coverage.

---

CI/CD

Il progetto utilizza GitHub Actions con due pipeline attivate su push e pull request verso main:

Pipeline di Linting

• Pylint — analisi statica del codice
• Flake8 — controllo errori di sintassi e complessità ciclomatica
• MyPy — type checking statico
• Black — verifica formattazione codice
• isort — verifica ordinamento import

Pipeline di Testing

• pytest con report di copertura sul modulo src/

---

Team

	Nome	GitHub
Studente	Giovanni G.	@sean8819
Studente	Marce	@Marss08
Studente	Vincenzo B.	@buggenzo