Metadata-Version: 2.5
Name: async-yt-dlp
Version: 0.1.1
Summary: Production-ready, strictly typed async wrapper for yt-dlp
Project-URL: Homepage, https://github.com/baton-spb/AsyncYTDLP
Project-URL: Documentation, https://github.com/baton-spb/AsyncYTDLP#readme
Project-URL: Repository, https://github.com/baton-spb/AsyncYTDLP.git
Project-URL: Issues, https://github.com/baton-spb/AsyncYTDLP/issues
Author: async-yt-dlp contributors
License-Expression: MIT
License-File: LICENSE
Keywords: async,asyncio,download,video,youtube,yt-dlp
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: yt-dlp>=2024.01.01
Provides-Extra: dev
Requires-Dist: coverage>=7.6.0; extra == 'dev'
Requires-Dist: graphifyy>=0.9.64; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: ffmpeg
Requires-Dist: aio-ffmpeg>=0.1.0; extra == 'ffmpeg'
Provides-Extra: full
Requires-Dist: aio-ffmpeg>=0.1.0; extra == 'full'
Requires-Dist: brotli>=1.0.0; extra == 'full'
Requires-Dist: certifi>=2024.01.01; extra == 'full'
Requires-Dist: curl-cffi>=0.5.10; extra == 'full'
Requires-Dist: deno>=2.0.0; extra == 'full'
Requires-Dist: mutagen>=1.47.0; extra == 'full'
Requires-Dist: pycryptodomex>=3.20.0; extra == 'full'
Requires-Dist: requests>=2.31.0; extra == 'full'
Requires-Dist: urllib3>=2.0.0; extra == 'full'
Requires-Dist: websockets>=13.0; extra == 'full'
Requires-Dist: yt-dlp-ejs>=0.8.0; extra == 'full'
Description-Content-Type: text/markdown

# async-yt-dlp

