🗺️ Roadmap: как работать с шаблоном

Этот раздел поможет тебе разобраться в структуре и содержании основных частей проекта:

  • Как организованы исходные файлы

  • Как работать с конфигурациями

  • Как настроены CI/CD и Docker

🗂️ Структура проекта

📜 Памятка по эмоджи: 📁 - Каталоги и папки 💻 - Настройки компьютера ⚙️ - Конфигурация шаблона 📋 - Текстовые файлы 📐 - Шаблонирование (копирование) 🕵️‍♂️ - Проверка (линтинг, безопасность) 🧱 - Исходный код (src) 🧪 - Тесты 🔄 - CI/CD процессы 🐳 - Докер 🧰 - Автоматизация (make) 📚 - Документация (Sphinx)

Проект организован следующим образом:

projectTemplate/ ├── .github/ # GitHub Actions workflows │ └── workflows/ │ └── deploy_docs.yml # CI/CD для деплоя документации ├── .vscode/ # Настройки VS Code ├── configs/ # Конфигурационные файлы │ ├── config.py # Глобальные параметры проекта │ └── path_manager.py # Утилита для работы с путями ├── diagrams/ # Диаграммы UML │ ├── project_structure.puml # Архитектура проекта │ └── temp_containers.puml # Диаграмма контейнеров ├── docs/ # Документация проекта (Sphinx) │ └── index.rst # Основной файл документации ├── docker-compose.yaml # Конфигурация для Docker Compose ├── Dockerfile # Основной Dockerfile для сборки ├── Makefile # Полезные команды через make ├── README.md # Краткое описание проекта ├── requirements.txt # Зависимости Python ├── src/ # Исходный код │ ├── main.py # Основная точка входа │ └── utils/ # Вспомогательные утилиты │ └── logger.py # Логирование ├── tools/ # Вспомогательные скрипты │ ├── diagram_auto_update.py # Автоматическое обновление диаграмм │ └── print_structure.py # Вывод структуры проекта в терминал ├── tests/ # Тесты └── copier.yaml # Шаблон для генерации нового проекта └── .pre-commit-config.yaml # Конфигурация для Pre-Commit hooks └── .gitignore # Игнорируемые файлы для Git └── .dockerignore # Игнорируемые файлы для Docker └── .env # Переменные окружения └── .env.example # Пример файла .env └── {{ _copier_conf.answers_file }}.jinja # Шаблон Jinja для Copier

💻 Настройки VS Code (.vscode/)

Папка .vscode/ — это директория, которая позволяет настраивать Visual Studio Code для вашего проекта. Она содержит несколько важных файлов, которые могут быть использованы для улучшения вашего рабочего процесса и настройки IDE.

⚙️ settings.json

Этот файл содержит настройки IDE, которые определяют, как будет выглядеть и вести себя редактор.

  • Отступы и форматирование кода (с указанием количества пробелов или символов для отступа).

  • Путь к интерпретатору Python для правильного выполнения кода.

  • Настройки линтинга и автозамены, чтобы поддерживать единый стиль кода по всему проекту.

settings.json
{
  "terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}"
  },

  "terminal.integrated.env.linux": {
    "PYTHONPATH": "${workspaceFolder}"
  },

  "terminal.integrated.env.osx": {
    "PYTHONPATH": "${workspaceFolder}"
  },
  "security.promptForLocalFileProtocolHandling": false,
  "files.autoSave": "afterDelay",
  "editor.renderWhitespace": "all",
  
  "workbench.activityBar.location": "top",
  
  "workbench.secondarySideBar.defaultVisibility": "visible",
  
  "outline.showVariables": false,

  "errorLens.enabled": true,
  "errorLens.messageEnabled": true,
  "errorLens.problemRangeDecorationEnabled": false,
  "errorLens.gutterIconsEnabled": false,
  "errorLens.statusBarMessageEnabled": false,
  "errorLens.enabledDiagnosticLevels": ["error", "warning", "info"],
  "errorLens.messageBackgroundMode": "line",
  "errorLens.severityText": ["⛔", "⚠", "ℹ", "🍏"],
  "errorLens.margin": "4ch",
  "errorLens.alignMessage": {
    "start": 0,
    "end": 0,
    "minimumMargin": 4,
    "padding": [0, 0],
    "useFixedPosition": true
  },

  "workbench.colorCustomizations": {
    "errorLens.errorBackground": "#e454541b",
    "errorLens.warningBackground": "#ff942f1b",
    "errorLens.infoBackground": "#00b7e420",
    "errorLens.hintBackground": "#17a2a220"
  },

  "better-comments.multilineComments": true,
  "better-comments.highlightPlainText": true,

  "better-comments.tags": [
  {
    "tag": "!",
    "color": "#FF2D00",
    "strikethrough": false,
    "underline": false,
    "backgroundColor": "transparent",
    "bold": false,
    "italic": false
  },
  {
    "tag": "?",
    "color": "#3498DB",
    "strikethrough": false,
    "underline": false,
    "backgroundColor": "transparent",
    "bold": false,
    "italic": false
  },
  {
    "tag": "//",
    "color": "#474747",
    "strikethrough": true,
    "underline": false,
    "backgroundColor": "transparent",
    "bold": false,
    "italic": false
  },
  {
    "tag": "todo",
    "color": "#FF8C00",
    "strikethrough": false,
    "underline": false,
    "backgroundColor": "transparent",
    "bold": false,
    "italic": false
  },
  {
    "tag": "*",
    "color": "#98C379",
    "strikethrough": false,
    "underline": false,
    "backgroundColor": "transparent",
    "bold": false,
    "italic": false
  }
],
"workbench.iconTheme": "vscode-icons"



}

