272 lines
6.7 KiB
Markdown
272 lines
6.7 KiB
Markdown
# 🚀 Python Project Template
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Универсальный шаблон для создания Python-проектов с уже настроенной инфраструктурой разработки, тестирования и контейнеризации.
|
||
|
||
Этот репозиторий позволяет начать новый проект **за несколько минут**, не тратя время на настройку инструментов и окружения.
|
||
|
||
Шаблон задаёт единый стандарт для Python-проектов:
|
||
|
||
- одинаковая структура проекта
|
||
- единые инструменты разработки
|
||
- воспроизводимое окружение
|
||
- готовая инфраструктура для запуска и деплоя
|
||
|
||
---
|
||
|
||
# 📚 Содержание
|
||
|
||
- [Быстрый старт](#-быстрый-старт)
|
||
- [Что входит в шаблон](#-что-входит-в-шаблон)
|
||
- [Структура проекта](#-структура-проекта)
|
||
- [Docker](#-docker)
|
||
- [Контроль качества кода](#-контроль-качества-кода)
|
||
- [Тестирование](#-тестирование)
|
||
- [Миграции базы данных](#-миграции-базы-данных)
|
||
- [Локализация](#-локализация)
|
||
- [Changelog](#-changelog)
|
||
- [Workflow разработки](#-workflow-разработки)
|
||
- [Release процесс](#-release-процесс)
|
||
- [Для каких проектов подходит](#-для-каких-проектов-подходит)
|
||
|
||
---
|
||
|
||
# ⚡ Быстрый старт
|
||
|
||
Клонируйте репозиторий:
|
||
|
||
```bash
|
||
git clone <repository>
|
||
cd project
|
||
````
|
||
|
||
Установите зависимости:
|
||
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
Запустите приложение:
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
---
|
||
|
||
# 🐳 Docker
|
||
|
||
Собрать и запустить контейнер:
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
Docker-конфигурация включает:
|
||
|
||
* production-ready `Dockerfile`
|
||
* multi-stage сборку
|
||
* оптимизацию размера образа
|
||
* запуск контейнера без root
|
||
* healthcheck контейнера
|
||
|
||
---
|
||
|
||
# ✨ Что входит в шаблон
|
||
|
||
В репозитории уже настроены основные инструменты разработки.
|
||
|
||
## Контейнеризация
|
||
|
||
* Docker
|
||
* Docker Compose
|
||
* оптимизированная сборка контейнера
|
||
|
||
## Проверка кода
|
||
|
||
* Ruff — линтер и автоформатирование
|
||
* mypy — статическая типизация
|
||
* bandit — анализ безопасности
|
||
* detect-secrets — обнаружение секретов
|
||
|
||
## Автоматические проверки
|
||
|
||
* pre-commit
|
||
* проверки YAML и JSON
|
||
* контроль merge конфликтов
|
||
* обнаружение больших файлов
|
||
|
||
---
|
||
|
||
# 🧹 Контроль качества кода
|
||
|
||
Перед каждым коммитом автоматически запускаются проверки:
|
||
|
||
* линтинг
|
||
* проверка типов
|
||
* анализ безопасности
|
||
* поиск секретов
|
||
* базовые проверки репозитория
|
||
|
||
Установка pre-commit:
|
||
|
||
```bash
|
||
pre-commit install
|
||
```
|
||
|
||
---
|
||
|
||
# 🧪 Тестирование
|
||
|
||
В проекте используется **pytest**.
|
||
|
||
Особенности:
|
||
|
||
* строгая конфигурация
|
||
* поддержка asyncio
|
||
* контроль предупреждений
|
||
* удобный вывод ошибок
|
||
|
||
Тесты располагаются в каталоге:
|
||
|
||
```
|
||
tests/
|
||
```
|
||
|
||
Запуск тестов:
|
||
|
||
```bash
|
||
pytest
|
||
```
|
||
|
||
---
|
||
|
||
# 🗄 Миграции базы данных
|
||
|
||
В проекте настроен **Alembic**.
|
||
|
||
Он используется для:
|
||
|
||
* управления миграциями базы данных
|
||
* отслеживания изменений схемы
|
||
* безопасного обновления структуры БД
|
||
|
||
---
|
||
|
||
# 🌍 Локализация
|
||
|
||
Настроен **Babel** для поддержки переводов и интернационализации.
|
||
|
||
Это позволяет легко реализовать многоязычные приложения.
|
||
|
||
---
|
||
|
||
# 📜 Changelog
|
||
|
||
Используется **git-cliff** для автоматической генерации `CHANGELOG`.
|
||
|
||
Changelog формируется на основе conventional commits.
|
||
|
||
---
|
||
|
||
# 📁 Структура проекта
|
||
|
||
Рекомендуемая структура:
|
||
|
||
```
|
||
project/
|
||
│
|
||
├ src/
|
||
│ └ app/
|
||
│ └ main.py
|
||
│
|
||
├ tests/
|
||
│
|
||
├ migrations/
|
||
│
|
||
├ Dockerfile
|
||
├ docker-compose.yml
|
||
│
|
||
├ pyproject.toml
|
||
├ pytest.ini
|
||
│
|
||
└ README.md
|
||
```
|
||
|
||
---
|
||
|
||
# 🔧 Workflow разработки
|
||
|
||
Типичный рабочий процесс:
|
||
|
||
1. создать новую ветку
|
||
|
||
```bash
|
||
git checkout -b feature/my-feature
|
||
```
|
||
|
||
2. внести изменения
|
||
|
||
3. выполнить проверки
|
||
|
||
```bash
|
||
pre-commit run --all-files
|
||
pytest
|
||
```
|
||
|
||
4. сделать коммит
|
||
|
||
```bash
|
||
git commit -m "feat: add new feature"
|
||
```
|
||
|
||
5. отправить изменения
|
||
|
||
```bash
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
# 🚀 Release процесс
|
||
|
||
Релизы создаются с использованием **conventional commits**.
|
||
|
||
История изменений генерируется автоматически:
|
||
|
||
```bash
|
||
git cliff
|
||
```
|
||
|
||
---
|
||
|
||
# 🧩 Для каких проектов подходит
|
||
|
||
Этот шаблон можно использовать для:
|
||
|
||
* backend сервисов
|
||
* API
|
||
* Telegram-ботов
|
||
* CLI инструментов
|
||
* микросервисов
|
||
* автоматизационных сервисов
|
||
|
||
Он не привязан к конкретному фреймворку и может использоваться как универсальная база для Python-разработки.
|
||
|
||
---
|
||
|
||
# 🎯 Цель шаблона
|
||
|
||
Этот репозиторий помогает:
|
||
|
||
* ускорить запуск новых проектов
|
||
* стандартизировать структуру кода
|
||
* упростить разработку и деплой
|
||
* внедрить единые инженерные практики
|
||
|
||
Это **фундамент для Python-проектов**, который избавляет от повторяющейся настройки инфраструктуры.
|