⚙️ Getting started: Установка и настройка шаблона

Установка и настройка Python

💻 Установка Visual Studio Code

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

Порядок установки:

  1. Перейдите на официальный сайт Visual Studio Code.

  2. Выберите нужную версию для своей операционной системы (Windows, macOS, Linux).

  3. Скачайте и следуйте инструкциям на экране для завершения установки.

Настройки терминала Windows для работы с VS Code

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

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

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

В командной строке PowerShell существует несколько типов политик выполнения (Execution Policies), и в нашем случае используется политика RemoteSigned, которая разрешает запуск локальных скриптов, но требует, чтобы скрипты, загруженные из интернета, были подписаны доверенным издателем.

Шаги настройки

  1. Открыть Windows PowerShell от имени администратора Для выполнения изменений в системных настройках необходимо иметь права администратора. Для этого:

    • Найдите «PowerShell» в поиске Windows.

    • Щелкните правой кнопкой мыши на «Windows PowerShell» и выберите Запуск от имени администратора.

  2. Ввести команду После того как PowerShell откроется с правами администратора, введите команду:

    Set-ExecutionPolicy RemoteSigned -Force

Подробнее о команде

  • Set-ExecutionPolicy — это команда, которая позволяет изменить текущую политику выполнения скриптов.

  • RemoteSigned — настройка, которая разрешает запуск локальных скриптов и скриптов, подписанных с удалённых источников.

  • -Force — флаг, который автоматически подтверждает выполнение команды, не запрашивая разрешение у пользователя.

После выполнения этой команды PowerShell будет разрешать запускать локальные скрипты и работать с виртуальными окружениями, что значительно улучшит ваш опыт работы с VS Code. Вы сможете без проблем активировать и деактивировать виртуальные окружения, а также запускать различные командлеты и автоматизировать процессы разработки.

Notepad++

Notepad++ — это бесплатный и мощный текстовый редактор для Windows, который поддерживает работу с множеством языков программирования. Он обладает удобным интерфейсом, функциями подсветки синтаксиса, авто-дополнением, расширяемостью через плагины и возможностью работы с большими файлами, что делает написание и редактирование коммитов более удобным.

Установка

  1. Перейдите на официальный сайт Notepad++.

  2. Скачайте последнюю версию для Windows (обычно это будет версия для 32 или 64-битной системы).

  3. Запустите установочный файл и следуй инструкциям установщика.

🔄 Git и Github

Git — это распределённая система управления версиями, которая позволяет отслеживать изменения в коде и работать над проектами с несколькими людьми одновременно.

GitHub — это онлайн-платформа для хостинга и совместной работы с репозиториями Git, позволяющая легко обмениваться кодом и контролировать версии.

Git позволяет управлять версионностью кода, а GitHub обеспечивает совместную работу над проектами, делая код доступным для всех участников.

Примечание

Подробная инструкция по установке и настройке Git

Лучший видеокурс по работе с Git для новичков

Бесплатный курс по работе с Git и GitHub на Stepik

Минимальная установка Git на Windows

  1. Скачайте Git с официального сайта

Совет

Можно оставить настройки по умолчанию

  1. Добавьте путь к Git в переменную среды Path (Python настраивался аналогично) Когда Git будет установлен, нужно добавить его путь в переменную среды Path, чтобы команды Git были доступны в любом месте командной строки. Это позволяет вам запускать Git, не указывая полный путь до его исполнимых файлов.

Примечание

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

  • Откройте меню «Пуск», найдите Система и откройте Свойства системы.

  • Перейдите во вкладку Дополнительные параметры системы.

  • Нажмите Переменные среды….

  • В разделе Системные переменные найдите переменную Path и выберите Изменить.

  • Добавьте новый путь к папке с установленным Git, обычно это C:\Program Files\Git\bin (или аналогичный путь в зависимости от места установки).

  • Нажмите Ок, чтобы сохранить изменения.

  1. Откройте командную строку Windows и обновите глобальные настройки Git - установите имя, электронную почту, выберите Notepad++ в качестве редактора по умолчанию

git global config user.name "Ваше имя"

git global config user.email "Ваша почта"

git config --global core.editor "notepad++ -multiInst -nosession"

Примечание

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

Совет

Используйте памятку по коммитам для грамотной работы с Git.

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