⚙️ extensions.json

Этот файл хранит список расширений для VS Code, которые могут улучшить опыт разработки.

extensions.json
{
  "recommendations": [
    "jebbs.plantuml",
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-vscode.makefile-tools",
    "github.vscode-github-actions",
    "ms-azuretools.vscode-docker",
    "ms-vscode-remote.remote-containers",
    "aaron-bond.better-comments",
    "alefragnani.bookmarks",
    "naumovs.color-highlight",
    "usernamehw.errorlens",
    "vscode-icons-team.vscode-icons",
    "tamasfe.even-better-toml",
    "executablebookproject.myst-highlight"
  ]
}

Примечание

VS Code автоматически предложит установить все необходимые расширения при открытии проекта. Но ты можешь сделать это вручную через меню расширений.

Расширения, используемые в этом шаблоне

Категория

Расширение

Описание

🐍 Python-разработка

🔧 Python (Microsoft)

Это основное расширение для разработки на Python. Поддерживает IntelliSense, линтинг, отладку, Jupyter Notebooks, виртуальные окружения и многое другое.

🧠 Pylance (Microsoft)

Быстрый анализатор кода, предоставляющий автодополнение, переход по определению, подсветку ошибок и типизацию (type checking).

🛑 Error Lens (Alexander)

Визуально выделяет ошибки в коде, делая их более заметными.

🐙 GitHub Pull Requests and Issues (GitHub)

Интеграция с GitHub: работа с pull requests, issues, обсуждениями прямо из редактора.

📦 Работа с инфраструктурой и CI/CD

⚙️ Docker (Microsoft)

Инструменты для работы с Docker: сборка образов, управление контейнерами, работа с Docker Compose и реестрами.

📦 GitHub Actions (GitHub)

Интеграция с GitHub Actions: просмотр пайплайнов, запуск, отладка и мониторинг выполнения CI/CD.

🧰 Работа с файлами и форматами

🧩 Even Better TOML (tamasfe)

Расширенная поддержка TOML-файлов: автодополнение, валидация, форматирование.

📄 MyST Highlight (ExecutableBookProject)

Поддержка синтаксиса MyST Markdown, используемого в Sphinx, для красивой документации.

🖌️ Color Highlight (Sergii N)

