Metadata-Version: 2.4
Name: telegram-dl
Version: 2.0.1
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)
![Tests](https://img.shields.io/badge/tests-27%20passed-green)
![Code Quality](https://img.shields.io/badge/code%20quality-production%20ready-blue)

**Download videos from your own Telegram channels and groups easily.**

> This tool uses Telegram's official API - the same way the Telegram app works. It's 100% legal according to Telegram's Terms of Service.

## Installation

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

## Quick Start (3 Steps)

### Step 1: Get Telegram API Credentials (Free)

1. Go to [my.telegram.org](https://my.telegram.org)
2. Login with your phone number
3. Click **"API development tools"**
4. Click **"Create application"**
5. Copy your **API ID** and **API Hash**

### Step 2: Find Your Channel ID

```bash
# Run this command with your credentials
telegram-dl --api-id YOUR_API_ID --api-hash YOUR_API_HASH --phone +1234567890 --list-channels
```

You'll see a list like:
```
Available channels and groups:

  [Channel] -1001234567890 | My Learning Videos
  [Channel] -1009876543210 | Course Materials
  [Group]   -1001112223334 | Study Group
```

### Step 3: Download Videos

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

## Is This Legal?

**Yes, absolutely!**

This tool uses **Telegram's Official API**, which is the same API used by:
- The official Telegram app
- Telegram Desktop
- Telegram Web
- Many other Telegram clients

**What this means:**
- ✅ Downloads videos from channels you are a member of
- ✅ Uses MTProto protocol (Telegram's official protocol)
- ✅ Your credentials stay on your device
- ✅ No data is sent to third parties

**What you can do:**
- ✅ Download your own content
- ✅ Download content from channels you joined
- ✅ Backup your purchased courses

**What you cannot do:**
- ❌ Download from private channels you're not a member of
- ❌ Redistribute copyrighted content
- ❌ Violate channel/group rules

Read more: [Telegram API Terms](https://core.telegram.org/api/terms)

## Features

### For Users
- **Easy to use** - Just 3 commands to get started
- **Progress tracking** - See download progress with progress bars
- **Skip existing** - Don't re-download files you already have
- **Multiple retry** - Automatically retries failed downloads
- **Custom output** - Save to any folder you want

### For Developers (Interview Ready!)
- **Production-Ready Code** - Clean architecture with SOLID principles
- **Design Patterns** - Builder, Factory, Observer, Repository, Strategy
- **Type Safety** - Full Pydantic validation
- **Well Tested** - 27 unit tests
- **Documented** - Comprehensive docstrings
- **Extensible** - Easy to add new features

## How It Works

### Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                        You (User)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    CLI Interface                            │
│            (Commands: --list-channels, --download)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  TelegramDownloader                        │
│    - Manages connection                                    │
│    - Handles downloads                                     │
│    - Notifies progress                                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Telethon Library (Official API)                │
│    - MTProto Protocol                                      │
│    - Encryption                                             │
│    - Session Management                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Telegram Servers                          │
└─────────────────────────────────────────────────────────────┘
```

### Data Flow

```
1. You provide credentials
         ↓
2. Tool connects to Telegram (using MTProto)
         ↓
3. Tool authenticates you (same as Telegram app)
         ↓
4. Tool fetches your channel list
         ↓
5. You select channel to download
         ↓
6. Tool iterates through messages
         ↓
7. For each video:
   - Check if already downloaded
   - Download video file
   - Update progress
         ↓
8. Done! Videos saved to your computer
```

## Code Examples

### Simple Usage

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

async def main():
    # Your credentials
    credentials = TelegramCredentials(
        api_id=12345,
        api_hash="abc123def456",
        phone="+1234567890"
    )
    
    # Download videos
    async with TelegramDownloader(credentials) as dl:
        results = await dl.download_all_videos(-1001234567890)
        
    print(f"Downloaded {len(results)} videos!")

asyncio.run(main())
```

### With Progress Bar

```python
from telegram_dl import TelegramDownloader
from telegram_dl.patterns import ProgressBarObserver

downloader = TelegramDownloader(credentials)
downloader.attach_observer(ProgressBarObserver())

async with downloader as dl:
    await dl.download_all_videos(-1001234567890)
```

### Using Builder Pattern

```python
from telegram_dl import DownloaderBuilder

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

## Design Patterns Used

| Pattern | Where Used | Why |
|---------|-----------|-----|
| **Builder** | `DownloaderBuilder` | Flexible configuration |
| **Factory** | `RetryStrategyFactory` | Create retry strategies |
| **Observer** | `ProgressBarObserver` | Notify progress updates |
| **Repository** | `VideoRepository` | Manage video data |
| **Strategy** | Retry strategies | Swap algorithms easily |

## SOLID Principles

| Principle | Implementation |
|-----------|---------------|
| **Single Responsibility** | Each class has one job |
| **Open/Closed** | Add features without modifying existing code |
| **Liskov Substitution** | Swap implementations easily |
| **Interface Segregation** | Small, focused interfaces |
| **Dependency Inversion** | Depend on abstractions |

## Project Structure

```
telegram-dl/
├── telegram_dl/
│   ├── __init__.py          # Package exports
│   ├── cli.py               # Command-line interface
│   ├── client.py            # Main downloader class
│   ├── exceptions.py        # Custom exceptions
│   ├── models.py            # Pydantic data models
│   └── patterns.py          # Design patterns
├── tests/
│   ├── conftest.py          # Test fixtures
│   └── test_telegram_dl.py  # Unit tests (27 tests)
├── pyproject.toml           # Package configuration
└── README.md                # This file
```

## Building From Source

```bash
# Clone the repository
git clone https://github.com/kuldeep27396/telegram-dl
cd telegram-dl

# Install dependencies
pip install -e .

# Run tests
pytest tests/ -v

# Build package
rm -rf dist/
python -m build

# Publish to PyPI
twine upload dist/*
```

## Requirements

- Python 3.10 or higher
- Telegram API credentials (free from [my.telegram.org](https://my.telegram.org))

### Dependencies

| Package | Purpose |
|---------|---------|
| telethon | Telegram API client |
| pydantic | Data validation |
| tenacity | Retry logic |
| tqdm | Progress bars |

## CLI Options

```bash
# Required
--api-id          Your Telegram API ID
--api-hash        Your Telegram API Hash
--phone           Your phone number (+1234567890)

# Optional
--channel         Channel ID to download from
--output          Output directory (default: ./telegram_videos)
--session         Session name (default: telegram_dl_session)
--list-channels   Show all your channels
--with-progress   Show progress bars
--log-level       Logging level (DEBUG, INFO, WARNING, ERROR)
```

## Error Handling

The tool handles these errors gracefully:

| Error | What Happens |
|-------|-------------|
| Wrong credentials | Prompts to check API ID/Hash |
| 2FA enabled | Prompts for password |
| Channel not found | Shows available channels |
| Network error | Auto-retries with backoff |
| Download failed | Logs error, continues with next |

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run tests: `pytest tests/ -v`
4. Submit a pull request

## License

MIT License - free to use, modify, and distribute.

## Links

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

---

**Made with ❤️ for developers who want to learn from Telegram courses**