[![CI](https://github.com/baton-spb/AsyncYTDLP/actions/workflows/ci.yml/badge.svg)](https://github.com/baton-spb/AsyncYTDLP/actions)
[![PyPI version](https://img.shields.io/pypi/v/async-yt-dlp.svg)](https://pypi.org/project/async-yt-dlp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Typing: Typed](https://img.shields.io/badge/typing-typed-green.svg)](https://peps.python.org/pep-0561/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<p align="center">
  <b>Высокопроизводительная, строго типизированная асинхронная Python-библиотека обёртка над yt-dlp.</b>
</p>

<p align="center">
  <a href="#возможности">Возможности</a> •
  <a href="#установка">Установка</a> •
  <a href="#быстрый-старт">Быстрый старт</a> •
  <a href="#архитектура">Архитектура</a> •
  <a href="#документация">Документация</a> •
  <a href="#лицензия">Лицензия</a>
</p>

---

`async-yt-dlp` — это универсальный асинхронный SDK / adapter layer над мощным синхронным ядром `yt-dlp`. Библиотека спроектирована для использования в любых современных async-приложениях:
- Telegram-ботах (aiogram, telethon, pyrogram)
- Discord-ботах (discord.py)
- Веб-сервисах и API (FastAPI, Litestar, Aiohttp)
- Фоновых воркерах и очередях (Celery, ARQ, Taskiq)

Библиотека **не зависит** от Telegram или каких-либо веб-фреймворков и является полностью самостоятельным проектом.

---

## Возможности

-  **100% Async Native**: Все блокирующие операции сети, диска и ffmpeg вынесены в системные потоки через `asyncio.to_thread`. Event loop никогда не блокируется.
-  **Строгая типизация**: Модели `MediaInfo`, `FormatInfo`, `DownloadResult`, `ProgressEvent` (PEP 561 `py.typed`, совместимо со строгим режимом `mypy`).
-  **Потокобезопасность**: Изолированный экземпляр `YoutubeDL` на каждую операцию исключает состояние гонки и порчу сессий.
-  **Плавный стриминг прогресса**: Асинхронный генератор `download_with_progress` с адаптивным троттлингом (защита от перегрузки интерфейса и спама).
-  **Контроль параллельности**: Встроенный `DownloadManager` на базе `asyncio.Semaphore` с ограничением емкости очереди (backpressure).
-  **Структурированная конкурентность**: Поддержка `asyncio.TaskGroup` в пакетной загрузке `download_many`.
-  **Честная модель отмены**: Корректная обработка `task.cancel()`, таймаутов `asyncio.timeout` и graceful shutdown.
-  **Безопасность данных**: Автоматическая маскировка паролей, токенов, cookies и прокси в логах; защита от SSRF и протокола `file://`.
-  **Проверка зависимостей**: Встроенная диагностика окружения (`check_dependencies`) для проверки `yt-dlp`, `ffmpeg`, `ffprobe` и JS-движков.

---

## Установка

Требуется Python **3.11+**.

```bash
# Базовая установка:
pip install async-yt-dlp

# С опциональной интеграцией с async-ffmpeg:
pip install "async-yt-dlp[ffmpeg]"

# Полный набор (async-ffmpeg + сетевые акселераторы curl-cffi, websockets и др.):
pip install "async-yt-dlp[full]"
```

Или с использованием `uv`:
```bash
uv add async-yt-dlp
```

---

## Быстрый старт

### 1. Извлечение метаданных видео или плейлиста
```python
import asyncio
from async_yt_dlp import AsyncYTDLP


async def main():
    async with AsyncYTDLP() as ytdlp:
        info = await ytdlp.extract_info("https://www.youtube.com/watch?v=BaW_jenozKc")
        print(f"🎬 {info.title}")
        print(f"👤 Автор: {info.uploader}")
        print(f"⏱ Длительность: {info.duration_seconds} сек.")


if __name__ == "__main__":
    asyncio.run(main())
```

### 2. Скачивание видео с настройками качества
```python
import asyncio
from pathlib import Path
from async_yt_dlp import AsyncYTDLP, YTDLPOptions


async def main():
    options = YTDLPOptions(
        format="bestvideo[height<=720]+bestaudio/best[height<=720]",
        output_path=Path("./downloads"),
        output_template="%(title)s.%(ext)s",
    )

    async with AsyncYTDLP(default_options=options) as ytdlp:
        result = await ytdlp.download("https://www.youtube.com/watch?v=BaW_jenozKc")
        print(f"✅ Файл сохранен: {result.filepath} ({result.file_size} байт)")


if __name__ == "__main__":
    asyncio.run(main())
```

### 3. Стриминг прогресса загрузки в реальном времени
```python
import asyncio
from async_yt_dlp import AsyncYTDLP, DownloadStatus


async def main():
    async with AsyncYTDLP() as ytdlp:
        url = "https://www.youtube.com/watch?v=BaW_jenozKc"

        async for event in ytdlp.download_with_progress(url, throttle_interval=0.5):
            if event.status == DownloadStatus.DOWNLOADING:
                print(
                    f"\rЗагрузка: {event.percent:.1f}% | {event.speed_str} | ETA: {event.eta_str}",
                    end="",
                )
            elif event.status == DownloadStatus.COMPLETE:
                print("\nГотово!")


if __name__ == "__main__":
    asyncio.run(main())
```

---

## Архитектура

```
┌───────────────────────────────────────────────┐
│     Приложение (Telegram, Web, CLI, Bot)      │
└───────────────────────┬───────────────────────┘
                        │
            ┌───────────▼───────────┐
            │       AsyncYTDLP      │  ← Фасад, API, Lifecycle
            └───────────┬───────────┘
                        │
            ┌───────────▼───────────┐
            │    DownloadManager    │  ← Semaphore, Backpressure, Shutdown
            └───────────┬───────────┘
                        │
            ┌───────────▼───────────┐
            │     ThreadBackend     │  ← asyncio.to_thread, изолированный
            └───────────┬───────────┘     экземпляр YoutubeDL на операцию
                        │
            ┌───────────▼───────────┐
            │   yt_dlp.YoutubeDL    │  ← Синхронный движок yt-dlp
            └───────────────────────┘
```

Подробное описание архитектуры доступно в документе [docs/architecture.md](docs/architecture.md).

---

## Документация

Подробные руководства на русском языке находятся в каталоге `docs/`:

1. [Быстрый старт](docs/getting-started.md)
2. [Архитектура и дизайн](docs/architecture.md)
3. [Справочник публичного API](docs/api.md)
4. [Конфигурация YTDLPOptions](docs/configuration.md)
5. [Управление параллельностью](docs/concurrency.md)
6. [Модель отмены и таймауты](docs/cancellation.md)
7. [Отслеживание прогресса](docs/progress.md)
8. [Иерархия исключений](docs/errors.md)
9. [Безопасность и санитизация](docs/security.md)
10. [Производительность и оптимизация](docs/performance.md)
11. [Развертывание и Docker](docs/deployment.md)
12. [Руководство для разработчиков](docs/development.md)
13. [Тестирование](docs/testing.md)
14. [Устранение неполадок](docs/troubleshooting.md)
15. [Миграция с синхронного yt-dlp](docs/migration.md)

---

## Примеры использования

В каталоге `examples/` представлены готовые примеры кода:
- [Простое извлечение информации](examples/simple_extract.py)
- [Скачивание файла](examples/simple_download.py)
- [Отображение прогресса](examples/progress.py)
- [Работа с плейлистами](examples/playlist.py)
- [Извлечение аудио и MP3 конвертация](examples/audio_extraction.py)
- [Продвинутые параметры](examples/custom_options.py)
- [Отмена задач и таймауты](examples/cancellation.py)
- [Пакетная параллельная загрузка](examples/concurrency.py)
- [Интеграция с Telegram-ботом на aiogram 3.x](examples/integrations/telegram_aiogram.py)

---

## Лицензия

Проект распространяется под лицензией MIT. Подробнее см. в файле [LICENSE](LICENSE).
