telegram-dl 2.0.0

A production-ready Python CLI tool to download videos from Telegram channels

telegram-dl

A production-ready Python CLI tool to download videos from Telegram channels.

Installation

pip install telegram-dl

Quick Start

1. Get Telegram API Credentials

1. Go to my.telegram.org
2. Log in with your phone number
3. Click "API development tools"
4. Create a new app
5. Copy your API ID and API Hash

2. Download Videos

# List your channels first
telegram-dl --api-id 12345 --api-hash abc123def456 --phone [phone] --list-channels

# Download all videos from a channel
telegram-dl --api-id 12345 --api-hash abc123def456 --phone [phone] --channel -1001234567890

# With progress bar
telegram-dl --api-id 12345 --api-hash abc123def456 --phone [phone] --channel -1001234567890 --with-progress

Programmatic Usage

from telegram_dl import TelegramDownloader, TelegramCredentials
import asyncio

async def main():
    credentials = TelegramCredentials(
        api_id=12345,
        api_hash="abc123def456",
        phone="[phone]"
    )
    
    async with TelegramDownloader(credentials) as dl:
        # List channels
        channels = await dl.get_dialogs()
        for ch in channels:
            print(f"{ch.id} | {ch.title}")
        
        # Download all videos
        results = await dl.download_all_videos(channel_id)

asyncio.run(main())

Architecture & Design Patterns

SOLID Principles

Principle	Implementation
Single Responsibility	Each class has one job (Client, Repository, Builder, etc.)
Open/Closed	Open for extension via Strategy pattern
Liskov Substitution	Observer and Strategy interfaces allow substitution
Interface Segregation	Small, focused interfaces (Observer, Repository, Factory)
Dependency Inversion	Depend on abstractions (Protocols) not concretions

Design Patterns Used

1. Builder Pattern

downloader = (
    DownloaderBuilder()
    .with_credentials(api_id, api_hash, phone)
    .with_output_dir("./videos")
    .with_retry_strategy("exponential", max_attempts=5)
    .with_progress_bar()
    .with_logging()
    .build()
)

2. Strategy Pattern

# Multiple retry strategies available
strategy = RetryStrategyFactory.create("exponential")  # Exponential backoff
strategy = RetryStrategyFactory.create("fixed", delay=2.0)  # Fixed delay

3. Observer Pattern

downloader.attach_observer(ProgressBarObserver())
downloader.attach_observer(LoggingObserver())

4. Repository Pattern

repo = VideoRepository(client, channel_entity)
videos = await repo.get_all()
video = await repo.get_by_id(123)

5. Factory Pattern

config = ConfigFactory.create_download_config(output_dir="./videos")
strategy = RetryStrategyFactory.create("exponential", max_attempts=3)

Data Models (Pydantic)

All data models use Pydantic v2 for:

• Type validation
• Serialization
• Documentation

from telegram_dl.models import VideoMetadata, DownloadProgress, DownloadResult

# All models are fully typed and validated
video = VideoMetadata(id=1, name="video.mp4", size=1024)

Features

• Production-Ready: Comprehensive error handling, logging, retries
• Type Safe: Full type hints with Pydantic validation
• Design Patterns: Builder, Factory, Observer, Repository, Strategy
• SOLID Principles: Clean, maintainable, extensible code
• Progress Tracking: Real-time progress bars and logging
• Retry Logic: Multiple retry strategies with backoff

Publishing Guide

Manual Publishing to PyPI

# 1. Install build tools
pip install build twine

# 2. Update version in pyproject.toml
# version = "2.0.0"

# 3. Build the package
rm -rf dist/
python -m build

# 4. Upload to PyPI
twine upload dist/*

Requirements

• Python 3.10+
• Telegram API credentials (get from my.telegram.org)
• Dependencies: telethon, pydantic, tenacity, tqdm

Links

• PyPI Package: https://pypi.org/project/telegram-dl/
• GitHub Repository: https://github.com/kuldeep27396/telegram-dl
• Report Issues: https://github.com/kuldeep27396/telegram-dl/issues

License

MIT License