Перейти к основному содержимому

5.02. Автоматизация и DevOps

В РАЗРАБОТКЕНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНО
Разработчику Архитектору

Автоматизация и DevOps​

Почему Python стал языком автоматизации​

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

Центральная особенность Python, определившая его доминирование в автоматизации, — это скриптовая природа. Под этим понимается возможность запускать код без предварительной компиляции, интерпретируя его «на лету», с минимальными накладными расходами на развёртывание среды. Такой подход позволяет писать небольшие программы, решающие узкие задачи: перенос файлов, анализ логов, отправка уведомлений, генерация отчётов. Эти программы не требуют сборки, не нуждаются в сложной конфигурации зависимостей и часто могут быть запущены одной командой из терминала.

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

Второй фактор — богатая стандартная библиотека. Python поставляется с модулями, покрывающими огромное количество повседневных операций: работа с файловой системой (os, pathlib), сетевое взаимодействие (socket, urllib, http), обработка аргументов командной строки (argparse), парсинг структурированных данных (json, xml, csv, configparser). Для многих рутинных задач сторонние зависимости не требуются — стандартной библиотеки достаточно.

Третий — мощная и зрелая экосистема пакетов. Индекс пакетов PyPI содержит десятки тысяч библиотек, в том числе специализированных для задач DevOps: от библиотек для деплоя (например, fabric, invoke) до инструментов мониторинга (psutil, prometheus_client), управления конфигурацией (ansible-core, salt), тестирования (pytest, locust) и взаимодействия с облачными API (boto3, google-cloud, azure-identity). Эта экосистема не просто велика — она глубоко интегрирована: те же pytest и black могут вызываться как из командной строки, так и из Python-кода, что позволяет строить сложные гибридные сценарии.

Но, пожалуй, наиболее важным является то, что Python не претендует на исключительность в инфраструктуре. Он не заменяет Bash или PowerShell для простейших задач, не вытесняет Go в высокопроизводительных утилитах, не конкурирует с Terraform или Kubernetes в управлении ресурсами. Вместо этого он занимает нишу клейкого слоя — glue language, — связывающего разнородные системы, дополняющего их логикой, которую невозможно выразить в шаблонах или конфигурационных файлах. Именно в этой роли — как инструмента интеграции, адаптации и расширения — Python особенно незаменим.

Автоматизация рутины​

Под автоматизацией рутины в контексте DevOps понимается устранение повторяющихся, предсказуемых, но трудоёмких операций, выполняемых вручную оператором, администратором или разработчиком. Эти операции не требуют принятия решений в реальном времени, но требуют внимания к деталям и чёткого соблюдения последовательности действий. Ручное выполнение таких задач сопряжено с риском ошибок, утомлением и непропорциональными временными затратами.

Python позволяет формализовать подобные процедуры в виде сценариев, которые можно запускать по расписанию (например, через cron или systemd.timer), триггерить по событиям (например, при появлении файла) или включать в состав более сложных процессов (например, как этап CI-конвейера).

Работа с файловой системой​

Одна из самых частых рутин — манипуляции с файлами и каталогами: групповое переименование, фильтрация по шаблонам, архивация устаревших данных, очистка временных файлов. В стандартной библиотеке Python за это отвечают три основных модуля: os, glob и pathlib.

Модуль os — это низкоуровневый интерфейс к операционной системе. Он предоставляет прямой доступ к таким примитивам, как os.listdir(), os.rename(), os.remove(), os.makedirs(). Его сила — в универсальности и близости к системным вызовам. Но его интерфейс часто считается устаревшим: пути представлены строками, что усложняет кроссплатформенную работу (разные разделители: / в Unix-системах и \ в Windows), а операции с путями требуют явного использования os.path.join() и подобных функций.

Модуль glob позволяет работать с файловыми путями по шаблонам, используя wildcard-сопоставление (например, *.log, data_???.csv). Он удобен для массового отбора файлов без написания собственных циклов и условий. Однако его возможности ограничены простыми шаблонами — регулярные выражения он не поддерживает.

Современным и рекомендуемым подходом является использование pathlib, который появился в Python 3.4 и с тех пор стал стандартом de facto. Класс Path инкапсулирует путь как объект первого класса: его можно складывать с другими путями с помощью оператора /, проверять существование через .exists(), получать расширение через .suffix, итерироваться по содержимому каталога через .iterdir(). Более того, pathlib полностью кроссплатформен: объект сам знает, как правильно формировать пути в текущей ОС. Это резко снижает количество ошибок, связанных с несовместимостью путей, и делает код читаемее.

Пример: автоматическая архивация логов старше 30 дней
Сценарий может ежедневно просматривать каталог /var/log/app/, находить файлы, изменённые более месяца назад, сжимать их в архив .tar.gz и перемещать в /var/log/archive/. При этом он может вести журнал своих действий, проверять свободное место перед архивацией и отправлять уведомление при неудаче. Такой сценарий легко реализуется с помощью pathlib, shutil, tarfile, datetime и logging — все эти модули входят в стандартную поставку.

Управление зависимостями и окружениями​

Другая распространённая рутина — поддержание актуальности проектных зависимостей. В Python-проектах это означает обновление пакетов, перечисленных в requirements.txt или pyproject.toml. Ручной перебор версий, проверка совместимости, анализ changelog’ов — всё это требует времени. Автоматизированный подход позволяет, например, еженедельно проверять, какие пакеты имеют обновлённые мажорные версии, генерировать pull request с обновлёнными requirements, запускать тесты и, при успехе, сливать изменения.

