mpt-tool 5.0.0__py3-none-any.whl

mpt_tool/managers/state/airtable.py

@@ -0,0 +1,108 @@
+from typing import override
+
+from pyairtable.formulas import match
+from pyairtable.orm import Model, fields
+
+from mpt_tool.config import get_airtable_config
+from mpt_tool.enums import MigrationTypeEnum
+from mpt_tool.managers import StateManager
+from mpt_tool.managers.errors import StateNotFoundError
+from mpt_tool.models import Migration
+
+
+class MigrationStateModel(Model):
+    """Airtable model for migration states."""
+
+    migration_id = fields.RequiredTextField("migration_id")
+    order_id = fields.RequiredIntegerField("order_id")
+    type = fields.RequiredSelectField("type")
+    started_at = fields.DatetimeField("started_at")
+    applied_at = fields.DatetimeField("applied_at")
+
+    class Meta:
+        @staticmethod
+        def api_key() -> str | None:  # noqa: WPS602
+            """Airtable API key."""
+            return get_airtable_config("api_key")
+
+        @staticmethod
+        def base_id() -> str | None:  # noqa: WPS602
+            """Airtable base ID."""
+            return get_airtable_config("base_id")
+
+        @staticmethod
+        def table_name() -> str | None:  # noqa: WPS602
+            """Airtable table name."""
+            return get_airtable_config("table_name")
+
+
+class AirtableStateManager(StateManager):
+    """Manages migration states in Airtable."""
+
+    @override
+    @classmethod
+    def load(cls) -> dict[str, Migration]:
+        migrations = {}
+        for state in MigrationStateModel.all():
+            migration = Migration(
+                migration_id=state.migration_id,
+                order_id=state.order_id,
+                type=MigrationTypeEnum(state.type),
+                started_at=state.started_at,
+                applied_at=state.applied_at,
+            )
+            migrations[migration.migration_id] = migration
+
+        return migrations
+
+    @override
+    @classmethod
+    def get_by_id(cls, migration_id: str) -> Migration:
+        state = MigrationStateModel.first(formula=match({"migration_id": migration_id}))
+        if not state:
+            raise StateNotFoundError(f"State {migration_id} not found")
+
+        return Migration(
+            migration_id=state.migration_id,
+            order_id=state.order_id,
+            type=MigrationTypeEnum(state.type),
+            started_at=state.started_at,
+            applied_at=state.applied_at,
+        )
+
+    @override
+    @classmethod
+    def new(cls, migration_id: str, migration_type: MigrationTypeEnum, order_id: int) -> Migration:
+        state = MigrationStateModel(
+            migration_id=migration_id, order_id=order_id, type=migration_type.value
+        )
+        state.save()
+        return Migration(
+            migration_id=state.migration_id,
+            order_id=state.order_id,
+            type=MigrationTypeEnum(state.type),
+            started_at=state.started_at,
+            applied_at=state.applied_at,
+        )
+
+    @override
+    @classmethod
+    def save_state(cls, state: Migration) -> None:
+        migration_state_model = MigrationStateModel.first(
+            formula=f"migration_id = '{state.migration_id}'"
+        )
+        if migration_state_model:
+            migration_state_model.order_id = state.order_id
+            migration_state_model.type = state.type.value
+            migration_state_model.started_at = state.started_at
+            migration_state_model.applied_at = state.applied_at
+        else:
+            migration_state_model = MigrationStateModel(
+                migration_id=state.migration_id,
+                order_id=state.order_id,
+                type=state.type.value,
+                started_at=state.started_at,
+                applied_at=state.applied_at,
+            )
+
+        migration_state_model.save()

mpt_tool/managers/state/base.py

@@ -0,0 +1,49 @@
+from abc import ABC, abstractmethod
+
+from mpt_tool.enums import MigrationTypeEnum
+from mpt_tool.models import Migration
+
+
+class StateManager(ABC):
+    """Base class for state managers."""
+
+    @classmethod
+    @abstractmethod
+    def load(cls) -> dict[str, Migration]:
+        """Load migration states."""
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def get_by_id(cls, migration_id: str) -> Migration:
+        """Get a migration state by its ID.
+
+        Args:
+            migration_id: The migration ID.
+
+        Raises:
+            StateNotFoundError: If the state is not found.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def new(cls, migration_id: str, migration_type: MigrationTypeEnum, order_id: int) -> Migration:
+        """Create a new migration state.
+
+        Args:
+            migration_id: The migration ID.
+            migration_type: The migration type.
+            order_id: The order ID.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def save_state(cls, state: Migration) -> None:
+        """Save a migration state to the state file.
+
+        Args:
+            state: The migration state.
+        """
+        raise NotImplementedError

