Refactor code structure for improved readability and maintainability

2026-05-27 17:06:39 +03:00
parent d06bd989f3
commit 59aaa9c4d7
31 changed files with 1416 additions and 543 deletions
@@ -0,0 +1,107 @@
+# 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/workflows/release.yml: повторный прогон quality/tests на теге и публикация в Gitea Packages только после их успеха
+
+Публикация настроена в Gitea PyPI registry по документации Gitea Packages.
+
+Нужные secrets для release 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 тега вида v* и только после успешных lint/typecheck/test jobs.
+
+Локально тот же сценарий можно выполнить так:
+
+```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 publish-gitea
+```