gadem

migrate.py

@@ -1,5 +1,9 @@
 from __future__ import annotations
 
+"""
+Утилита для запуска файлов миграций из папки migrations и фиксации состояния применённых шагов.
+"""
+
 import argparse
 import importlib.util
 import json
@@ -36,6 +40,7 @@ class Migration:
 
 
 def load_state(path: Path) -> Dict:
+    # Достаём список уже применённых миграций, чтобы не выполнять их повторно
     if not path.exists():
         return {"applied": []}
     with path.open("r", encoding="utf-8") as f:
@@ -43,12 +48,14 @@ def load_state(path: Path) -> Dict:
 
 
 def save_state(path: Path, state: Dict) -> None:
+    # Создаём файл состояния на диске после успешной миграции
     path.parent.mkdir(parents=True, exist_ok=True)
     with path.open("w", encoding="utf-8") as f:
         json.dump(state, f, ensure_ascii=True, indent=2)
 
 
 def discover_migrations(root: Path) -> List[Migration]:
+    # Подгружаем все *.py в каталоге миграций и ищем в них функцию run/apply
     migrations: List[Migration] = []
     for module_path in sorted(root.glob("*.py")):
         if module_path.name.startswith("_") or module_path.name == "__init__.py":
@@ -73,6 +80,7 @@ def discover_migrations(root: Path) -> List[Migration]:
 
 
 def record_applied(state: Dict, migration: Migration) -> None:
+    # Обновляем состояние, фиксируя идентификатор и имя файла миграции
     applied = [entry for entry in state.get("applied", []) if entry.get("id") != migration.migration_id]
     applied.append(
         {