Metadata-Version: 2.4
Name: telegram-dl
Version: 2.0.0
Summary: A production-ready Python CLI tool to download videos from Telegram channels
Author-email: KD <kd@example.com>
License: MIT
Project-URL: Homepage, https://github.com/kuldeep27396/telegram-dl
Project-URL: Repository, https://github.com/kuldeep27396/telegram-dl
Project-URL: Issues, https://github.com/kuldeep27396/telegram-dl/issues
Keywords: telegram,download,video,cli,pydantic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: telethon>=1.35.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: tqdm>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# telegram-dl

![PyPI Version](https://img.shields.io/pypi/v/telegram-dl)
![Python Versions](https://img.shields.io/pypi/pyversions/telegram-dl)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![GitHub Release](https://img.shields.io/github/v/release/kuldeep27396/telegram-dl)

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

## Installation

```bash
pip install telegram-dl
```

## Quick Start

### 1. Get Telegram API Credentials

1. Go to [my.telegram.org](https://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

```bash
# List your channels first
telegram-dl --api-id 12345 --api-hash abc123def456 --phone +1234567890 --list-channels

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

# With progress bar
telegram-dl --api-id 12345 --api-hash abc123def456 --phone +1234567890 --channel -1001234567890 --with-progress
```

## Programmatic Usage

```python
from telegram_dl import TelegramDownloader, TelegramCredentials
import asyncio

async def main():
    credentials = TelegramCredentials(
        api_id=12345,
        api_hash="abc123def456",
        phone="+1234567890"
    )
    
    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 |
|-----------|----------------|
| **S**ingle Responsibility | Each class has one job (Client, Repository, Builder, etc.) |
| **O**pen/Closed | Open for extension via Strategy pattern |
| **L**iskov Substitution | Observer and Strategy interfaces allow substitution |
| **I**nterface Segregation | Small, focused interfaces (Observer, Repository, Factory) |
| **D**ependency Inversion | Depend on abstractions (Protocols) not concretions |

### Design Patterns Used

#### 1. Builder Pattern
```python
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
```python
# Multiple retry strategies available
strategy = RetryStrategyFactory.create("exponential")  # Exponential backoff
strategy = RetryStrategyFactory.create("fixed", delay=2.0)  # Fixed delay
```

#### 3. Observer Pattern
```python
downloader.attach_observer(ProgressBarObserver())
downloader.attach_observer(LoggingObserver())
```

#### 4. Repository Pattern
```python
repo = VideoRepository(client, channel_entity)
videos = await repo.get_all()
video = await repo.get_by_id(123)
```

#### 5. Factory Pattern
```python
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

```python
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

```bash
# 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](https://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