Для этого можно использовать встроенные возможности pip list --outdated, но более гибко — задействовать importlib.metadata (начиная с Python 3.8) или сторонние библиотеки вроде pip-api. Сценарий может:

  • прочитать текущие версии из requirements.txt;
  • для каждого пакета запросить список доступных версий через PyPI API (requests + https://pypi.org/pypi/{package}/json);
  • сравнить семантические версии с учётом политики проекта (только патч-версии? только минорные? мажорные — только после ручного одобрения?);
  • сгенерировать diff и отчёт.

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

Контекст DevOps​

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

  1. Идемпотентность — повторный запуск сценария не должен приводить к побочным эффектам (например, двойному переименованию файла или дублированию записей в логе). Это достигается проверкой состояния перед действием: «существует ли файл?», «уже ли архивирован?».

  2. Логирование и наблюдаемость — каждый скрипт должен писать структурированные логи (например, в JSON через logging), чтобы его поведение можно было отследить в централизованной системе (ELK, Loki, Splunk). Без этого автоматизация быстро превращается в «чёрный ящик», отказ которого трудно диагностировать.

  3. Параметризация — жёстко закодированные пути, адреса или токены — признак неготовности сценария к эксплуатации. Все внешние параметры должны передаваться через переменные окружения, аргументы командной строки или конфигурационные файлы.

  4. Обработка ошибок — автоматизация должна корректно завершать работу, освобождать ресурсы и информировать оператора. Использование контекстных менеджеров (with), явные try/except/finally, проверки на None и пустые коллекции — обязательные элементы надёжного сценария.

Автоматизация тестирования​

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

Следует различать два уровня автоматизации тестирования:

  • Автоматизация написания и выполнения тестов — это использование фреймворков, позволяющих выразить проверки в декларативной или императивной форме, а затем запустить их единообразно, с отчётом о результатах.
  • Автоматизация поддержки тестирования — это подготовка тестовых данных, настройка окружения, мониторинг состояния системы во время прогона, постобработка логов и артефактов.

Python эффективно реализует оба уровня.

Фреймворки​

В стандартной библиотеке Python присутствует модуль unittest, вдохновлённый xUnit-подходом (JUnit, NUnit). Он предоставляет класс TestCase, методы setUp() и tearDown() для инициализации и очистки, а также набор assertion-методов (assertEqual, assertTrue, assertRaises и др.). Преимущества unittest — отсутствие внешних зависимостей и предсказуемость. Однако его структура требует наследования и явного объявления тест-методов, что увеличивает объём шаблонного кода.

Для документационных тестов существует doctest. Он позволяет встраивать примеры вызовов и ожидаемых результатов прямо в docstring’ы функций. Запустив doctest.testmod(), можно проверить, соответствует ли текущая реализация приведённым примерам. Это особенно полезно для библиотек: примеры в документации одновременно становятся исполняемыми тестами, гарантируя их актуальность. Однако doctest плохо подходит для сложных сценариев — он не предназначен для проверки побочных эффектов, работы с внешними системами или асинхронного кода.

Более современные фреймворки — pytest, nose (устаревший), nose2 — пришли из сообщества и быстро завоевали доминирующие позиции. Из них pytest стал de facto стандартом. Его сила — в простоте базового сценария и глубине расширяемости.

В pytest тест — это обычная функция, имя которой начинается с test_. Утверждения используются в виде обычного Python-кода:

def test_addition():
    assert 2 + 2 == 4

Нет необходимости наследоваться от базового класса, импортировать специальные assertion-методы или оборачивать проверки. При провале assert pytest автоматически показывает значения всех подвыражений в левой и правой частях — это значительно ускоряет диагностику.

Но главное преимущество pytest — в его экосистеме плагинов и встроенных возможностях, критически важных для DevOps:

  • Фикстуры (@pytest.fixture) позволяют инкапсулировать подготовку и очистку ресурсов (соединение с БД, временный каталог, mock-сервер). Фикстуры могут иметь разные области видимости: function, class, module, session — что даёт тонкий контроль над затратами на инициализацию.
  • Параметризация (@pytest.mark.parametrize) позволяет запустить один и тот же тест с разными наборами входных данных и ожидаемых результатов, не дублируя код.
  • Маркеры (@pytest.mark) — метаданные, которые можно использовать для отбора тестов (pytest -m smoke), пропуска в определённых условиях (skipif) или интеграции с CI (например, @pytest.mark.slow для вынесения длительных тестов в отдельный джоб).
  • Плагины расширяют функциональность: pytest-cov для измерения покрытия кода, pytest-xdist для параллельного запуска, pytest-mock для удобной работы с unittest.mock, pytest-asyncio для тестирования корутин.

Для небольшого скрипта достаточно doctest или даже ручных assert. Для библиотеки с публичным API оправдан pytest с покрытием и параметризацией. Для legacy-проекта, где уже используется unittest, миграция может быть нецелесообразна — pytest умеет запускать тесты unittest, обеспечивая постепенный переход.

Генерация тестовых данных​

Надёжное тестирование невозможно без качественных тестовых данных. Ручной подбор значений быстро исчерпывает себя: он не покрывает граничные случаи, не масштабируется и трудно поддерживается. Python предлагает два подхода к автоматизации генерации данных.

Первый — статистическое моделирование с помощью библиотеки Faker. Она предоставляет фабрики для генерации реалистичных, но фиктивных данных: имён, адресов, email, телефонов, банковских реквизитов, текста, дат, IP-адресов и многого другого — с учётом локализации (например, русскоязычные имена через Faker('ru_RU')). Это особенно ценно при тестировании UI, валидации форм или интеграции с внешними системами, где формат данных строго регламентирован.

Пример: генерация 1000 пользователей для нагрузочного теста
Вместо написания цикла со строковыми шаблонами (user{i}@example.com) можно создать провайдера, который будет выдавать семантически корректные данные, уменьшая риск ложных срабатываний из-за неверного формата.

Второй подход — свойство-ориентированное тестирование (property-based testing), реализованное в библиотеке Hypothesis. Вместо задания конкретных примеров, программист формулирует инвариант — утверждение, которое должно выполняться для любого входного значения из заданного домена. Hypothesis затем генерирует сотни и тысячи комбинаций входных данных, включая экстремальные случаи (пустые строки, очень большие числа, Unicode-символы, спецсимволы), и ищет контрпример, нарушающий инвариант.

Например, для функции сортировки можно объявить:
«Результат всегда является перестановкой входного списка и упорядочен по возрастанию».
Hypothesis сам найдёт, например, список с NaN, который ломает сравнение, или циклические ссылки, если функция не рассчитана на них.

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

Нагрузочное и мутационное тестирование​

Функциональные тесты отвечают на вопрос «делает ли система то, что должна?». Но в DevOps-практике не менее важны вопросы «выдержит ли система пиковую нагрузку?» и «насколько хрупок наш тестовый набор?».

Для имитации нагрузки на HTTP-API широко используется Locust. В отличие от классических инструментов вроде JMeter, Locust описывает поведение пользователей на Python. Каждый «пользователь» — это экземпляр класса, в котором определены сценарии: «зайти на сайт», «авторизоваться», «отправить запрос к API». Это позволяет моделировать реалистичные сценарии: задержки между действиями, ветвление логики, использование кук, обработка ответов. Locust масштабируется горизонтально — несколько воркеров могут управляться через веб-интерфейс, а метрики (RPS, время отклика, ошибки) собираются в реальном времени и могут экспортироваться в Prometheus или Grafana.

Для проверки качества тестов применяется мутационное тестирование, реализованное в инструменте mutmut. Идея проста: если тестовый набор хорош, он должен «замечать» даже незначительные изменения в коде (мутации), такие как замена > на >=, удаление ветви условия, инкремент вместо декремента. mutmut автоматически вносит такие изменения в исходный код, запускает тесты и фиксирует, какие мутации «выжили» — то есть тесты не упали. Количество выживших мутаций — объективная метрика надёжности тестов, гораздо более содержательная, чем простое покрытие строк.

Автоматизация UI​

Тестирование пользовательского интерфейса исторически считается трудоёмким и хрупким. Python стал одним из основных языков для этой задачи благодаря библиотеке Selenium WebDriver. Она предоставляет единый API для управления браузерами (Chrome, Firefox, Edge) через драйверы. Код на Python отправляет команды: открыть URL, найти элемент по селектору, ввести текст, кликнуть, дождаться появления элемента — и проверяет результат.

Современные практики, однако, стремятся минимизировать объём end-to-end UI-тестов. Они медленны, зависят от внешнего состояния (сети, таймаутов) и ломаются при изменении верстки. Поэтому стратегия такова:

  • Максимальная логика выносится в unit- и integration-тесты (без UI).
  • UI-тесты покрывают только критические бизнес-сценарии: «пользователь может оформить заказ», «администратор может заблокировать аккаунт».
  • Используются паттерны, повышающие устойчивость: Page Object Model (инкапсуляция локаторов и действий в классах-страницах), явные ожидания вместо time.sleep(), изоляция тестов через уникальные тестовые данные.

С развитием headless-браузеров и библиотек вроде Playwright (есть Python-биндинги) и Puppeteer (через pyppeteer), появилась возможность тестировать веб и Electron-приложения, а также проводить скриншот-тестирование и анализ производительности.

Интеграция в DevOps​

Автоматизированные тесты перестают быть «полезной опцией», когда они встраиваются в жизненный цикл поставки:

  • Pre-commit hook: быстрые unit-тесты и проверка стиля запускаются локально перед коммитом (с помощью pre-commit).
  • CI-pipeline: при пуше в ветку запускаются все тесты: unit, integration, возможно, smoke-тесты UI. Провал одного из этапов — повод не мержить.
  • Pre-deploy gate: перед развёртыванием в production запускается набор регрессионных тестов на staging-среде.
  • Canary-тесты: после частичного развёртывания — автоматические проверки работоспособности на живом трафике (health-check, smoke-запросы).

Python, благодаря единообразию запуска (pytest, python -m unittest) и богатым возможностям отчёта (JUnit XML, JSON), легко интегрируется в любую CI/CD-систему: GitLab CI, GitHub Actions, Jenkins, TeamCity.

CI/CD и инструменты качества кода​

В DevOps-культуре поставка ПО рассматривается как непрерывный поток преобразований: исходный код → сборка → тестирование → развёртывание → мониторинг. Каждый этап этого потока должен быть автоматизирован, воспроизводим и проверяем. Однако автоматизация действий — лишь половина дела. Вторая, не менее важная часть — автоматизация контроля. Именно она позволяет сохранять стабильность потока, предотвращать накопление технического долга и обеспечивать уверенность в каждом новом релизе.

Python, благодаря своей выразительности и зрелой экосистеме инструментов статического анализа, стал одной из ключевых платформ для реализации такой инженерной гигиены. При этом важно понимать: эти инструменты не предназначены для «поиска ошибок» в узком смысле — они формируют среду, в которой ошибки труднее допустить.

Форматирование кода​

Споры о стиле кода — отступах, пробелах вокруг операторов, порядке импортов — исторически отнимали у команд значительное количество времени на code review. Python предложил радикальное решение: делегировать форматирование машине.

Библиотека Black — самый яркий пример такого подхода. Её принцип: «не настраивается — и это преимущество». Black применяет жёсткий, предсказуемый алгоритм форматирования, основанный на максимальной читаемости и минимальной субъективности. Он не предлагает выбор между 2 и 4 пробелами — он всегда использует 4. Он не оставляет интерпретации, как переносить длинные списки или вызовы функций — он делает это единообразно.

Результат — идемпотентное форматирование: повторный запуск Black на уже отформатированном файле не вносит изменений. Это критически важно для CI: если в конвейере запускается Black с проверкой (--check), а код не соответствует стандарту, сборка падает — и разработчик вынужден отформатировать код до отправки на review. Таким образом, время ревью тратится только на архитектурные и логические аспекты.

Дополнительно к Black используется isort — специализированный инструмент для сортировки и группировки импортов. Он разделяет стандартные, сторонние и локальные импорты, располагает их в алфавитном порядке внутри групп и устраняет дубликаты. Хотя Black также умеет форматировать импорты, isort даёт более тонкий контроль — например, поддержку профилей (Django, Google Style) и исключений для конкретных модулей.

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

Статический анализ​

Форматирование решает проблему читаемости. Статический анализ решает проблему корректности — пусть и с вероятностным характером.

pylint — один из старейших и наиболее комплексных линтеров для Python. Он проверяет не только соответствие PEP 8, но и:

  • использование неопределённых переменных;
  • неиспользуемые импорты и локальные переменные;
  • несоответствие сигнатур методов в наследовании;
  • сложность функций (цикломатическая сложность);
  • потенциальные проблемы безопасности (например, использование exec без валидации).

Каждое замечание сопровождается кодом (например, C0301 — слишком длинная строка) и описанием, что позволяет настраивать поведение через конфигурационный файл (.pylintrc). pylint выдаёт общий балл за модуль — метрика, которую можно трекать во времени и использовать как индикатор технического долга.

Более современный и быстрый альтернативный стек — flake8 в связке с плагинами. flake8 сам по себе — обёртка над pyflakes (проверка логики), pycodestyle (проверка PEP 8) и mccabe (анализ сложности). Его преимущество — модульность: через систему плагинов можно подключить, например, flake8-bugbear (поиск хрупких паттернов), flake8-comprehensions (рекомендации по использованию генераторов), flake8-annotations (проверка аннотаций типов). Запуск flake8 быстрее, чем pylint, что делает его удобным для pre-commit проверок.

Особое место занимает mypy — статический анализатор, ориентированный на проверку аннотаций типов. Python остаётся динамически типизированным языком, но с версии 3.5 поддерживает необязательные аннотации (def f(x: int) -> str:). mypy анализирует их статически, не запуская код, и находит несоответствия: передачу строки туда, где ожидается число, возврат None из функции, обещавшей вернуть объект. Это особенно ценно в крупных проектах: аннотации становятся формальной спецификацией интерфейсов, а mypy — средством её верификации задолго до runtime.

Ни один из этих инструментов не является «авторитетом». Их предупреждения — не директивы, а гипотезы о возможных проблемах. Конфигурация и отбор правил — часть договорённостей внутри команды. Например, запрет print() в production-коде может быть оправдан, а в CLI-утилите — нет. Ключевой принцип — последовательность: если правило включено, оно должно соблюдаться везде.

Pre-commit​

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

Подход pre-commit радикально меняет эту модель: проверки выполняются локально, до создания коммита. Инструмент pre-commit управляет набором хуков, описанных в файле .pre-commit-config.yaml. При каждом git commit он:

  1. создаёт изолированное виртуальное окружение для каждого хука;
  2. устанавливает необходимые зависимости;
  3. запускает указанные утилиты только по изменённым файлам;
  4. при провале любого хука — прерывает коммит и выводит отчёт.

Типичная конфигурация включает:

  • black с --check;
  • isort с --check-only;
  • flake8 или pylint;
  • mypy (часто только для core-модулей из-за скорости);
  • check-yaml, check-toml — валидация конфигов;
  • trailing-whitespace, end-of-file-fixer — мелкая гигиена.

Преимущество такого подхода — немедленная обратная связь. Разработчик видит ошибку стиля или неиспользуемую переменную в момент коммита, когда контекст ещё свеж в памяти. Это резко сокращает цикл «написать → закоммитить → увидеть ошибку → исправить». Кроме того, pre-commit гарантирует, что в историю попадает только код, прошедший базовые проверки — что упрощает аудит и рефакторинг.

Мониторинг инфраструктуры и приложений​

Автоматизация качества не ограничивается кодом. В DevOps-практике критически важна способность наблюдать за состоянием системы — как во время разработки, так и в production. Python здесь выступает как универсальный язык написания агентов мониторинга: компактных программ, которые собирают метрики, анализируют логи и реагируют на отклонения.

Наблюдение за ресурсами​

Библиотека psutil (process and system utilities) предоставляет кроссплатформенный API для получения информации о:

  • загрузке CPU (всей системы и по ядрам);
  • использовании оперативной памяти и swap;
  • дисковых операциях (чтение/запись, объём свободного места);
  • сетевых интерфейсах (трафик, ошибки);
  • запущенных процессах (PID, потребление ресурсов, дерево порождения).

На основе psutil можно строить:

  • health-check скрипты, которые отправляют алерт при превышении порога использования памяти;
  • профилировщики ресурсов, фиксирующие, какой модуль или функция вызывает всплеск CPU;
  • автоматические регуляторы — например, сценарий, который приближает потребление памяти к 90%, останавливает менее приоритетные процессы или инициирует graceful shutdown сервиса.

Важно: psutil не заменяет Prometheus или Zabbix. Он — строительный блок для кастомных решений, когда стандартные метрики недостаточны, или когда нужно интегрировать мониторинг в логику приложения.

Следящие за файлами​

Для реакции на события в файловой системе используется watchdog. Он инкапсулирует различия между механизмами inotify (Linux), kqueue (BSD/macOS) и ReadDirectoryChangesW (Windows), предоставляя единый интерфейс наблюдения за каталогами.

Типичные сценарии:

  • Автоматическая пересборка документации при изменении .md-файлов;
  • Перезапуск веб-сервера в режиме разработки при изменении исходного кода;
  • Отслеживание появления новых лог-файлов и их передача в агрегатор;
  • Реакция на создание файла с определённым шаблоном имени (например, *.trigger) — запуск обработчика.

watchdog позволяет писать реактивные системы без постоянного опроса (polling), что снижает нагрузку на диск и уменьшает задержку реакции.

Оперативная реакция​

Сбор данных сам по себе бесполезен без действия. Python облегчает интеграцию с каналами оперативного реагирования:

  • Telegram Bot API (python-telegram-bot или requests напрямую): отправка сообщения в группу инженеров при падении сервиса. Простой скрипт может проверять статус HTTP-эндпоинта раз в минуту и при 5 последовательных ошибках формировать алерт с контекстом (время, URL, код ответа).
  • Email через smtplib: для менее срочных уведомлений — например, еженедельный отчёт о росте технического долга.
  • Slack Webhooks, Mattermost, Rocket.Chat: интеграция в корпоративные мессенджеры через их REST API.

Ключевой принцип — минимизация ложных срабатываний. Алерт должен быть:

  • конкретным («сервис /api/users возвращает 500 в течение 30 секунд»);
  • действенным (содержать ссылку на дашборд, команду для перезапуска, имя ответственного);
  • дедуплицированным (повторные уведомления по одной проблеме подавляются).
Простой мониторинг доступности​

Для базовой проверки работоспособности внешних зависимостей достаточно двух библиотек:

  • requests — для HTTP-запросов. Проверка status code, времени ответа, наличия ключевых фраз в теле.
  • ping3 — для ICMP-пинга (альтернатива системному ping, но без прав суперпользователя на большинстве систем). Позволяет измерить RTT до хоста, проверить его доступность на сетевом уровне.

Их можно комбинировать в сценарий, который каждые 5 минут проверяет:

  1. Доступен ли DNS (например, запрос к https://1.1.1.1/dns-query?...);
  2. Отвечает ли gateway;
  3. Возвращает ли внутренний health-check 200 OK;
  4. Соответствует ли содержимое landing page шаблону.

При нарушении любого из условий — отправка алерта с полным контекстом (какие проверки пройдены, какие — нет).

Интеграция в CI/CD​

Автоматизация, существующая только на машине одного разработчика, не является автоматизацией в смысле DevOps. Чтобы сценарий стал частью инженерного процесса, он должен быть:

  • Воспроизводим — давать одинаковый результат при любом запуске, независимо от времени, места и окружения;
  • Изолирован — не зависеть от глобального состояния хоста (установленных пакетов, переменных окружения, версий утилит);
  • Атомарен — либо полностью завершаться успешно, либо откатываться без побочных эффектов;
  • Наблюдаем — оставлять артефакты, по которым можно диагностировать успех или провал.

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

Управление зависимостями​

Наивный подход — фиксация зависимостей в requirements.txt с помощью pip freeze. Он прост, но опасен:

  • pip freeze сохраняет все установленные пакеты, включая транзитивные зависимости и инструменты разработки (например, black, pytest);
  • Отсутствие привязки к хешам артефактов (--hash) делает сборку уязвимой к компрометации PyPI или сетевых атак «человек посередине»;
  • Разные версии pip или ОС могут разрешать зависимости по-разному, приводя к несовместимым окружениям.

Современные практики предполагают разделение декларативного и императивного:

  1. Декларативный файл зависимостей (pyproject.toml с [project.dependencies], или requirements.in) — содержит только прямые зависимости проекта, без версий или с мягкими ограничениями (django>=4.2,<5.0). Это — спецификация.

  2. Замороженный файл фиксированных версий (requirements.txt, poetry.lock, pipfile.lock) — генерируется инструментом и содержит все зависимости, включая транзитивные, с точными версиями и, предпочтительно, с криптографическими хешами. Это — манифест.

Инструменты, реализующие этот подход:

  • pip-tools — для экосистемы pip. Команда pip-compile requirements.in генерирует requirements.txt; pip-sync синхронизирует окружение строго по манифесту.
  • Poetry — полноценный менеджер зависимостей и сборки. Он управляет виртуальными окружениями, разрешает зависимости с учётом конфликтов, поддерживает монорепозитории и публикацию пакетов. poetry.lock гарантирует идентичность окружений на всех этапах.
  • PDM — современная альтернатива, полностью совместимая со стандартом PEP 621 и ориентированная на скорость и детерминизм.

В CI-конвейере сборка всегда должна использовать замороженный файл. Локально разработчик работает с декларативным, а обновление манифеста (pip-compile --upgrade, poetry update) — отдельная, осознанная операция, сопровождаемая тестированием.

Изоляция окружений​

Глобальная установка пакетов через sudo pip install — анти-паттерн. Она нарушает изоляцию проектов, приводит к конфликтам версий и делает систему непредсказуемой.

Виртуальные окружения — стандартный механизм изоляции в Python. Они создают каталог с собственным интерпретатором (символической ссылкой на системный python), site-packages и pip.

  • venv — встроенный модуль (с Python 3.3). Создание: python -m venv .venv. Прост, надёжен, не требует внешних зависимостей.
  • virtualenv — сторонний, более гибкий (поддержка старых версий Python), но избыточен в большинстве случаев.
  • conda — подходит, если проект требует Python-пакеты и бинарные зависимости (например, numpy с оптимизированными BLAS-библиотеками, или R-пакетов). Однако для чисто Python-проектов он избыточен и медленнее.

В CI-системах виртуальное окружение создаётся на каждом запуске — это гарантирует, что сборка не зависит от состояния кэша предыдущих джобов. Кэширование site-packages допустимо, но только при условии, что ключ кэша включает хеш манифеста зависимостей (например, hash(requirements.txt)). Иначе обновление зависимости не приведёт к пересборке.

Безопасность автоматизации​

Автоматизация, обращающаяся к API (внешним сервисам, облачным провайдерам, базам данных), неизбежно сталкивается с необходимостью хранения учётных данных. Жёсткое кодирование токенов, паролей или ключей в скриптах — критическая уязвимость.

Принципы безопасного обращения с секретами​

  1. Никогда не храните секреты в репозитории — ни в открытом виде, ни в зашифрованном (если ключ для расшифровки тоже в репозитории). Даже в приватных репозиториях история коммитов может быть скомпрометирована.

  2. Передавайте секреты через переменные окружения — стандартный, кроссплатформенный механизм. В коде используйте os.getenv("API_KEY") с проверкой на None и понятным сообщением об ошибке.

  3. Используйте vault-системы в production — HashiCorp Vault, AWS Secrets Manager, Azure Key Vault. В CI-конвейерах секреты подставляются через защищённые переменные (GitLab CI masked variables, GitHub Actions secrets), которые не попадают в логи и не экспортируются в дочерние процессы без явного разрешения.

  4. Минимизируйте привилегии — выдавайте токенам только необходимые права (принцип минимальных привилегий). Например, для деплоя достаточно прав на запись в bucket S3, но не на управление IAM-ролями.

Проверка уязвимостей в зависимостях​

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

  • safety — проверяет зависимости против базы данных уязвимостей от PyUp. Работает с requirements.txt, поддерживает offline-режим.
  • pip-audit — официальный инструмент от Python Packaging Authority (PyPA), использующий данные Advisory Database от GitHub. Интегрируется с pip и Poetry.
  • bandit — статический анализатор кода на предмет распространённых уязвимостей: pickle, exec, небезопасные шаблоны, hard-coded credentials.

В CI-конвейере рекомендуется запускать safety check или pip-audit на этапе сборки. При обнаружении критической уязвимости (CVE с высоким CVSS) сборка должна прерываться — это создаёт «шлюз безопасности» перед развёртыванием.

Документирование автоматизации​

Скрипт без документации — технический долг. Через шесть месяцев даже автор не вспомнит, зачем нужен флаг --force-clean, или почему задержка между запросами — ровно 1.7 секунды.

Python поддерживает самодокументирование:

  • Docstrings в формате Google, NumPy или reStructuredText — для модулей, функций, классов. Инструменты вроде sphinx могут генерировать HTML-документацию из них.
  • Аргументы командной строки через argparse — метод add_argument() принимает параметр help=, который автоматически включается в --help.
  • Примеры использования в __main__-блоке — запуск скрипта с --example может вывести готовый рабочий пример вызова.

Но главное — внешняя документация. В Confluence, Notion или в самом репозитории (в docs/ или README.md) должен быть раздел, отвечающий на вопросы:

  • Какие задачи решает этот скрипт?
  • Какие предусловия требуются (окружение, переменные, файлы)?
  • Какие побочные эффекты возможны (изменение файлов, отправка запросов)?
  • Как диагностировать провал?
  • Кто отвечает за поддержку?

Без этого автоматизация быстро превращается в «магию», которую боятся трогать — и которую при первой же поломке отключают «на всякий случай».

Тестирование самих сценариев автоматизации​

Сценарии автоматизации — это тоже код. И он подвержен ошибкам: опечатки в путях, неправильная обработка исключений, предположения об окружении. Их необходимо тестировать.

Подходы:

  • Unit-тесты для вспомогательных функций — логика парсинга, форматирования, принятия решений выносится в отдельные функции и покрывается pytest.
  • Интеграционные тесты с временными каталогами — с помощью pytest и фикстуры tmp_path создаётся изолированное дерево файлов, на котором проверяется поведение скрипта.
  • End-to-end тесты в изолированном окружении — запуск скрипта в Docker-контейнере с моками внешних сервисов (например, через pytest-localserver для HTTP).

Отказ от тестирования автоматизации — иллюзия экономии времени. Реальная цена — часы, потраченные на диагностику «почему CI сломался в пятницу вечером».

Примеры сценариев автоматизации​

1. Автоархивация логов (log_archiver.py)​

Решает задачу: безопасное сжатие и перемещение старых лог-файлов с сохранением структуры, контролем места и уведомлением при ошибках.

#!/usr/bin/env python3
"""
Автоматическая архивация лог-файлов.

Скрипт просматривает указанный каталог, находит файлы старше заданного возраста,
сжимает их в tar.gz-архивы и перемещает в архивный каталог. Перед архивацией
проверяется свободное место. Все действия логируются в JSON-формате.

Требования:
- Python ≥ 3.8
- Не требует сторонних зависимостей.

Использование:
    python log_archiver.py \
        --source /var/log/app \
        --archive /var/log/archive \
        --days 30 \
        --min-free-space 1GB \
        --dry-run

Переменные окружения (альтернатива CLI):
    LOG_ARCHIVER_SOURCE      — каталог с логами
    LOG_ARCHIVER_ARCHIVE     — каталог архивов
    LOG_ARCHIVER_DAYS        — порог возраста (в днях)
    LOG_ARCHIVER_MIN_FREE    — минимальный объём свободного места (например, "2.5GB")
    LOG_ARCHIVER_DRY_RUN     — "1" для тестового прогона без изменений
    TELEGRAM_BOT_TOKEN       — токен бота (опционально, для алертов)
    TELEGRAM_CHAT_ID         — ID чата (опционально)
"""

import argparse
import json
import logging
import os
import shutil
import subprocess
import sys
import time
from datetime import datetime, timedelta
from pathlib import Path


# === Настройка логгера ===
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    handlers=[
        logging.StreamHandler(sys.stdout),
        logging.FileHandler("/var/log/log_archiver.log", encoding="utf-8"),
    ],
)
logger = logging.getLogger(__name__)


def parse_size(size_str: str) -> int:
    """Преобразует строку вида '1.5GB' в байты."""
    size_str = size_str.upper().strip()
    multipliers = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
    for unit, mult in multipliers.items():
        if size_str.endswith(unit):
            try:
                value = float(size_str[: -len(unit)].strip())
                return int(value * mult)
            except ValueError:
                pass
    raise ValueError(f"Некорректный формат размера: {size_str}")


def get_free_space(path: Path) -> int:
    """Возвращает свободное место на устройстве в байтах."""
    stat = os.statvfs(path)
    return stat.f_bavail * stat.f_frsize


def archive_file(file_path: Path, archive_dir: Path, dry_run: bool = False) -> bool:
    """Архивирует один файл в tar.gz и удаляет оригинал при успехе."""
    try:
        archive_name = f"{file_path.stem}_{file_path.stat().st_mtime:.0f}.tar.gz"
        archive_path = archive_dir / archive_name

        if dry_run:
            logger.info(f"[DRY-RUN] Будет создан архив: {archive_path}")
            return True

        # Создаём архив с сохранением прав и времён
        cmd = [
            "tar",
            "-czf",
            str(archive_path),
            "-C",
            str(file_path.parent),
            file_path.name,
        ]
        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
        logger.debug(f"tar stdout: {result.stdout}")
        logger.debug(f"tar stderr: {result.stderr}")

        # Удаляем оригинал только после успешного архивирования
        file_path.unlink()
        logger.info(f"Архивирован и удалён: {file_path} → {archive_path}")
        return True

    except subprocess.CalledProcessError as e:
        logger.error(f"Ошибка tar для {file_path}: {e.stderr}")
        return False
    except Exception as e:
        logger.exception(f"Необработанная ошибка при архивации {file_path}: {e}")
        return False


def send_telegram_alert(message: str):
    """Отправляет уведомление в Telegram (если настроены токен и chat_id)."""
    bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
    chat_id = os.getenv("TELEGRAM_CHAT_ID")
    if not bot_token or not chat_id:
        return

    try:
        import requests  # lazy import — только при необходимости
        url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
        payload = {
            "chat_id": chat_id,
            "text": f"[LogArchiver] {message}",
            "parse_mode": "Markdown",
        }
        requests.post(url, json=payload, timeout=10)
    except Exception as e:
        logger.warning(f"Не удалось отправить Telegram-алерт: {e}")


def main():
    parser = argparse.ArgumentParser(description="Автоархивация логов")
    parser.add_argument("--source", required=False, help="Каталог с логами")
    parser.add_argument("--archive", required=False, help="Каталог для архивов")
    parser.add_argument("--days", type=int, default=30, help="Возраст файлов в днях")
    parser.add_argument(
        "--min-free-space", default="1GB", help="Минимум свободного места (напр., 2.5GB)"
    )
    parser.add_argument("--dry-run", action="store_true", help="Тестовый прогон")

    args = parser.parse_args()

    # Приоритет: CLI > ENV > default (но source/archive обязательны)
    source_dir = Path(args.source or os.getenv("LOG_ARCHIVER_SOURCE"))
    archive_dir = Path(args.archive or os.getenv("LOG_ARCHIVER_ARCHIVE"))
    days = args.days or int(os.getenv("LOG_ARCHIVER_DAYS", 30))
    min_free = args.min_free_space or os.getenv("LOG_ARCHIVER_MIN_FREE", "1GB")
    dry_run = args.dry_run or os.getenv("LOG_ARCHIVER_DRY_RUN") == "1"

    if not source_dir or not archive_dir:
        logger.error("Не указаны --source и --archive (или переменные окружения)")
        sys.exit(1)

    try:
        min_bytes = parse_size(min_free)
        cutoff_time = time.time() - days * 86400  # 86400 = секунд в дне
        archive_dir.mkdir(parents=True, exist_ok=True)

        # Проверка свободного места
        free_bytes = get_free_space(archive_dir)
        if free_bytes < min_bytes:
            msg = f"Недостаточно места в {archive_dir}: {free_bytes / 1e9:.2f} GB < {min_free}"
            logger.error(msg)
            send_telegram_alert(msg)
            sys.exit(1)

        # Сбор подходящих файлов
        candidates = [
            f
            for f in source_dir.rglob("*")
            if f.is_file() and f.stat().st_mtime < cutoff_time
        ]

        logger.info(f"Найдено {len(candidates)} файлов старше {days} дней в {source_dir}")

        success_count = 0
        for file in candidates:
            if archive_file(file, archive_dir, dry_run):
                success_count += 1

        summary = (
            f"Архивация завершена: {success_count}/{len(candidates)} файлов обработано."
        )
        logger.info(summary)
        if not dry_run and len(candidates) > 0:
            send_telegram_alert(summary)

    except Exception as e:
        error_msg = f"Критическая ошибка: {e}"
        logger.exception(error_msg)
        send_telegram_alert(error_msg)
        sys.exit(1)


if __name__ == "__main__":
    main()

Как использовать и интегрировать​

  • Запуск по расписанию:
    Добавить в crontab (например, ежедневно в 02:00): 
    0 2 * * * /opt/scripts/log_archiver.py --source /var/log/app --archive /var/log/archive --days 30
  • В CI/CD:
    Включить в stage cleanup для сборочных агентов — архивировать логи сборки старше 7 дней.
  • Безопасность:
    Запускать от пользователя с минимальными правами (только чтение в source, запись в archive).
    Секреты Telegram — только через переменные окружения, не в CLI.

2. Health-check бот с алертингом (health_monitor.py)​

Решает задачу: непрерывная проверка доступности сервисов и оперативное оповещение при сбое.

#!/usr/bin/env python3
"""
Health-check монитор с Telegram-оповещением.

Проверяет доступность списка сервисов по HTTP и ICMP. При N последовательных
провалах отправляет алерт в Telegram. Поддерживает кастомные проверки (например,
наличие ключевой фразы в теле ответа).

Требования:
    pip install requests ping3

Конфигурация — через YAML-файл (см. пример ниже) или переменные окружения.

Пример config.yaml:
    services:
      - name: "API Gateway"
        url: "https://api.example.com/health"
        timeout: 5
        expected_status: 200
        expected_text: "OK"
        failure_threshold: 3

      - name: "Database Host"
        host: "db.internal"
        type: "icmp"
        failure_threshold: 2

    telegram:
        bot_token: "${TELEGRAM_BOT_TOKEN}"  # подстановка из env
        chat_id: "${TELEGRAM_CHAT_ID}"
"""

import argparse
import json
import logging
import os
import sys
import time
import yaml
from pathlib import Path

import requests
from ping3 import ping


logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[logging.StreamHandler(sys.stdout)],
)
logger = logging.getLogger(__name__)