Автоматизировать через copier

  1. Используй шаблон для коммитов

git config --global commit.template .\projectTemplate\docs\commit_template.txt

Теперь при команде git commit

  • Git откроет Notepad++ с шаблоном из commit_template.txt.

  • Вы заполняете описание коммита в этом шаблоне.

  • После сохранения и закрытия Notepad++ изменения коммита будут сохранены.

Примечание

Шаблон коммита помогает всегда следовать одинаковому стилю. Вы можете легко настроить шаблон коммита под собственные нужды и стандарты, для этого необходимо отредактировать файл \projectTemplate\docs\commit_template.txt

📐 Copier

copier — это инструмент для автоматического копирования шаблонов и генерации файлов, который используется для создания новых проектов на основе заранее подготовленных шаблонов. Он позволяет быстро клонировать структуру проекта, что особенно полезно для стандартизации и автоматизации процесса создания новых приложений или компонентов. Также copier позволяет быстро обновлять проекты при изменении шаблона, на основе которого они были выполнены.

Установить его можно через pip:

pip install copier

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

Убедитесь, что у вас установлен Python 3.9 или выше. Проверить версию можно командой:

python --version

Копирование шаблона проекта

Теперь, когда copier установлен, мы можем скопировать шаблон в нужную директорию. Для этого выполните следующую команду:

copier copy https://github.com/yourname/projectTemplate.git ./your_project_name

Замените your_project_name на имя новой папки, в которую будет скопирован проект.

Примечание

Copier предложит ответить на несколько вопросов — вы можете принять значения по умолчанию или изменить их под свои нужды.

Обновление шаблона проекта с помощью copier

Если шаблон проекта был обновлён, и вы хотите применить изменения к своему текущему проекту, можно использовать команду copier update. Это позволяет синхронизировать проект с изменениями в шаблоне.

Для этого перейдите в директорию проекта и выполните команду:

copier update

Примечание

При выполнении этой команды copier будет проверять изменения в шаблоне и предложит обновить файлы, если они были изменены. Вы можете выбрать, какие изменения принять, а какие отклонить.

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

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

⚙️ Виртуальное окружение

Создание виртуального окружения

После копирования шаблона перейдите в директорию проекта и создайте виртуальное окружение:

cd your_project_name
python -m venv venv

Затем активируйте виртуальное окружение:

Для Windows:

.\venv\Scripts\activate

Для macOS/Linux:

source venv/bin/activate

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

Не забудьте активировать виртуальное окружение перед установкой зависимостей!

Подробнее о том, что такое виртуальное окружение и зачем его настраивать

Установка зависимостей

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

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

Как обновить requirements.txt?

  1. Если вы установили новую библиотеку с помощью pip, например:

pip install some_library

  1. Чтобы обновить файл requirements.txt, используйте команду:

pip freeze > requirements.txt

Эта команда автоматически сохранит все текущие установленные пакеты и их версии в файл requirements.txt. Это особенно важно, чтобы сохранить совместимость всех зависимостей проекта.

Такой подход позволяет обеспечить

  • Совместимость: Когда кто-то клонирует ваш проект и установит все зависимости с помощью pip install -r requirements.txt, он получит те же версии библиотек. Это гарантирует, что проект будет работать одинаково в разных средах.

  • Удобство: Для разработчиков, которые работают с твоим проектом, наличие актуального requirements.txt позволяет легко установить все нужные библиотеки одной командой. Это сокращает время на настройку окружения.

Пример:

Допустим, вы добавили библиотеку requests в проект. После этого команда pip freeze обновит requirements.txt и будет выглядеть, например, так:

requests==2.28.1
numpy==1.23.0
flask==2.1.0

Теперь, когда кто-то загрузит проект и выполнит команду

pip install -r requirements.txt

Все эти библиотеки будут установлены в нужных версиях.

Примечание

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

🕵️‍♂️ Подключение pre-commit

Что такое pre-commit?

pre-commit — это инструмент для автоматической проверки кода перед коммитами в Git. Он позволяет настроить ряд хуков, которые будут запускаться каждый раз перед тем, как код попадет в репозиторий.

pre-commit помогает поддерживать чистоту кодовой базы. При помощи этого инструмента можно проводить различные проверки кода:

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

  • Форматирование: автоматическое приведение кода к единому стилю (отступы, пробелы, порядок импортов)

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