Подсвечивает цветовые значения (например, #FF5733) прямо в коде, показывая палитру.

📁 Интерфейс и навигация

🎨 VSCode Icons (VSCode Icons Team)

Иконки для файлов и папок в проводнике, улучшающие восприятие структуры проекта.

💡 Better Comments (Aaron Bond)

Выделяет комментарии разных типов (важные, TODO, FIXME и др.) цветом для лучшей читаемости.

📌 Bookmarks (Alessandro Fragnani)

Позволяет ставить закладки в коде для быстрого перехода между важными участками.

🧮 Fold Level (vikyd)

Удобное управление сворачиванием кода по уровням вложенности.

🛠️ Сборка и автоматизация

🛠️ Makefile Tools (Microsoft)

Позволяет работать с Makefile внутри VS Code — запуск целей, навигация, интеграция с редактором.

🌿 Диаграммы и визуализация

🌿 PlantUML (jebbs)

Поддержка создания диаграмм UML прямо в VS Code через синтаксис PlantUML.

⚙️ Конфигурация

📋 requirements.txt

Текстовый файл, в котором перечислены все зависимости, необходимые для работы с проектом. Например, так он выглядит для этого шаблона

requirements.txt
# для вывода цветных логов
colorama

# работа с .env
environs

# Поддержка markdown
myst-parser

# для проверки кода перед коммитом (линтеры, форматирование итд)
pre-commit

# для автоматической генерации документации при помощи sphinx
sphinx
sphinx-autodoc-typehints
sphinx-copybutton
sphinx-intl
sphinxcontrib-plantuml
sphinx-rtd-theme
sphinx-togglebutton

# Библиотека для управления проектами
copier

📁 configs

Папка configs/ содержит файлы, которые отвечают за глобальные настройки проекта и управление путями. Эти файлы помогают централизовать параметры и упрощают управление проектом.

⚙️ configs/config.py

Этот файл содержит глобальные параметры проекта, такие как:

  • Пути к важным файлам и папкам (например, пути для логирования, сохранения данных или конфигураций).

  • Параметры окружения: например, настройки базы данных или API-ключи.

Все эти параметры удобно собирать в одном месте, чтобы облегчить управление проектом и сделать его более гибким.

Модуль конфигурации приложения.

Загружает переменные окружения из файла .env и системных переменных, используя библиотеку environs, и предоставляет централизованный доступ к настройкам через класс Config.

class configs.config.Config[исходный код]

Базовые классы: object

Глобальная конфигурация приложения.

Все параметры считываются из переменных окружения и используются для настройки различных аспектов проекта: базы данных, кэша, API, телеграм-бота, email, логирования, безопасности и т.д.

APP_NAME: str = 'MyApp'
CONFIGS_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/configs')
DIAGRAMS_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/diagrams')
DOCKER_CONTAINER_NAME: str = 'myapp-container'
DOCKER_ENV: str = 'development'
DOCKER_IMAGE_NAME: str = 'myapp-image'
DOCS_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/docs')
GITHUB_WORKFLOWS_DIR = PosixPath('/home/runner/work/projectTemplate/projectTemplate/.github/workflows')
GOOGLE_API_KEY: str = None
GOOGLE_CLIENT_ID: str = None
GOOGLE_CLIENT_SECRET: str = None
GOOGLE_REDIRECT_URI: str = None
LOGS_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/logs')
LOG_LEVEL: str = 'INFO'
MAX_WORKERS: int = 5
NOTES_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/notes')
PROJECT_ROOT: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate')
SRC_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/src')
TELEGRAM_ADMIN_IDS: list[int] = []
TELEGRAM_BOT_TOKEN: str = None
TELEGRAM_CHAT_ID: str = None
TESTS_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/tests')
TIMEZONE: str = 'UTC'
TOOLS_DIR: Path = PosixPath('/home/runner/work/projectTemplate/projectTemplate/tools')

📋 .env и .env.example

Файл .env используется для хранения переменных окружения, которые могут использоваться в проекте. Это обычно конфиденциальные данные, такие как ключи API, пароли и другие настройки, которые не должны быть в коде.

Файл .env.example представляет собой пример файла .env, который содержит шаблон для переменных окружения. Он помогает пользователям проекта понять, какие переменные необходимо настроить для работы приложения.

.env.example
# ----------------------------------------
# Пример файла .env для проекта
# ----------------------------------------
# НЕ ХРАНИТЕ реальные секреты в этом файле!
# Скопируйте .env.example в .env и заполните реальные значения.
#
# Формат: KEY=VALUE
# Комментарии начинаются с #
# Пустые строки игнорируются
# ----------------------------------------

# --- Общие настройки --- 
DEPLOY_USER_NAME=linux-user-name  # Укажите имя юзера линукс, которого вы используете для деплоя на вашем сервере
UID=0000                             # Укажите UID вашего юзера
GID=0000                             # Укажите GID вашего юзера
APP_NAME=your-app-name                # Задайте имя вашего приложения (проще всего указать название директории проекта)
APP_PORT=8000                             # Пример: 8000 для разработки, или любой другой свободный порт (не забудьте открыть его через ufw)
LOG_LEVEL=INFO                   # Регулирует объем логов (для продакшн рекомендуется INFO или выше)
DEBUG=True                            # Включите True для разработки, False для продакшн
TIMEZONE=UTC                     # Используйте правильный часовой пояс для вашего региона
MAX_WORKERS=5                    # Настройте количество параллельных процессов

# --- Docker ---
DOCKER_PORT=8000                      # порт хоста, через который наружу можно обращаться к приложению, работающему внутри контейнера
DOCKER_ENV=development                # Контекст сборки/запуска Docker: dev или prod
DOCKER_IMAGE_NAME=myapp-image         # Имя Docker-образа
DOCKER_CONTAINER_NAME=myapp-container # Имя контейнера Docker

# --- Telegram ---
TELEGRAM_BOT_TOKEN=your-telegram-bot-token  # Получите токен у @BotFather
TELEGRAM_CHAT_ID=your-chat-id-for-notifications  # Используйте Telegram Bot API для получения ID
TELEGRAM_ADMIN_IDS=123456789,987654321,1122334455  # Список ID через запятую

# --- База данных ---
DB_ENGINE=postgresql                  # Тип СУБД: postgresql, mysql, sqlite и др.
DB_HOST=localhost                     # Адрес базы данных (может быть IP или hostname)
DB_PORT=5432                          # Порт базы данных (по умолчанию для PostgreSQL)
DB_NAME=mydatabase                    # Название базы данных
DB_USER=myuser                        # Пользователь базы данных
DB_PASSWORD=mypassword                # Пароль пользователя базы данных
DB_SSL_MODE=prefer                    # SSL режим для подключения: disable, require, verify-ca

# --- Google API ---
GOOGLE_API_KEY=your-google-api-key                 # Ключ API для Google
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com  # OAuth Client ID
GOOGLE_CLIENT_SECRET=your-google-client-secret     # OAuth Client Secret
GOOGLE_REDIRECT_URI=http://localhost:8000/oauth2callback  # URL для редиректа после авторизации

Совет

Перед началом работы создайте в директории проекта файл .env и скопируйте нужные переменные из .env.example.

Не забудьте изменить configs/config.py в соответствии с вашим .env

Предупреждение

Не включай файл .env в систему контроля версий (например, в Git) во избежание утечек ключей и секретов. В данном шаблоне используется .gitignore, чтобы исключить .env из коммитов.

📐 Настройки copier

⚙️ copier.yaml

Файл copier.yaml является конфигурационным для инструмента copier, который используется для создания и копирования шаблонов проектов. Этот файл определяет, как будет происходить процесс клонирования шаблона и как будет обрабатываться ввод пользователя при создании нового проекта.

Основные функции файла copier.yaml:

  • Настройки шаблона: Здесь задаются параметры для создания нового проекта, такие как вопросы для пользователя, которые будут заданы во время копирования шаблона.

  • Параметры клонирования: Определяет, какие файлы и папки будут включены в шаблон, а какие — исключены. Это позволяет гибко настраивать шаблоны под разные сценарии.

  • Обработка пользовательских данных: Этот файл может включать в себя переменные, которые заменяются на ответы пользователя при клонировании шаблона (например, имя проекта, версия и другие параметры).

copier.yaml
# copier.yaml

project_name:
  type: str
  help: Введите имя вашего нового проекта
  default: test12

project_summary:
  type: str
  help: Кратко опишите ваш проект
  default: Это проект

author_name:
  type: str
  help: Как вас зовут?
  default: Иван Иванов

author_email:
  type: str
  help: Введите адрес вашей электронной почты
  default: dick@gmail.com

# Настройки copier
_subdirectory: .

_exclude:
    - ".git"
    - "__pycache__"
    - "*.pyc"

_defaults: false  

_vcs_ref: "main"  

# Configure jinja2 defaults to make syntax highlighters lives easier
_templates_suffix: .jinja

📋 copier_conf.answers_file.jinja

Шаблон Jinja используется в copier для настройки и генерации шаблонов проекта. Этот файл содержит динамические параметры и переменные, которые автоматически заменяются на ответы пользователя во время создания нового проекта.

В Jinja-шаблонах обычно определяются шаблонные переменные, такие как название проекта, версия или другие параметры, которые нужно задать при клонировании шаблона. Эти переменные могут быть встроены в любые файлы шаблона, например, в конфигурационные файлы, код или документацию.

Предупреждение

После копирования шаблона в директории вашего проекта появится файл .copier.answers.yml

НИКОГДА не изменяйте файл ответов вручную. Подробнее об этом читайте в официальной документации

⚙️ Настройки pre-commit

🕵️‍♂️ .pre-commit-config.yaml

Конфигурация для инструмента pre-Commit, который управляет хуками для проверки кода перед его коммитом в репозиторий. В этом файле описываются используемые хуки для линтинга и других проверок.

.pre-commit-config.yaml
repos:
# 1. Линтинг через ruff
-   repo: https://github.com/astral-sh/ruff-pre-commit   
    rev: v0.12.2
    hooks:
    -   id: ruff-format
    -   id: ruff-check
        args: [--fix, --exit-non-zero-on-fix]

# 2. Базовые проверки
-   repo: https://github.com/pre-commit/pre-commit-hooks   
    rev: v5.0.0
    hooks:
    -   id: check-added-large-files
    -   id: check-case-conflict
    -   id: check-illegal-windows-names
    -   id: name-tests-test
    -   id: detect-private-key
    -   id: check-docstring-first
    -   id: check-symlinks
    -   id: check-json
    -   id: check-toml
    -   id: check-yaml

# 3. Поиск секретов
-   repo: https://github.com/Yelp/detect-secrets   
    rev: v1.5.0
    hooks:
    -   id: detect-secrets

# 4. Обновление синтаксиса и сортировка импортов
-   repo: https://github.com/asottile/pyupgrade   
    rev: v3.20.0
    hooks:
    -   id: pyupgrade
    
-   repo: https://github.com/PyCQA/isort
    rev: 6.0.1
    hooks:
    -   id: isort

# 5. Проверка покрытия docstrings
-   repo: https://github.com/econchick/interrogate
    rev: 1.7.0 
    hooks:
      - id: interrogate
        args: [--fail-under=50, -vv, -i, -I, -m]

# 6. Статический анализ безопасности
-   repo: https://github.com/PyCQA/bandit   
    rev: 1.7.5
    hooks:
    -   id: bandit

⚙️ Настройки исключений

📋 .gitignore

Файл .gitignore указывает Git, какие файлы и директории игнорировать в процессе контроля версий. Обычно он включает переменные окружения (.env), временные файлы, логи, кэш и другие файлы, которые не должны быть добавлены в репозиторий.

.gitignore
# ---------------------------
# 🧹 Временные файлы Python
# ---------------------------

# Кэшированные файлы Python (__pycache__, *.pyc и т.д.)
__pycache__/
*.py[cod]
*$py.class

# Расширения C (скомпилированные модули)
*.so

# ---------------------------
# 📦 Установка и пакетирование
# ---------------------------

# Виртуальные окружения
env/
venv/
.venv/
ENV/

# Сборки проекта
build/
dist/
develop-eggs/
distribute_scratch/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# Логи установки pip
pip-log.txt
pip-delete-this-directory.txt


# ---------------------------
# 🧪 Тесты и покрытие кода
# ---------------------------

# Результаты тестов и покрытия
htmlcov/
.tox/
.pytest_cache/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover


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

# Генерируемая документация
docs/_build/


# ---------------------------
# 🧑‍💻 IDE и редакторы
# ---------------------------

# VS Code не включаем, т.к необходимо переносить настройки VS Code вместе с проектом
#.vscode/

# JetBrains (PyCharm, IntelliJ и др.)
.idea/


# ---------------------------
# 🖥️ Системные файлы ОС
# ---------------------------

# macOS
.DS_Store

# Windows
Thumbs.db
ehthumbs.db


# ---------------------------
# 🐳 Docker и логи
# ---------------------------

# Логи контейнеров
*.log

# Переопределение для Docker Compose
docker-compose.override.yml


# ---------------------------
# 🔧 Инструменты разработки
# ---------------------------

# Настройки Pyenv
.python-version

# Точки останова Jupyter Notebook
.ipynb_checkpoints/

# mypy (статический анализ типов)
.mypy_cache/

# Pyre (анализатор типов от Facebook)
.pyre/

# Profiling data (например, cProfile)
.prof

# Расписание задач Celery Beat
celerybeat-schedule

# Переменные окружения из .env
.env

# ---------------------------
# 📂 Логи и пользовательские данные
# ---------------------------

# Логи приложений
*.log
logs/

# Базы данных SQLite
*.sqlite3


# ---------------------------
# 📦 Пакеты и кэши
# ---------------------------

# Wheel-файлы Python
*.whl

# pytest cache
.pytest_cache/

# C-расширения
*.so

📋 .dockerignore

Этот файл аналогичен .gitignore, но используется для исключения файлов из контекста сборки Docker. Он помогает уменьшить размер образа и ускорить сборку, исключая ненужные файлы и директории.

.dockerignore
# =============================
# 📁 Файлы, которые не нужно передавать в контекст сборки Docker
# =============================

# 🚫 Системные файлы
.DS_Store
Thumbs.db

# 🧱 Git и разработка
.git
.gitignore
*.log
*.pyc
__pycache__
*.swp
*.swo
*.tmp
*.bak
*.orig
*.rej
*.diff
*.patch

# 📦 Виртуальные окружения и зависимости
venv/
env/
.virtualenv/
.pytest_cache/
.coverage
htmlcov/
.mypy_cache/

# 🛠️ IDE / редакторы
.idea/
.vscode/
*.iml
*.sublime-project
*.sublime-workspace
*.code-workspace

# 📂 Папки с тестами (если не нужны в образе)
tests/
test_*.py
__pycache__/test_*.py

# 📄 Конфигурации и переменные окружения
.env
.env.local
.env.*.local
.env.example

# 📁 Папки node.js (если есть фронтенд)
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.pnpm-store/

# 🗂️ Артефакты сборки
dist/
build/
*.egg-info/
*.so
*.dylib
*.dll

# 📝 Документация
docs/
README.md
CHANGELOG.md
LICENSE

🧱 Исходный код (src/)

Исходный код проекта находится в директории src/. Он разделён на главный файл main.py и вспомогательные утилиты в папке utils.

Примечание

В этой директории будет создаваться логика всего приложения, которое ты хочешь построить

🧱 src/main.py

Файл src/main.py является точкой входа в приложение. Он обычно содержит основную логику приложения, включая запуск процессов или инициализацию важных компонентов. Также в нем часто можно встретить код для вывода информации о начале работы приложения или настройку начальных параметров.

Этот файл играет ключевую роль, так как запускает основные функции проекта. Это может быть как просто запуск консольного приложения, так и настройка веб-сервера или другого сервисного компонента.

Точка входа — главный запуск приложения.

Этот модуль содержит точку входа в приложение и вызывает основную функцию main().

src.main.log_messages()[исходный код]

Функция, которая логирует сообщения разных уровней и выводит текст через print.

Задает 5 уровней логирования

src.main.main()[исходный код]

Основная функция, запускающая бесконечный цикл с логами.

🛠️ src/utils/logger.py

Модуль src/utils/logger.py предоставляет базовую настройку логирования для проекта. Он отвечает за конфигурацию логера, который используется в других частях проекта для записи логов в консоль, файл или другие хранилища.

Логирование — это важная часть приложения, которая помогает отслеживать события и ошибки в процессе работы программы. Этот модуль может быть настроен для записи логов с разными уровнями важности, такими как:

  • DEBUG — для детализированных сообщений, полезных при отладке.

  • INFO — для общих информационных сообщений.

  • WARNING — для предупреждений.

  • ERROR — для сообщений об ошибках.

  • CRITICAL — для критических ошибок.

Модуль для настройки кастомного логгера.

Обеспечивает цветной вывод в консоль и запись логов в файлы.

src.utils.logger.LOGS_DIR

Путь к директории, где будут сохраняться лог-файлы.

Type:

str

src.utils.logger.LOG_FORMAT

Формат строки лога.

Type:

str

src.utils.logger.DATE_FORMAT

Формат даты и времени в логах.

Type:

str

class src.utils.logger.ColoredFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)[исходный код]

