# 🚀 Python Project Template

![Python](https://img.shields.io/badge/python-3.13-blue)
![Docker](https://img.shields.io/badge/docker-ready-blue)
![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)
![License](https://img.shields.io/badge/license-MIT%20-green)

Универсальный шаблон для создания 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-проектов**, который избавляет от повторяющейся настройки инфраструктуры.