class HealthMonitor:
    def __init__(self, config_path: str):
        with open(config_path) as f:
            raw_config = yaml.safe_load(f)

        # Подстановка переменных окружения вида ${VAR}
        config_str = json.dumps(raw_config)
        for key, value in os.environ.items():
            config_str = config_str.replace(f"${{{key}}}", value)
        self.config = json.loads(config_str)

        self.state = {}  # имя сервиса → счётчик провалов

    def check_http(self, service: dict) -> bool:
        try:
            resp = requests.get(
                service["url"],
                timeout=service.get("timeout", 10),
                headers={"User-Agent": "HealthMonitor/1.0"},
            )
            if resp.status_code != service.get("expected_status", 200):
                logger.warning(f"{service['name']}: статус {resp.status_code}")
                return False
            if (text := service.get("expected_text")) and text not in resp.text:
                logger.warning(f"{service['name']}: не найден текст '{text}'")
                return False
            return True
        except Exception as e:
            logger.error(f"{service['name']}: HTTP ошибка — {e}")
            return False

    def check_icmp(self, service: dict) -> bool:
        try:
            delay = ping(service["host"], timeout=service.get("timeout", 2))
            return delay is not None
        except Exception as e:
            logger.error(f"{service['name']}: ICMP ошибка — {e}")
            return False

    def check_service(self, service: dict) -> bool:
        check_type = service.get("type", "http")
        if check_type == "http":
            return self.check_http(service)
        elif check_type == "icmp":
            return self.check_icmp(service)
        else:
            logger.error(f"Неизвестный тип проверки: {check_type}")
            return False

    def run_once(self):
        for svc in self.config["services"]:
            name = svc["name"]
            is_ok = self.check_service(svc)

            # Инициализация состояния
            if name not in self.state:
                self.state[name] = 0

            if is_ok:
                if self.state[name] > 0:
                    logger.info(f"{name}: восстановлен после {self.state[name]} сбоев")
                    self._send_alert(f"✅ {name} восстановлен")
                self.state[name] = 0
            else:
                self.state[name] += 1
                threshold = svc.get("failure_threshold", 3)
                if self.state[name] >= threshold:
                    self._send_alert(f"❌ {name} недоступен ({self.state[name]} сбоев подряд)")

    def _send_alert(self, message: str):
        tg = self.config.get("telegram", {})
        token = tg.get("bot_token")
        chat_id = tg.get("chat_id")
        if not token or not chat_id:
            return

        try:
            url = f"https://api.telegram.org/bot{token}/sendMessage"
            payload = {"chat_id": chat_id, "text": f"[HealthMonitor] {message}"}
            requests.post(url, json=payload, timeout=5)
        except Exception as e:
            logger.warning(f"Ошибка отправки Telegram: {e}")


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--config", default="config.yaml", help="Путь к конфигу")
    parser.add_argument("--interval", type=int, default=60, help="Интервал проверки (сек)")
    args = parser.parse_args()

    try:
        monitor = HealthMonitor(args.config)
        logger.info(f"Запущен мониторинг с интервалом {args.interval} сек")
        while True:
            monitor.run_once()
            time.sleep(args.interval)
    except KeyboardInterrupt:
        logger.info("Остановлен пользователем")
    except Exception as e:
        logger.exception(f"Критическая ошибка: {e}")
        sys.exit(1)