mpt_tool/managers/state/factory.py

@@ -0,0 +1,32 @@
+from enum import StrEnum
+
+from mpt_tool.config import get_storage_type
+from mpt_tool.managers import StateManager
+from mpt_tool.managers.state.airtable import AirtableStateManager
+from mpt_tool.managers.state.file import FileStateManager
+
+
+class StorageTypeEnum(StrEnum):
+    """Enum for storage types."""
+
+    LOCAL = "local"
+    AIRTABLE = "airtable"
+
+
+class StateManagerFactory:
+    """Factory to create StateManager instances."""
+
+    @classmethod
+    def get_instance(cls) -> StateManager:
+        """Return a StateManager instance based on environment variables.
+
+        Returns:
+            StateManager instance (FileStateManager or AirtableStateManager)
+
+        """
+        storage_type = get_storage_type()
+        return (
+            AirtableStateManager()
+            if storage_type == StorageTypeEnum.AIRTABLE
+            else FileStateManager()
+        )

mpt_tool/managers/state/file.py

@@ -0,0 +1,64 @@
+import json
+from pathlib import Path
+from typing import override
+
+from mpt_tool.constants import MIGRATION_STATE_FILE
+from mpt_tool.enums import MigrationTypeEnum
+from mpt_tool.managers import StateManager
+from mpt_tool.managers.encoders import StateJSONEncoder
+from mpt_tool.managers.errors import InvalidStateError, StateNotFoundError
+from mpt_tool.models import Migration
+
+
+class FileStateManager(StateManager):
+    """Manages file migration states."""
+
+    _state_path: Path = Path(MIGRATION_STATE_FILE)
+
+    @override
+    @classmethod
+    def load(cls) -> dict[str, Migration]:
+        if not cls._state_path.exists():
+            return {}
+
+        try:
+            state_data = json.loads(cls._state_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as error:
+            raise InvalidStateError(f"Invalid state file: {error!s}") from error
+
+        return {key: Migration.from_dict(mig_data) for key, mig_data in state_data.items()}
+
+    @override
+    @classmethod
+    def get_by_id(cls, migration_id: str) -> Migration:
+        state_data = cls.load()
+        try:
+            state = state_data[migration_id]
+        except KeyError:
+            raise StateNotFoundError("State not found") from None
+
+        return state
+
+    @override
+    @classmethod
+    def new(cls, migration_id: str, migration_type: MigrationTypeEnum, order_id: int) -> Migration:
+        new_state = Migration(
+            migration_id=migration_id,
+            order_id=order_id,
+            type=migration_type,
+        )
+        cls.save_state(new_state)
+        return new_state
+
+    @override
+    @classmethod
+    def save_state(cls, state: Migration) -> None:
+        state_data = cls.load()
+        state_data[state.migration_id] = state
+        cls._save(state_data)
+
+    @classmethod
+    def _save(cls, state_data: dict[str, Migration]) -> None:
+        cls._state_path.write_text(
+            json.dumps(state_data, indent=2, cls=StateJSONEncoder), encoding="utf-8"
+        )

mpt_tool/migration/__init__.py

@@ -0,0 +1,4 @@
+from mpt_tool.migration.data_base import DataBaseMigration
+from mpt_tool.migration.schema_base import SchemaBaseMigration
+
+__all__ = ["DataBaseMigration", "SchemaBaseMigration"]

mpt_tool/migration/base.py

@@ -0,0 +1,25 @@
+import logging
+from abc import ABC, abstractmethod
+
+from mpt_tool.enums import MigrationTypeEnum
+
+logger = logging.getLogger(__name__)
+
+
+class BaseMigration(ABC):
+    """Abstract base class for all migration commands."""
+
+    _type: MigrationTypeEnum
+
+    def __init__(self) -> None:
+        self.log = logger
+
+    @property
+    def type(self) -> MigrationTypeEnum:
+        """The type of migration this command represents."""
+        return self._type
+
+    @abstractmethod
+    def run(self) -> None:
+        """Executes the command."""
+        raise NotImplementedError

mpt_tool/migration/data_base.py

@@ -0,0 +1,10 @@
+from abc import ABC
+
+from mpt_tool.enums import MigrationTypeEnum
+from mpt_tool.migration.base import BaseMigration
+
+
+class DataBaseMigration(BaseMigration, ABC):
+    """Base command for data migrations."""
+
+    _type = MigrationTypeEnum.DATA

mpt_tool/migration/mixins/__init__.py

@@ -0,0 +1,4 @@
+from mpt_tool.migration.mixins.airtable_client import AirtableAPIClientMixin
+from mpt_tool.migration.mixins.mpt_client import MPTAPIClientMixin
+
+__all__ = ["AirtableAPIClientMixin", "MPTAPIClientMixin"]

mpt_tool/migration/mixins/airtable_client.py

@@ -0,0 +1,29 @@
+from functools import cached_property
+
+from pyairtable import Api as AirtableClient
+
+from mpt_tool.config import get_airtable_config
+
+
+class AirtableAPIClientMixin:
+    """Mixin to add Airtable API client to commands.
+
+    The API key is read from the environment variable AIRTABLE_API_KEY.
+    """
+
+    @cached_property
+    def airtable_client(self) -> AirtableClient:
+        """Get or create Airtable Client.
+
+        Returns:
+            The Airtable Client instance
+
+        Raises:
+            ValueError: If required environment variables are not set
+
+        """
+        airtable_api_key = get_airtable_config("api_key")
+        if not airtable_api_key:
+            raise ValueError("Airtable API key must be set in env variable AIRTABLE_API_KEY")
+
+        return AirtableClient(airtable_api_key)

mpt_tool/migration/mixins/mpt_client.py

@@ -0,0 +1,31 @@
+from functools import cached_property
+
+from mpt_api_client import MPTClient
+
+from mpt_tool.config import get_mpt_config
+
+
+class MPTAPIClientMixin:
+    """Mixin to add MPT API client to commands.
+
+    MPT API token and base URL are read from the environment variables MPT_API_TOKEN
+    and MPT_API_BASE_URL.
+    """
+
+    @cached_property
+    def mpt_client(self) -> MPTClient:
+        """Get or create MPT API client from environment configurations.
+
+        Returns:
+            The MPT API client instance
+
+        Raises:
+            ValueError: If required environment variables are not set
+
+        """
+        api_token = get_mpt_config("api_token")
+        base_url = get_mpt_config("base_url")
+        if not api_token or not base_url:
+            raise ValueError("MPT API token and base URL must be set in env variables")
+
+        return MPTClient.from_config(api_token=api_token, base_url=base_url)

mpt_tool/migration/schema_base.py

@@ -0,0 +1,10 @@
+from abc import ABC
+
+from mpt_tool.enums import MigrationTypeEnum
+from mpt_tool.migration.base import BaseMigration
+
+
+class SchemaBaseMigration(BaseMigration, ABC):
+    """Base command for schema migrations."""
+
+    _type = MigrationTypeEnum.SCHEMA

mpt_tool/models.py

@@ -0,0 +1,140 @@
+import datetime as dt
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Self
+
+from mpt_tool.constants import MAX_LEN_MIGRATION_ID
+from mpt_tool.enums import MigrationStatusEnum, MigrationTypeEnum
+
+
+@dataclass
+class Migration:
+    """Represents a migration."""
+
+    migration_id: str
+    order_id: int
+    type: MigrationTypeEnum
+    started_at: dt.datetime | None = None
+    applied_at: dt.datetime | None = None
+
+    @classmethod
+    def from_dict(cls, migration_data: dict[str, Any]) -> Self:
+        """Create a migration from a dictionary."""
+        return cls(
+            migration_id=migration_data["migration_id"],
+            order_id=migration_data["order_id"],
+            type=MigrationTypeEnum(migration_data["type"]),
+            started_at=dt.datetime.fromisoformat(migration_data["started_at"])
+            if migration_data["started_at"]
+            else None,
+            applied_at=dt.datetime.fromisoformat(migration_data["applied_at"])
+            if migration_data["applied_at"]
+            else None,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert a migration to a dictionary."""
+        return {
+            "migration_id": self.migration_id,
+            "order_id": self.order_id,
+            "type": self.type.value,
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "applied_at": self.applied_at.isoformat() if self.applied_at else None,
+        }
+
+    def applied(self) -> None:
+        """Mark the migration as applied."""
+        self.applied_at = dt.datetime.now(tz=dt.UTC)
+
+    def failed(self) -> None:
+        """Mark the migration as failed."""
+        self.started_at = None
+        self.applied_at = None
+
+    def fake(self) -> None:
+        """Mark the migration as fake."""
+        self.started_at = None
+        self.applied_at = dt.datetime.now(tz=dt.UTC)
+
+    def start(self) -> None:
+        """Mark the migration as started."""
+        self.started_at = dt.datetime.now(tz=dt.UTC)
+
+
+@dataclass
+class MigrationFile:
+    """Represents a migration file with its identifier and order."""
+
+    full_path: Path
+    migration_id: str
+    order_id: int
+
+    @property
+    def file_name(self) -> str:
+        """Migration file name."""
+        return f"{self.order_id}_{self.migration_id}.py"
+
+    def __post_init__(self) -> None:
+        if len(self.migration_id) >= MAX_LEN_MIGRATION_ID:
+            raise ValueError(
+                f"Migration ID must be less than {MAX_LEN_MIGRATION_ID} characters long."
+            )
+        if not self.migration_id.isidentifier():
+            raise ValueError(
+                "Migration ID must contain only alphanumeric letters and numbers, or underscores."
+            )
+
+    @property
+    def name(self) -> str:
+        """Migration file name."""
+        return f"{self.order_id}_{self.migration_id}"
+
+    @classmethod
+    def build_from_path(cls, path: Path) -> Self:
+        """Build a migration file from a path.
+
+        Args:
+            path: The path to the migration file.
+        """
+        order_id, migration_id = path.stem.split("_", maxsplit=1)
+        return cls(full_path=path, order_id=int(order_id), migration_id=migration_id)
+
+    @classmethod
+    def new(cls, migration_id: str, path: Path) -> Self:
+        """Create a new migration file.
+
+        Args:
+            migration_id: The migration ID.
+            path: The path to the migration folder.
+        """
+        timestamp = dt.datetime.now(tz=dt.UTC).strftime("%Y%m%d%H%M%S")
+        full_path = path / f"{timestamp}_{migration_id}.py"
+        return cls(full_path=full_path, migration_id=migration_id, order_id=int(timestamp))
+
+
+@dataclass(frozen=True)
+class MigrationListItem:
+    """Represents the data required to render a migration entry."""
+
+    migration_id: str
+    order_id: int
+    migration_type: MigrationTypeEnum | None
+    started_at: dt.datetime | None
+    applied_at: dt.datetime | None
+    status: MigrationStatusEnum
+
+    @classmethod
+    def from_sources(
+        cls,
+        migration_file: MigrationFile,
+        migration_state: Migration | None,
+    ) -> Self:
+        """Create a migration list item from file metadata and stored state."""
+        return cls(
+            migration_id=migration_file.migration_id,
+            order_id=migration_file.order_id,
+            migration_type=migration_state.type if migration_state else None,
+            started_at=migration_state.started_at if migration_state else None,
+            applied_at=migration_state.applied_at if migration_state else None,
+            status=MigrationStatusEnum.from_state(migration_state),
+        )

mpt_tool/renders.py

@@ -0,0 +1,30 @@
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.table import Table
+
+from mpt_tool.models import MigrationListItem
+
+
+class MigrationRender:
+    """Render migration state information as a formatted table."""
+
+    _fields = ("order_id", "migration_id", "started_at", "applied_at", "type", "status")
+
+    def __init__(self, migration_items: list[MigrationListItem]):
+        self.migration_items = migration_items
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:  # noqa: PLW3201
+        table = Table(show_lines=True, title_justify="center")
+        for field in self._fields:
+            table.add_column(field, no_wrap=True, min_width=len(field))
+
+        for migration in self.migration_items:
+            table.add_row(
+                str(migration.order_id),
+                migration.migration_id,
+                migration.started_at.isoformat(timespec="seconds") if migration.started_at else "-",
+                migration.applied_at.isoformat(timespec="seconds") if migration.applied_at else "-",
+                migration.migration_type.value if migration.migration_type else "-",
+                migration.status.title(),
+            )
+
+        yield table

mpt_tool/templates.py

@@ -0,0 +1,12 @@
+from string import Template
+
+MIGRATION_SCAFFOLDING_FILE_TEXT = """\
+from mpt_tool.migration import $migration_name
+
+
+class Migration($migration_name):
+    def run(self):
+        # implement your logic here
+        pass
+"""
+MIGRATION_SCAFFOLDING_TEMPLATE: Template = Template(MIGRATION_SCAFFOLDING_FILE_TEXT)

mpt_tool/use_cases/__init__.py

@@ -0,0 +1,11 @@
+from mpt_tool.use_cases.apply_migration import ApplyMigrationUseCase
+from mpt_tool.use_cases.list_migrations import ListMigrationsUseCase
+from mpt_tool.use_cases.new_migration import NewMigrationUseCase
+from mpt_tool.use_cases.run_migrations import RunMigrationsUseCase
+
+__all__ = [
+    "ApplyMigrationUseCase",
+    "ListMigrationsUseCase",
+    "NewMigrationUseCase",
+    "RunMigrationsUseCase",
+]

mpt_tool/use_cases/apply_migration.py

@@ -0,0 +1,42 @@
+from mpt_tool.managers import FileMigrationManager, StateManager, StateManagerFactory
+from mpt_tool.managers.errors import MigrationFolderError, StateNotFoundError
+from mpt_tool.use_cases.errors import ApplyMigrationError
+
+
+class ApplyMigrationUseCase:
+    """Use case for applying a migration without running it."""
+
+    def __init__(
+        self,
+        file_migration_manager: FileMigrationManager | None = None,
+        state_manager: StateManager | None = None,
+    ):
+        self.file_migration_manager = file_migration_manager or FileMigrationManager()
+        self.state_manager = state_manager or StateManagerFactory.get_instance()
+
+    def execute(self, migration_id: str) -> None:
+        """Apply a migration without running it."""
+        try:
+            migration_files = self.file_migration_manager.validate()
+        except MigrationFolderError as error:
+            raise ApplyMigrationError(str(error)) from error
+
+        migration_file = next(
+            (migration for migration in migration_files if migration.migration_id == migration_id),
+            None,
+        )
+        if not migration_file:
+            raise ApplyMigrationError(f"Migration {migration_id} not found")
+
+        try:
+            state = self.state_manager.get_by_id(migration_id)
+        except StateNotFoundError:
+            # TODO: handle LoadMigrationError exception
+            migration = self.file_migration_manager.load_migration(migration_file)
+            state = self.state_manager.new(migration_id, migration.type, migration_file.order_id)
+
+        if state.applied_at is not None:
+            raise ApplyMigrationError(f"Migration {migration_id} already applied")
+
+        state.fake()
+        self.state_manager.save_state(state)

mpt_tool/use_cases/errors.py

@@ -0,0 +1,17 @@
+from mpt_tool.errors import BaseError
+
+
+class UseCaseError(BaseError):
+    """Base error for use cases."""
+
+
+class NewMigrationError(UseCaseError):
+    """Error creating new migration."""
+
+
+class RunMigrationError(UseCaseError):
+    """Error running migration."""
+
+
+class ApplyMigrationError(UseCaseError):
+    """Error applying migration."""

mpt_tool/use_cases/list_migrations.py

@@ -0,0 +1,35 @@
+import logging
+
+from mpt_tool.managers import FileMigrationManager, StateManager, StateManagerFactory
+from mpt_tool.models import MigrationListItem
+
+logger = logging.getLogger(__name__)
+
+
+class ListMigrationsUseCase:
+    """Use case for listing all migrations."""
+
+    def __init__(
+        self,
+        file_migration_manager: FileMigrationManager | None = None,
+        state_manager: StateManager | None = None,
+    ):
+        self.file_migration_manager = file_migration_manager or FileMigrationManager()
+        self.state_manager = state_manager or StateManagerFactory.get_instance()
+
+    def execute(self) -> list[MigrationListItem]:
+        """List all migrations sorted by order identifier."""
+        migration_files = self.file_migration_manager.retrieve_migration_files()
+        migration_states = self.state_manager.load()
+        migration_list: list[MigrationListItem] = []
+        for migration_file in migration_files:
+            migration_state = migration_states.get(migration_file.migration_id)
+            if not migration_state:
+                logger.debug("No state found for migration: %s", migration_file.migration_id)
+            migration_list.append(
+                MigrationListItem.from_sources(
+                    migration_file=migration_file, migration_state=migration_state
+                )
+            )
+
+        return sorted(migration_list, key=lambda migration: migration.order_id)