Базовые классы: Formatter

Цветной форматтер для вывода логов в консоль.

Класс расширяет стандартный logging.Formatter, добавляя цветовое оформление в зависимости от уровня логирования. Поддерживаются уровни DEBUG, INFO, WARNING, ERROR и CRITICAL.

COLORS

Сопоставление уровней логирования с цветами из библиотеки colorama.

Type:

dict

COLORS = {'CRITICAL': '\x1b[41m\x1b[37m\x1b[1m', 'DEBUG': '\x1b[36m', 'ERROR': '\x1b[31m', 'INFO': '\x1b[32m', 'WARNING': '\x1b[33m'}
format(record)[исходный код]

Форматирует запись лога, применяя цвет в зависимости от уровня.

Цвет устанавливается перед вызовом базового метода format() родительского класса.

Параметры:

record (logging.LogRecord) – Объект записи лога.

Результат:

Отформатированная строка лога с цветовым выделением.

Тип результата:

str

src.utils.logger.get_logger(name=None)[исходный код]

Возвращает настроенный логгер с указанным именем.

Создаёт и настраивает логгер, который выводит сообщения в консоль с цветовой индикацией уровня логирования и записывает информационные и более серьёзные сообщения в файл.

Параметры:

name (str, optional) – Имя логгера. Если не указано, возвращается корневой логгер.

