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

HSM: Python Workflow Deep Dive

Этот документ детально описывает, как hsm управляет Python-окружением, и почему это эффективнее традиционных подходов (Git Submodules, Monorepos).

1. Проблема: Dependency Hell в модульных системах​

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

  • Monorepo: Всё в одном месте, легко дебажить, но репозиторий становится огромным и неповоротливым.
  • Polyrepo + Submodules: Код разделен, но Submodules — это "боль" (жесткая привязка коммитов, сложности с обновлением, рекурсивное клонирование).
  • PyPI/Private Registry: Чисто, но невозможно править код плагина "на лету" без постоянных релизов.

2. Решение HSM: Динамическая композиция​

HSM реализует концепцию Environment Hypervisor. Он позволяет работать с независимыми репозиториями плагинов так, будто это часть монорепозитория, но без его недостатков.

Преимущества HSM для Python:​

  • Self-Bootstrapping Sandbox: Команда hsm package init позволяет мгновенно создавать новые пакеты с правильной структурой и регистрацией.
  • No Hard Links: В основном репозитории нет ссылок на код плагинов. Только hsm.yaml с именами и версиями.
  • On-Demand Cloning: Вы клонируете только те плагины, которые нужны вам для текущей задачи разработки и тестирования.
  • Atomic Reconcile: HSM сначала проверяет совместимость всех компонентов в памяти, и только потом обновляет pyproject.toml.

3. Детальный процесс (Step-by-Step)​

А. Режим Разработки (Dev)​

Когда вы переводите пакет в dev режим:

  1. Cloning: HSM проверяет наличие папки (например, packages/my-plugin). Если её нет — предлагает склонировать.
  2. Mapping: HSM находит путь к исходникам.
  3. Atomic Injection: HSM подготавливает изменения для pyproject.toml.
  4. Sync: Вы запускаете hsm sync. HSM внутри себя вызывает uv sync (или другой адаптер).
    • Важно: Если uv sync завершится с ошибкой (например, из-за конфликта зависимостей), HSM откатит изменения, и ваш pyproject.toml останется в исходном, рабочем состоянии.

Результат: Вы меняете код в packages/my-plugin, и основное приложение мгновенно видит изменения.

Б. Режим Продакшена (Prod)​

При переключении в prod:

  1. Resolution: HSM берет зафиксированную версию (тег/коммит) из манифеста.
  2. Injection: В pyproject.toml прописывается прямая ссылка на Git: my-plugin = { git = "https://github.com/org/my-plugin", tag = "v1.2.0" }
  3. Sync: hsm sync (вызывающий uv sync) скачивает пакет и устанавливает его как неизменяемую библиотеку.

4. Сравнение с Git Submodules​

ХарактеристикаGit SubmodulesHSM Workflow
СвязностьЖесткая (на уровне коммитов)Декларативная (на уровне версий/режимов)
Клонирование (dev)Всегда всё (или сложные флаги)Только те репо пакетов, что нужны сейчас
Клонирование (prod)Всегда всё (или сложные флаги)Только готовые пакеты (без клонирования репо)
РазработкаСложно коммитить и пушитьОбычный git workflow в папке пакета
CI/CDТребует настройки submodulesОдин hsm sync

5. Итог​

HSM делает разработку модульных систем приятной (DX). Вы фокусируетесь на коде, а HSM берет на себя всю работу по связыванию путей и управлению зависимостями.