if __name__ == "__main__":
    main()

Как использовать и интегрировать​

  • Запуск как демон:
    Через systemd — создаётся unit-файл, перезапускающий скрипт при падении.
  • Конфигурация:
    config.yaml хранится в репозитории, но без секретов. TELEGRAM_BOT_TOKEN и TELEGRAM_CHAT_ID подставляются из EnvironmentFile в systemd.
  • В CI/CD:
    Запуск в stage post-deploy для проверки доступности после деплоя (с --interval 5 --iterations 3 и выходом по коду).

3. Pre-commit хук для документации (doc_validator.py)​

Решает задачу: проверка корректности и согласованности технической документации перед коммитом.

#!/usr/bin/env python3
"""
Pre-commit хук для валидации технической документации.

Проверяет:
- Валидность Markdown (синтаксис, ссылки на несуществующие файлы)
- Наличие заголовка уровня 1 (H1) в начале файла
- Отсутствие жёстко заданных абсолютных путей
- Согласованность имён файлов и заголовков (например, file.md → # File)

Требования:
    pip install markdown-it-py mdformat
"""

import argparse
import re
import sys
from pathlib import Path

from markdown_it import MarkdownIt


def validate_markdown(file_path: Path) -> list[str]:
    """Возвращает список ошибок для файла."""
    errors = []
    content = file_path.read_text(encoding="utf-8")

    # Проверка H1 в начале
    lines = content.strip().splitlines()
    if not lines or not lines[0].startswith("# "):
        errors.append("Отсутствует заголовок H1 в первой строке")

    # Проверка абсолютных путей
    if re.search(r"\]\(/", content):  # [текст](/путь)
        errors.append("Обнаружены абсолютные пути в ссылках — используйте относительные")

    # Проверка валидности Markdown
    try:
        md = MarkdownIt("commonmark")
        tokens = md.parse(content)
        # Простая проверка: нет ли токенов с типом 'error'
        if any(t.type == "error" for t in tokens):
            errors.append("Некорректный Markdown-синтаксис")
    except Exception as e:
        errors.append(f"Ошибка парсинга Markdown: {e}")

    # Проверка согласованности имени файла и заголовка
    if lines and lines[0].startswith("# "):
        title = lines[0][2:].strip()
        expected_title = file_path.stem.replace("_", " ").replace("-", " ").title()
        if title.lower() != expected_title.lower():
            errors.append(f"Заголовок '{title}' не соответствует имени файла '{expected_title}'")

    return errors


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("files", nargs="*", help="Файлы для проверки")
    args = parser.parse_args()

    if not args.files:
        print("Нет файлов для проверки", file=sys.stderr)
        sys.exit(0)

    markdown_files = [f for f in args.files if f.endswith(".md")]
    all_errors = []

    for file in markdown_files:
        path = Path(file)
        if not path.exists():
            continue
        errors = validate_markdown(path)
        if errors:
            print(f"\n{file}:")
            for err in errors:
                print(f"  - {err}")
            all_errors.extend(errors)

    if all_errors:
        print(f"\n❌ Найдено ошибок: {len(all_errors)}", file=sys.stderr)
        sys.exit(1)
    else:
        print("✅ Документация валидна", file=sys.stderr)
        sys.exit(0)


if __name__ == "__main__":
    main()

Как интегрировать в pre-commit​

  1. Сохранить как .git/hooks/doc_validator.py (и сделать chmod +x);
  2. Или — лучше — через pre-commit фреймворк, добавив в .pre-commit-config.yaml: 
    - repo: local
      hooks:
        - id: doc-validator
          name: Validate documentation
          entry: python doc_validator.py
          language: system
          types: [markdown]