Результат:

Настроенный экземпляр логгера.

Тип результата:

logging.Logger

🛠️ Инструменты (tools/)

Папка tools/ содержит вспомогательные скрипты, которые помогают улучшить разработку и поддерживать порядок в проекте.

🛠️ tools/diagram_auto_update.py

Автоматически обновляет диаграммы PlantUML и генерирует .svg из .puml файлов.

🛠️ tools/print_structure.py

Выводит текущую структуру проекта в терминал. Полезно для проверки состояния проекта перед коммитом.

Примечание

Еще очень удобно уточнять контекст при общении с нейросетями, отправляя им структуру проекта

🧪 Тестирование (tests/)

Тесты находятся в директории tests/.

Предупреждение

В шаблоне пока не реализованы тесты

📚 Документация (docs/)

⚙️ conf.py

Конфигурационный файл для сборщика документации Sphinx.

Этот файл содержит все настройки, необходимые для кастомизации входных и выходных данных Sphinx. Он выполняется как код на Python во время сборки, при этом текущая директория устанавливается как директория конфигурации.

Ошибка

Доделать вывод самого файла

См. также

Подробнее см. в документации Sphinx:

📋 index.rst

Точка сборки документации Sphinx. Собирает все *.md в html страницы

📋 Файлы *.md