Для активации выполните команду в виртуальном окружении

pre-commit install

Эта команда устанавливает нужные скрипты в директорию .git/hooks

Примечание

Настройки для pre-commit находятся в корне проекта в .pre-commit-config.yaml

Запуск pre-commit

После того как вы выполните команду pre-commit install, хуки будут автоматически запускаться каждый раз при выполнении команды git commit.

Примечание

Автоматический запуск хуков помогает поддерживать код в хорошем состоянии, предотвращая попадание невалидного кода в репозиторий.

  1. Для одного файла

Чтобы запустить хуки только для одного конкретного файла, используйте команду:

pre-commit run --files path/to/file

Замените path/to/file на путь к нужному файлу. Это полезно, когда вы хотите проверить только изменения в одном файле, не выполняя проверку для всего проекта.

Примечание

В VS Code можно скопировать путь файла - кликаем правой кнопкой мышки на файл, выбираем Copy Path/Copy Relative Path

  1. Запуск для всех файлов

Чтобы запустить все хуки для всех файлов, выполните следующую команду:

pre-commit run --all-files

Эта команда проверит все файлы в проекте, которые находятся под контролем Git, используя все настроенные хуки.

  1. Отключение pre-commit для конкретного коммита

Если по какой-то причине вам нужно выполнить коммит, не запуская хуки, вы можете использовать флаг --no-verify:

git commit --no-verify

Это временно отключит запуск хуков перед коммитом, но следует использовать эту опцию с осторожностью, чтобы не пропустить важные проверки.

Хуки

В данном шаблоне используются следующие хуки

Примечание

Настройки для pre-commit находятся в корне проекта в .pre-commit-config.yaml. Их можно менять при необходимости

Группа хуков

Хук

Описание

Линтинг и форматирование

ruff-format

Форматирует код с использованием ruff, чтобы привести его к стандарту PEP8.

ruff-check

Проверяет код с использованием ruff. Параметр --fix автоматически исправляет ошибки, а --exit-non-zero-on-fix возвращает ошибку, если что-то исправлено.

isort

Сортирует импорты в коде, упорядочивая их по стандартам (например, алфавитный порядок).

Базовые проверки

check-added-large-files

Проверяет, не были ли случайно добавлены слишком большие файлы в репозиторий.

check-case-conflict

Проверяет наличие конфликтов имен с различием в регистре (например, file.py и File.py).

check-illegal-windows-names

Проверяет, что имена файлов не содержат запрещенные символы для Windows.

check-docstring-first

Проверяет, что строки документации расположены сразу после определения функции или класса.

check-symlinks

Проверяет наличие символических ссылок в проекте.

check-json

Проверяет синтаксис JSON-файлов на корректность.

check-toml

Проверяет синтаксис TOML-файлов на корректность.

check-yaml

Проверяет синтаксис YAML-файлов на корректность.

Поиск секретов

detect-secrets

Ищет секреты в коде (например, пароли или ключи API), чтобы предотвратить случайное добавление чувствительных данных в репозиторий.

Обновление синтаксиса Python

pyupgrade

Обновляет синтаксис Python до более новой версии, например, обновляет старые конструкции (например, u'' на '' для строк).

Проверка покрытия docstrings

interrogate

Проверяет, что все функции и классы имеют соответствующие строки документации, и требует минимальный процент покрытия docstrings (например, 80%).

Статический анализ безопасности

bandit

Выполняет статический анализ безопасности кода и выявляет уязвимости, такие как небезопасные функции или конструкции в коде.

📚 Работа с документацией

Шаблон уже настроен для генерации документации с помощью Sphinx. Чтобы сгенерировать HTML-документацию, в папке проекта выполните команду:

Для Linux

cd docs
make html

Для Windows

.\docs\make.bat html

HTML-версия документации будет доступна в папке _build/html.

Примечание

Для локального просмотра документации откройте файл _build/html/index.html в браузере.

CI/CD

Для автоматического деплоя приложения на свой личный сервер следует выполнить следующие шаги:

Настройка на стороне VPS

  1. На вашем VPS создайте пользователя, который будет использоваться только для деплоя. Рассмотрим на примере юзера deployer:

sudo adduser --home /home/deployer --shell /bin/bash --disabled-password --gecos "" deployer

:class: dropdown
Команда создаёт нового пользователя с заданным именем, домашней директорией и оболочкой, но без возможности войти в систему с паролем.

  1. Настроим права доступа нового юзера

  • Редактируем sudoers при помощи команды

sudo visudo

Добавляем внизу такую строку

deployer  ALL=(ALL) NOPASSWD: /usr/bin/git, /usr/bin/docker

  • Редактируем sshd_config через sudo

sudo nano /etc/ssh/sshd_config

Должно быть так

PermitRootogin no
PubkeyAuthentication yes
PasswordAuthentication no
PermitEmptyPasswords no

Примечание

PermitRootogin запрещает пользователю root входить от имени этого пользователя PubkeyAuthentication разрешает вход по SSH ключу PasswordAuthentication запрещает вход по паролю PermitEmptyPasswords запрещает использование пустых паролей

  • Добавляем юзера deployer в группу docker, а нашего основного юзера в группу deployer (вместо админ вставьте имя вашего основного юзера)

usermod -aG docker deployer
usermod -aG deployer admin

  1. Переключаемся на нового юзера

sudo su - deployer

  1. Настройка SSH для юзера deployer

  • Создаем в домашней директории home/deployer папку .ssh

sudo mkdir /home/deployer/.ssh

  • Создаем файл /home/deployer/.ssh/autorized_keys

touch home/deployer/.ssh/autorized_keys

  • Генерируем на локальном компьютере SSH ключи по алгоритму Ed25519 В результате получаем 2 ключа с именами deployer

ssh-keygen -t ed25519 -a 200 -C "github actions"

  • Копируем ПУБЛИЧНЫЙ ключ SSH в /home/deployer/.ssh/autorized_keys

  1. Настройки прав доступа (необходимо для подключения по ssh) Настраиваем следующие права для юзера deployer, его директорий и файлов

sudo chmod go-w /home/deployer

sudo chmod 700 /home/deployer/.ssh

sudo chown -R deployer:deployer /home/deployer/.ssh

sudo chmod 600 /home/deployer/.ssh/authorized_keys

  1. Настраиваем и открываем порты для работы приложения. Например, порт 55555

sudo ufw alow 55555/tcp
sudo ufw reload
sudo ufw status

  1. Переключаемся на нового юзера deployer и клонируем приложение с гитхаб

git clone

  1. Переходим в папку проекта и создаем в ней файл .env

cd projectTemplate
nano .env

  1. Заполняем .env по образцу .env.example - копируем все из .env.example, заменяем на свои значения

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

ВАЖНО указать UID и GID юзера deployer во избежание проблем с правами доступа

  1. Переключаемся обратно на админа и меняем права доступа для проекта

sudo chown -R deployer:deployer projectTemplate/

Примечание

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

Настройка на стороне GitHub

  1. Создаем необходимые переменные для Github Secrets

  • SSH_PRIVATE_KEY - приватный SSH ключ

  • SSH_HOST - IP адрес сервера (можно узнать через команду ifconfig)

  • SSH_PORT - порт SSH (можно найти в /etc/ssh/sshd_config)

  • SSH_USER - имя юзера (в нашем случае deployer)

  • DEPLOY_PATH - директория на сервере, где будет развернуто приложение (/home/deployer/)

  • TELEGRAM_BOT_TOKEN - API ключ телеграм бота, которому будут приходить уведомления об успешном деплое

  • TELEGRAM_CHAT_ID

TELEGRAM_BOT_TOKEN можно взять у официального бота телеграм @BotFather

TELEGRAM_CHAT_ID можно узнать следующим образом
1. Делаем запрос в браузере по адресу (замените TELEGRAM_BOT_TOKEN на ключ, полученный у Bot Fater)
```url
https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/getUpdates
```
2. Отправляем любое сообщение своему боту

3. Обновляем страницу в браузере

4. Получаем chat_id

  1. Делаем push на гитхаб, получаем уведомление в телеграм

✅ Резюме

Теперь твой проект полностью настроен и готов к разработке. Ты можешь:

  • Писать код в VS Code с поддержкой Python и автодополнением

  • Использовать виртуальное окружение для изоляции зависимостей

  • Работать с Git и делать коммиты

  • Генерировать и читать документацию