## ⚙️ Getting started: Установка и настройка шаблона ### Установка и настройка Python ### 💻 Установка Visual Studio Code Visual Studio Code — это бесплатный, мощный редактор исходного кода с поддержкой множества языков программирования и расширений. Он нужен для написания и редактирования кода, работы с версиями и интеграции с различными инструментами разработки. Порядок установки: 1. Перейдите на официальный сайт [Visual Studio Code](https://code.visualstudio.com/). 2. Выберите нужную версию для своей операционной системы (Windows, macOS, Linux). 3. Скачайте и следуйте инструкциям на экране для завершения установки. #### Настройки терминала Windows для работы с VS Code Для того чтобы работа с VS Code, особенно с терминалом и виртуальными окружениями, была максимально удобной и безошибочной, необходимо выполнить несколько настроек в PowerShell. Эти настройки позволят запускать скрипты и управлять виртуальными окружениями без дополнительных проблем. ```{warning} Когда вы пытаетесь запустить виртуальное окружение или выполнить скрипты в PowerShell, система может заблокировать выполнение этих операций из-за политики безопасности. Это связано с тем, что по умолчанию Windows запрещает запускать неподписанные скрипты, чтобы предотвратить возможные угрозы безопасности. В командной строке PowerShell существует несколько типов политик выполнения (Execution Policies), и в нашем случае используется политика **RemoteSigned**, которая разрешает запуск локальных скриптов, но требует, чтобы скрипты, загруженные из интернета, были подписаны доверенным издателем. ``` ##### Шаги настройки 1. **Открыть Windows PowerShell от имени администратора** Для выполнения изменений в системных настройках необходимо иметь права администратора. Для этого: - Найдите "PowerShell" в поиске Windows. - Щелкните правой кнопкой мыши на "Windows PowerShell" и выберите **Запуск от имени администратора**. 2. **Ввести команду** После того как PowerShell откроется с правами администратора, введите команду: ```bash Set-ExecutionPolicy RemoteSigned -Force ``` ```{admonition} Подробнее о команде :class: note :class: dropdown - **Set-ExecutionPolicy** — это команда, которая позволяет изменить текущую политику выполнения скриптов. * **RemoteSigned** — настройка, которая разрешает запуск локальных скриптов и скриптов, подписанных с удалённых источников. - **-Force** — флаг, который автоматически подтверждает выполнение команды, не запрашивая разрешение у пользователя. ``` После выполнения этой команды PowerShell будет разрешать запускать локальные скрипты и работать с виртуальными окружениями, что значительно улучшит ваш опыт работы с VS Code. Вы сможете без проблем активировать и деактивировать виртуальные окружения, а также запускать различные командлеты и автоматизировать процессы разработки. --- ### Notepad++ Notepad++ — это бесплатный и мощный текстовый редактор для Windows, который поддерживает работу с множеством языков программирования. Он обладает удобным интерфейсом, функциями подсветки синтаксиса, авто-дополнением, расширяемостью через плагины и возможностью работы с большими файлами, что делает написание и редактирование коммитов более удобным. #### Установка 1. Перейдите на [официальный сайт Notepad++](https://notepad-plus-plus.org/). 2. Скачайте последнюю версию для Windows (обычно это будет версия для 32 или 64-битной системы). 3. Запустите установочный файл и следуй инструкциям установщика. --- ### 🔄 Git и Github Git — это распределённая система управления версиями, которая позволяет отслеживать изменения в коде и работать над проектами с несколькими людьми одновременно. GitHub — это онлайн-платформа для хостинга и совместной работы с репозиториями Git, позволяющая легко обмениваться кодом и контролировать версии. Git позволяет управлять версионностью кода, а GitHub обеспечивает совместную работу над проектами, делая код доступным для всех участников. ```{note} [Подробная инструкция по установке и настройке Git](https://habr.com/ru/articles/541258/) [Лучший видеокурс по работе с Git для новичков](https://www.youtube.com/playlist?list=PLDyvV36pndZFHXjXuwA_NywNrVQO0aQqb) [Бесплатный курс по работе с Git и GitHub на Stepik](https://stepik.org/course/125248) ``` #### Минимальная установка Git на Windows 1. Скачайте Git с [официального сайта](https://git-scm.com/) ```{tip} :class: dropdown Можно оставить настройки по умолчанию ``` 2. Добавьте путь к Git в переменную среды Path (Python настраивался аналогично) Когда Git будет установлен, нужно добавить его путь в переменную среды Path, чтобы команды Git были доступны в любом месте командной строки. Это позволяет вам запускать Git, не указывая полный путь до его исполнимых файлов. ```{note} :class: dropdown В процессе установки Git, обычно, эта настройка уже выполняется автоматически. Однако, если по какой-то причине этого не произошло, вы можете сделать это вручную: - Откройте меню "Пуск", найдите Система и откройте Свойства системы. - Перейдите во вкладку Дополнительные параметры системы. - Нажмите Переменные среды.... - В разделе Системные переменные найдите переменную Path и выберите Изменить. - Добавьте новый путь к папке с установленным Git, обычно это C:\Program Files\Git\bin (или аналогичный путь в зависимости от места установки). - Нажмите Ок, чтобы сохранить изменения. ``` 3. Откройте командную строку Windows и обновите глобальные настройки Git - установите имя, электронную почту, выберите Notepad++ в качестве редактора по умолчанию ```bash git global config user.name "Ваше имя" ``` ```bash git global config user.email "Ваша почта" ``` ```bash git config --global core.editor "notepad++ -multiInst -nosession" ``` ```{note} :class: dropdown Можно выдумать любые имя и почту, но лучше сразу указать как минимум реальную почту. Это поможет вам и другим разработчикам легко видеть, кто внес изменения в код. ``` ```{admonition} Совет :class: tip Используйте [памятку по коммитам](./recommendations.md#руководство-по-написанию-коммитов) для грамотной работы с Git. ``` --- ```{warning} Автоматизировать через copier ``` 3. Используй шаблон для коммитов ```bash git config --global commit.template .\projectTemplate\docs\commit_template.txt ``` Теперь при команде git commit - Git откроет Notepad++ с шаблоном из commit_template.txt. - Вы заполняете описание коммита в этом шаблоне. - После сохранения и закрытия Notepad++ изменения коммита будут сохранены. ```{note} Шаблон коммита помогает всегда следовать одинаковому стилю. Вы можете легко настроить шаблон коммита под собственные нужды и стандарты, для этого необходимо отредактировать файл \projectTemplate\docs\commit_template.txt ``` ### 📐 Copier [`copier`](https://copier.readthedocs.io/) — это инструмент для автоматического копирования шаблонов и генерации файлов, который используется для создания новых проектов на основе заранее подготовленных шаблонов. Он позволяет быстро клонировать структуру проекта, что особенно полезно для стандартизации и автоматизации процесса создания новых приложений или компонентов. Также `copier` позволяет быстро обновлять проекты при изменении шаблона, на основе которого они были выполнены. Установить его можно через `pip`: ```bash pip install copier ``` ```{warning} Убедитесь, что у вас установлен Python 3.9 или выше. Проверить версию можно командой: ``` ```bash python --version ``` #### Копирование шаблона проекта Теперь, когда `copier` установлен, мы можем скопировать шаблон в нужную директорию. Для этого выполните следующую команду: ```bash copier copy https://github.com/yourname/projectTemplate.git ./your_project_name ``` Замените `your_project_name` на имя новой папки, в которую будет скопирован проект. ```{note} Copier предложит ответить на несколько вопросов — вы можете принять значения по умолчанию или изменить их под свои нужды. ``` #### Обновление шаблона проекта с помощью copier Если шаблон проекта был обновлён, и вы хотите применить изменения к своему текущему проекту, можно использовать команду copier update. Это позволяет синхронизировать проект с изменениями в шаблоне. Для этого перейдите в директорию проекта и выполните команду: ```bash copier update ``` ```{note} При выполнении этой команды `copier` будет проверять изменения в шаблоне и предложит обновить файлы, если они были изменены. Вы можете выбрать, какие изменения принять, а какие отклонить. ``` ```{warning} Перед обновлением рекомендуется создать резервную копию проекта, чтобы избежать потери данных. ``` --- ### ⚙️ Виртуальное окружение #### Создание виртуального окружения После копирования шаблона перейдите в директорию проекта и создайте виртуальное окружение: ```bash cd your_project_name python -m venv venv ``` Затем активируйте виртуальное окружение: Для Windows: ```bash .\venv\Scripts\activate ``` Для macOS/Linux: ```bash source venv/bin/activate ``` ```{warning} Не забудьте активировать виртуальное окружение перед установкой зависимостей! Подробнее о том, [что такое виртуальное окружение и зачем его настраивать](https://skillbox.ru/media/code/python-venv-chto-takoe-virtualnoe-okruzhenie-i-kak-im-polzovatsya/) ``` #### Установка зависимостей **`requirements.txt`** — это файл, который хранит список всех зависимостей проекта, которые нужно установить для его работы. Он используется для упрощения процесса установки пакетов, необходимых для проекта. Когда вы добавляете новые библиотеки в проект или обновляете их версии, важно обновить этот файл, чтобы другие разработчики или среды, в которых будет запускаться проект, могли легко установить нужные пакеты. ##### Как обновить `requirements.txt`? 1. Если вы установили новую библиотеку с помощью pip, например: ```bash pip install some_library ``` 2. Чтобы обновить файл `requirements.txt`, используйте команду: ```bash pip freeze > requirements.txt ``` Эта команда автоматически сохранит все текущие установленные пакеты и их версии в файл `requirements.txt`. Это особенно важно, чтобы сохранить совместимость всех зависимостей проекта. Такой подход позволяет обеспечить * **Совместимость:** Когда кто-то клонирует ваш проект и установит все зависимости с помощью `pip install -r requirements.txt`, он получит те же версии библиотек. Это гарантирует, что проект будет работать одинаково в разных средах. * **Удобство:** Для разработчиков, которые работают с твоим проектом, наличие актуального `requirements.txt` позволяет легко установить все нужные библиотеки одной командой. Это сокращает время на настройку окружения. ##### Пример: Допустим, вы добавили библиотеку `requests` в проект. После этого команда `pip freeze` обновит `requirements.txt` и будет выглядеть, например, так: ```text requests==2.28.1 numpy==1.23.0 flask==2.1.0 ``` Теперь, когда кто-то загрузит проект и выполнит команду ```bash pip install -r requirements.txt ``` Все эти библиотеки будут установлены в нужных версиях. ```{note} Подробнее об управлении зависимостями можно почитать [на хабре](https://habr.com/ru/articles/889670/) ``` ### 🕵️‍♂️ Подключение pre-commit #### Что такое pre-commit? [pre-commit](https://github.com/pre-commit/pre-commit) — это инструмент для автоматической проверки кода перед коммитами в Git. Он позволяет настроить ряд [хуков](https://git-scm.com/book/ru/v2/%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0-Git-%D0%A5%D1%83%D0%BA%D0%B8-%D0%B2-Git), которые будут запускаться каждый раз перед тем, как код попадет в репозиторий. `pre-commit` помогает поддерживать чистоту кодовой базы. При помощи этого инструмента можно проводить различные проверки кода: - Линтинг: анализ кода на ошибки, несоответствия стилю и потенциальные проблемы. Линтеры помогают выявлять синтаксические ошибки и улучшать читаемость кода. - Форматирование: автоматическое приведение кода к единому стилю (отступы, пробелы, порядок импортов) - Проверки безопасности: предотвращение утечек чувствительных данных (паролей, ключей) выявление потенциальных уязвимостей. Для активации выполните команду в виртуальном окружении ```bash pre-commit install ``` Эта команда устанавливает нужные скрипты в директорию .git/hooks ```{note} Настройки для pre-commit находятся в корне проекта в ``.pre-commit-config.yaml`` ``` #### Запуск pre-commit После того как вы выполните команду ``pre-commit install``, хуки будут автоматически запускаться каждый раз при выполнении команды ``git commit``. ```{note} Автоматический запуск хуков помогает поддерживать код в хорошем состоянии, предотвращая попадание невалидного кода в репозиторий. ``` 1. Для одного файла Чтобы запустить хуки только для одного конкретного файла, используйте команду: ```bash pre-commit run --files path/to/file ``` Замените `path/to/file` на путь к нужному файлу. Это полезно, когда вы хотите проверить только изменения в одном файле, не выполняя проверку для всего проекта. ```{note} В VS Code можно скопировать путь файла - кликаем правой кнопкой мышки на файл, выбираем Copy Path/Copy Relative Path ``` 2. Запуск для всех файлов Чтобы запустить все хуки для всех файлов, выполните следующую команду: ```bash pre-commit run --all-files ``` Эта команда проверит все файлы в проекте, которые находятся под контролем Git, используя все настроенные хуки. 3. Отключение pre-commit для конкретного коммита Если по какой-то причине вам нужно выполнить коммит, не запуская хуки, вы можете использовать флаг `--no-verify`: ```bash git commit --no-verify ``` Это временно отключит запуск хуков перед коммитом, но следует использовать эту опцию с осторожностью, чтобы не пропустить важные проверки. #### Хуки В данном шаблоне используются следующие хуки ```{note} Настройки для pre-commit находятся в корне проекта в ``.pre-commit-config.yaml``. Их можно менять при необходимости ``` | **Группа хуков** | **Хук** | **Описание** | | ----------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Линтинг и форматирование** | [ruff-format](https://github.com/astral-sh/ruff-pre-commit) | Форматирует код с использованием `ruff`, чтобы привести его к стандарту PEP8. | | | [ruff-check](https://github.com/astral-sh/ruff-pre-commit) | Проверяет код с использованием `ruff`. Параметр `--fix` автоматически исправляет ошибки, а `--exit-non-zero-on-fix` возвращает ошибку, если что-то исправлено. | | | [isort](https://github.com/PyCQA/isort) | Сортирует импорты в коде, упорядочивая их по стандартам (например, алфавитный порядок). | | **Базовые проверки** | [check-added-large-files](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет, не были ли случайно добавлены слишком большие файлы в репозиторий. | | | [check-case-conflict](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет наличие конфликтов имен с различием в регистре (например, `file.py` и `File.py`). | | | [check-illegal-windows-names](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет, что имена файлов не содержат запрещенные символы для Windows. | | | [check-docstring-first](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет, что строки документации расположены сразу после определения функции или класса. | | | [check-symlinks](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет наличие символических ссылок в проекте. | | | [check-json](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет синтаксис JSON-файлов на корректность. | | | [check-toml](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет синтаксис TOML-файлов на корректность. | | | [check-yaml](https://github.com/pre-commit/mirrors-pre-commit-hooks) | Проверяет синтаксис YAML-файлов на корректность. | | **Поиск секретов** | [detect-secrets](https://github.com/Yelp/detect-secrets) | Ищет секреты в коде (например, пароли или ключи API), чтобы предотвратить случайное добавление чувствительных данных в репозиторий. | | **Обновление синтаксиса Python** | [pyupgrade](https://github.com/asottile/pyupgrade) | Обновляет синтаксис Python до более новой версии, например, обновляет старые конструкции (например, `u''` на `''` для строк). | | **Проверка покрытия docstrings** | [interrogate](https://github.com/econchick/interrogate) | Проверяет, что все функции и классы имеют соответствующие строки документации, и требует минимальный процент покрытия docstrings (например, 80%). | | **Статический анализ безопасности** | [bandit](https://github.com/PyCQA/bandit) | Выполняет статический анализ безопасности кода и выявляет уязвимости, такие как небезопасные функции или конструкции в коде. | --- ### 📚 Работа с документацией Шаблон уже настроен для генерации документации с помощью [Sphinx](https://www.sphinx-doc.org/). Чтобы сгенерировать HTML-документацию, в папке проекта выполните команду: #### Для Linux ```bash cd docs make html ``` #### Для Windows ```bash .\docs\make.bat html ``` HTML-версия документации будет доступна в папке `_build/html`. ```{note} Для локального просмотра документации откройте файл `_build/html/index.html` в браузере. ``` --- ### CI/CD Для автоматического деплоя приложения на свой личный сервер следует выполнить следующие шаги: #### Настройка на стороне VPS 1. На вашем VPS создайте пользователя, который будет использоваться только для деплоя. Рассмотрим на примере юзера deployer: ```bash sudo adduser --home /home/deployer --shell /bin/bash --disabled-password --gecos "" deployer ``` ```note :class: dropdown Команда создаёт нового пользователя с заданным именем, домашней директорией и оболочкой, но без возможности войти в систему с паролем. ``` 2. Настроим права доступа нового юзера - Редактируем sudoers при помощи команды ```bash sudo visudo ``` Добавляем внизу такую строку ```text deployer ALL=(ALL) NOPASSWD: /usr/bin/git, /usr/bin/docker ``` - Редактируем sshd_config через sudo ```bash sudo nano /etc/ssh/sshd_config ``` Должно быть так ```text PermitRootogin no PubkeyAuthentication yes PasswordAuthentication no PermitEmptyPasswords no ``` ```{note} :class: dropdown PermitRootogin запрещает пользователю root входить от имени этого пользователя PubkeyAuthentication разрешает вход по SSH ключу PasswordAuthentication запрещает вход по паролю PermitEmptyPasswords запрещает использование пустых паролей ``` - Добавляем юзера deployer в группу docker, а нашего основного юзера в группу deployer (вместо админ вставьте имя вашего основного юзера) ```bash usermod -aG docker deployer usermod -aG deployer admin ``` 3. Переключаемся на нового юзера ```bash sudo su - deployer ``` 4. Настройка SSH для юзера deployer - Создаем в домашней директории home/deployer папку .ssh ```bash sudo mkdir /home/deployer/.ssh ``` - Создаем файл /home/deployer/.ssh/autorized_keys ```bash touch home/deployer/.ssh/autorized_keys ``` - Генерируем на локальном компьютере SSH ключи по алгоритму Ed25519 В результате получаем 2 ключа с именами deployer ```bash ssh-keygen -t ed25519 -a 200 -C "github actions" ``` - Копируем ПУБЛИЧНЫЙ ключ SSH в /home/deployer/.ssh/autorized_keys 5. Настройки прав доступа (необходимо для подключения по ssh) Настраиваем следующие права для юзера deployer, его директорий и файлов ```bash sudo chmod go-w /home/deployer ``` ```bash sudo chmod 700 /home/deployer/.ssh ``` ```bash sudo chown -R deployer:deployer /home/deployer/.ssh ``` ```bash sudo chmod 600 /home/deployer/.ssh/authorized_keys ``` 6. Настраиваем и открываем порты для работы приложения. Например, порт 55555 ```bash sudo ufw alow 55555/tcp sudo ufw reload sudo ufw status ``` 7. Переключаемся на нового юзера deployer и клонируем приложение с гитхаб ```bash git clone ``` 8. Переходим в папку проекта и создаем в ней файл .env ```bash cd projectTemplate nano .env ``` 9. Заполняем .env по образцу .env.example - копируем все из .env.example, заменяем на свои значения ```{warning} ВАЖНО указать UID и GID юзера deployer во избежание проблем с правами доступа ``` 10. Переключаемся обратно на админа и меняем права доступа для проекта ```bash sudo chown -R deployer:deployer projectTemplate/ ``` ```{note} Очень желательно выполнять все действия под новым юзером, чтобы избежать ошибки с правами доступа ``` #### Настройка на стороне 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 ````note 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 ```` 2. Делаем push на гитхаб, получаем уведомление в телеграм ### ✅ Резюме Теперь твой проект полностью настроен и готов к разработке. Ты можешь: - Писать код в VS Code с поддержкой Python и автодополнением - Использовать виртуальное окружение для изоляции зависимостей - Работать с Git и делать коммиты - Генерировать и читать документацию ---