Файлы написаны на языке MyST Markdown. Описывают всю документацию

🧰 Makefile и make.bat

Автоматизация локальной сборки документации

Примечание

При локальной сборке документации рекомендуется всегда действовать по следующей схеме:

Пример для Windows

  1. очищаем кэш сборки .\docs\make.bat clean

  2. собираем документацию .\docs\make.bat html

Пример для Linux cd docs make clean make html

📋 Диаграммы

Диаграммы проекта находятся в директории diagrams/. Все диаграммы написаны на языке PlantUML и могут быть обновлены автоматически с помощью утилиты tools/diagram_auto_update.py. Рендер диаграмм происходит автоматически при помощи GitHub Actions

🐳 Docker

Docker — это инструмент для создания, развертывания и управления контейнерами, который позволяет упаковать приложение и все его зависимости в один изолированный контейнер. Этот контейнер можно запускать в любой среде, что позволяет устранить проблемы с совместимостью, возникающие при запуске приложений на разных машинах.

Контейнеры в Docker позволяют гарантировать, что приложение будет работать одинаково на всех устройствах, где установлен Docker, независимо от операционной системы или настроек окружения.

Подробнее можно почитать на хабре

🐳 Dockerfile

Dockerfile — это текстовый файл с инструкциями, который описывает, как должен быть построен Docker-образ. В Dockerfile описываются шаги по установке зависимостей, настройке окружения и запуску приложения.

Dockerfile
# Начинаем сборку с образа Python slim, чтобы сократить размер приложения
FROM python:3.12-slim

# Импортируем нужные переменные (импортируются по пути .env -> docker-compose -> Dockerfile)
ARG DEPLOY_USER_NAME
ARG UID
ARG GID
ARG APP_NAME
ARG APP_PORT

# Устанавливаем локали (без вывода предупреждений)
RUN apt-get update && \
    apt-get install -y locales && \
    echo "en_US.UTF-8 UTF-8" > /etc/locale.gen && \
    locale-gen en_US.UTF-8 && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# Устанавливаем переменные окружения для локалей
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US:en
ENV LC_ALL en_US.UTF-8

# Устанавливаем PYTHONPATH, PATH и PYTHONIOENCODING
ENV PYTHONPATH /${APP_NAME}
ENV PATH /home/${DEPLOY_USER_NAME}/.local/bin:$PATH
ENV PYTHONIOENCODING=utf-8

# Устанавливаем рабочую директорию
WORKDIR /${APP_NAME}

