# yt-shorts-downloader

Библиотека и CLI для скачивания YouTube Shorts через Netscape cookie session.

Целевой контракт публичного API:

- вход: ссылка YouTube и путь к session file
- выход: бинарный MP4 в памяти для интеграции в API

## Установка

Для использования библиотеки:

```bash
uv pip install .
```

Для разработки:

```bash
uv sync --group dev
```

## Использование библиотеки

```python
from yt_shorts_downloader import download

video = download(
		"https://www.youtube.com/shorts/VIDEO_ID",
		"cookies.txt",
)

assert video.media_type == "video/mp4"
binary_mp4 = video.content
filename = video.filename
```

Если нужен файл на диске, используйте вспомогательную функцию:

```python
from yt_shorts_downloader import download_to_path

file_path = download_to_path(
		"https://www.youtube.com/shorts/VIDEO_ID",
		"cookies.txt",
		output_dir="downloads",
)
```

## CLI

```bash
uv run yt-shorts-downloader \
	"https://www.youtube.com/shorts/VIDEO_ID" \
	cookies.txt \
	--output-dir downloads
```

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

- src/yt_shorts_downloader/api.py: публичный API библиотеки
- src/yt_shorts_downloader/models: доменные модели
- src/yt_shorts_downloader/services: валидация и разбор session file
- src/yt_shorts_downloader/core: интеграция с yt-dlp и инфраструктурные функции
- stubs: локальные mypy stubs для внешних зависимостей без полной типизации

## Качество

- mypy работает в strict-режиме
- runtime-зависимости лежат в секции project.dependencies
- инструменты разработки лежат в секции dependency-groups.dev

Основные команды:

```bash
make format
make ci-check
make test
make build
```

## CI/CD

В репозитории добавлены Gitea Actions workflow:

- .gitea/workflows/ci.yml: lint, mypy, deptry, pytest и автоматическая публикация в Gitea Packages после успешного CI на push в main

Публикация настроена в Gitea PyPI registry по документации Gitea Packages.
Версия пакета берётся из секции [project] -> version в pyproject.toml.

Нужные secrets для CI workflow:

- GITEA_PYPI_REPOSITORY_URL: полный endpoint вида https://gitea.example.com/api/packages/<owner>/pypi
- GITEA_PACKAGE_USERNAME: пользователь Gitea
- GITEA_PACKAGE_TOKEN: personal access token с правом package write

Публикация идёт автоматически на push в main после успешных lint/typecheck/test jobs.
Если версия пакета уже существует в registry, upload будет пропущен через --skip-existing.
Если версия в pyproject.toml увеличена, в Gitea Packages появится новая версия пакета, а старые версии останутся доступными.

Локально тот же сценарий можно выполнить так:

```bash
export GITEA_PYPI_REPOSITORY_URL="https://gitea.example.com/api/packages/<owner>/pypi"
export GITEA_PACKAGE_USERNAME="<username>"
export GITEA_PACKAGE_TOKEN="<token>"
make package-version
make publish-gitea
```