# Создаём пользователя ДО установки зависимостей и даем ему права на чтение и запись
RUN groupadd -g ${GID} ${DEPLOY_USER_NAME} && \
    useradd -m -u ${UID} -g ${DEPLOY_USER_NAME} ${DEPLOY_USER_NAME}

# Копируем requirements
COPY requirements.txt .

# Устанавливаем зависимости от root
RUN pip install --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# Копируем исходный код в контейнер с правами нового юзера
COPY --chown=${DEPLOY_USER_NAME}:${DEPLOY_USER_NAME} . .

# Переключаемся на нового юзера
USER ${DEPLOY_USER_NAME}

# Проверяем состояния контейнера
# HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
#   CMD curl -f http://localhost:${APP_PORT}/health || exit 1

# Запуск приложения
CMD ["python", "-m", "src.main"]

🐳 docker-compose.yaml

Docker Compose — это инструмент для описания и запуска многоконтейнерных приложений. С помощью Compose можно настроить несколько контейнеров, каждый из которых выполняет свою задачу (например, один контейнер для приложения, другой для базы данных) и запускать их как единое приложение. Compose использует файл конфигурации docker-compose.yml, где прописывается вся необходимая информация о сервисах, сетях и томах.

Алгоритм деплоя нового приложения

  1. Зайдите на VPS и разрешите нужный порт в ufw (файрволл)

Примечание

Порт нужно указать в .env в переменной DOCKER_PORT

Подробнее о выборе порта

Лучше выбирать порты из диапазона 49152-65535 (динамические или частные порты), т.к они обычно не заняты важными службами. Разумнее всего проверить выбранный порт при помощи команд

Проверка занятых портов

sudo lsof -i -P -n | grep LISTEN

Проверка с помощью netstat

sudo netstat -tuln

Проверка конкретного порта (например, 8080)

sudo lsof -i :8080

Пример для 443 порта

sudo ufw allow 443/tcp
sudo ufw status
docker-compose.yaml
#docker-compose.yaml

version: '3.9'

services:
  app:
    build:
      context: .             # Dockerfile в текущей директории
      dockerfile: Dockerfile
      args:
        UID: ${UID}
        GID: ${GID}
        DEPLOY_USER_NAME: ${DEPLOY_USER_NAME}
        APP_NAME: ${APP_NAME}
        APP_PORT: ${APP_PORT}

    command: python src/main.py  # можно переопределить стандартный CMD

    volumes:
      - .:/${APP_NAME}               # монтируем исходный код (удобно при разработке)

    env_file:
      - .env                 # переменные окружения (токены, настройки)

    ports:
      - "${DOCKER_PORT}:${APP_PORT}"          # проброс портов (используется DOCKER_PORT из .env)

    restart: unless-stopped  # автоперезапуск контейнера при сбоях

    tty: true                # для корректной работы логов и bash-сессии
    stdin_open: true         # возможность docker attach

    environment:
      - PYTHONIOENCODING=utf-8

    # depends_on:
    #   - db                 # зависимости от других сервисов, если будут

# Пример для базы данных PostgreSQL (если понадобится)
# db:
#   image: postgres:15
#   restart: unless-stopped
#   environment:
#     POSTGRES_USER: youruser
#     POSTGRES_PASSWORD: yourpassword
#     POSTGRES_DB: yourdb
#   volumes:
#     - pgdata:/var/lib/postgresql/data

# volumes:
#   pgdata:

🧰 Makefile

Makefile — это текстовый файл, который используется системой сборки make для автоматизации процессов сборки и управления зависимостями в проекте. Преимущества использования Makefile:

  • Автоматизация: Позволяет автоматизировать повторяющиеся задачи, такие как создание окружений, установка зависимостей и запуск тестов.

  • Упрощение команд: В больших проектах, где нужно выполнять много шагов, Makefile позволяет упрощать команды.

  • Читаемость и удобство: Для новых участников проекта Makefile служит документом, который четко объясняет, как выполнять основные действия.

Makefile
# ================================
# 🛠️ Makefile
# ================================

# Считываем переменные окружения
include .env

# Указывает, какой файл docker-compose используется
COMPOSE_FILE=docker-compose.yaml
DC = docker-compose

# Сервис по умолчанию (например, app)
SERVICE ?= app

# Список всех доступных задач
.PHONY: help up down restart build rebuild logs bash prune docs-clean docs-html

# =============================================
# 📌 ОСНОВНЫЕ КОМАНДЫ
# =============================================

# Посмотреть все существующие контейнеры
ps:
	docker ps -a
# 
# ▶️ Запуск контейнеров в фоне
# Используй после сборки или при старте проекта
up:
	$(DC) up -d

# ⛔ Остановить все контейнеры проекта
# Не удаляет образы и данные
down:
	$(DC) down

# 🔁 Перезапустить контейнеры без пересборки
# Полезно, если изменился код, но не зависимости
restart:
	$(MAKE) down
	$(MAKE) up

# 🔨 Пересобрать образы с нуля + очистка мусора
# Только для изменений в requirements.txt или Dockerfile
build:
	$(DC) build --no-cache
	$(MAKE) prune

# 🔁🔄 Полный цикл: остановка → удаление → запуск
# Используй, если хочешь всё обновить "от и до"
rebuild: prune build up

# 🔍 Просмотр логов в реальном времени
logs:
	$(DC) logs -f

# 🖥️ Вход внутрь контейнера через bash (или sh)
bash:
	$(DC) exec $(SERVICE) /bin/bash || \
	$(DC) exec $(SERVICE) /bin/sh

# 🗑️ Очистка: удаление остановленных контейнеров и старых образов этого проекта
prune:
	$(DC) down --rmi local --volumes --remove-orphans

# Очистка сгенерированной документации
docs-clean:
	cd docs && make clean

# Сборка HTML-документации
docs-html:
	cd docs && make html

# =============================================
# 💡 ПАМЯТКА: Какие команды когда использовать
# =============================================

# 🟢 При первом запуске или после изменений в окружении:
# make up

# 🟡 После изменений в коде (не в зависимостях):
# make restart

# 🔵 После изменений в requirements.txt или Dockerfile:
# make build

# 🔴 Чтобы всё пересобрать "с нуля" и полностью перезапустить:
# make rebuild

# 🟣 Чтобы посмотреть логи:
# make logs

# 🟠 Чтобы залезть внутрь контейнера:
# make bash

# ⚫ Чтобы освободить место на диске:
# make prune

# 🟤 Для справки:
help:
	@echo "📌 Доступные команды:"
	@echo ""
	@echo "  make up            ➜ Запустить контейнеры"
	@echo "  make down          ➜ Остановить контейнеры"
	@echo "  make restart       ➜ Перезапустить (без пересборки)"
	@echo "  make build         ➜ Пересобрать образы с нуля"
	@echo "  make rebuild       ➜ Полный цикл: down → build → up"
	@echo "  make logs          ➜ Посмотреть логи"
	@echo "  make bash          ➜ Войти в контейнер"
	@echo "  make prune         ➜ Почистить старые данные"
	@echo "  make help          ➜ Эта справка"

🔄 CI/CD (GitHub Actions)

Что такое CI/CD

CI/CD (Continuous Integration / Continuous Delivery) — это процесс автоматизации разработки и развертывания приложений, который помогает ускорить внедрение изменений в проект. GitHub Actions предоставляет инструменты для автоматизации процессов, таких как тестирование, сборка, деплой и другие шаги, связанные с жизненным циклом проекта.

Преимущества CI/CD с GitHub Actions:

  • Автоматизация деплоя: Каждый раз, когда в репозиторий вносятся изменения, документация обновляется автоматически.

  • Отсутствие необходимости вручную деплоить изменения: Процесс деплоя происходит без вмешательства пользователя.

  • Публичная доступность документации: Документация всегда доступна по постоянному URL через GitHub Pages.

  • Масштабируемость: Можно добавить дополнительные шаги в workflow, например, для тестирования или сборки приложения.

Workflows

В вашем проекте используется GitHub Actions для автоматизации деплоя документации на GitHub Pages.

deploy_docs.yml
name: Build and Deploy Documentation

on:
  push:
    branches:
      - main
      - '**'  # Поддержка всех веток

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write

    steps:
      - name: 📁 Клонируем репозиторий
        uses: actions/checkout@v3

      - name: ☕ Устанавливаем Java и Graphviz (нужна для PlantUML)
        run: |
          sudo apt-get update
          sudo apt-get install -y default-jre graphviz

      - name: 🌿 Скачиваем последнюю версию PlantUML, проверяем работу Graphviz и Dot
        run: |
          # Создаем папку для PlantUML в /usr/local/bin, скачиваем PlantUML
          sudo mkdir -p /usr/local/bin/plantuml
          sudo wget -q https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar -O /usr/local/bin/plantuml/plantuml.jar
          # Проверяем версию PlantUML, Graphviz, Dot
          java -jar /usr/local/bin/plantuml/plantuml.jar -version
          dot -V
          java -jar /usr/local/bin/plantuml/plantuml.jar -testdot

      - name: 🐍 Настраиваем Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: 🔧 Устанавливаем зависимости
        run: |
          pip install --upgrade pip
          pip install -r requirements.txt
          pip install sphinxcontrib-plantuml sphinx-rtd-theme

      - name: 📄 Проверяем конфигурацию Sphinx
        run: |
          echo "Текущая конфигурация conf.py:"
          cat docs/conf.py

      - name: 📊 Собираем документацию
        env:
          PLANTUML_JAR_PATH: /usr/local/bin/plantuml/plantuml.jar
        run: |
          cd docs
          
          # Очищаем старый билд
          make clean

          # Передаём путь к plantuml через переменную окружения, а не правим conf.py
          make html SPHINXOPTS="-D plantuml=java\ -jar\ $PLANTUML_JAR_PATH"

          # Добавляем .nojekyll чтобы GitHub Pages не обрабатывал файлы как Jekyll-сайт
          touch _build/html/.nojekyll

      - name: 🖼️ Проверяем, собран ли HTML
        run: |
          ls -la docs/_build/html/

      - name: 🚀 Деплоим документацию на GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html