pum 1.0.0__py3-none-any.whl

pum/exceptions.py

@@ -0,0 +1,47 @@
+# Base exception for all PUM errors
+class PumException(Exception):
+    """Base class for all exceptions raised by PUM."""
+
+
+# --- Configuration and Validation Errors ---
+
+
+class PumConfigError(PumException):
+    """Exception raised for errors in the PUM configuration."""
+
+
+class PumInvalidChangelog(PumException):
+    """Exception raised for invalid changelog."""
+
+
+# --- Hook Errors ---
+
+
+class PumHookError(PumException):
+    """Exception raised for errors by an invalid hook."""
+
+
+# --- Changelog/SQL Errors ---
+
+
+class PumSqlError(PumException):
+    """Exception raised for SQL-related errors in PUM."""
+
+
+# --- Dump/Restore Errors (for dumper.py, if needed) ---
+
+
+class PgDumpCommandError(PumException):
+    """Exception raised for invalid pg_dump command."""
+
+
+class PgDumpFailed(PumException):
+    """Exception raised when pg_dump fails."""
+
+
+class PgRestoreCommandError(PumException):
+    """Exception raised for invalid pg_restore command."""
+
+
+class PgRestoreFailed(PumException):
+    """Exception raised when pg_restore fails."""

pum/hook.py

@@ -0,0 +1,231 @@
+import importlib.util
+import inspect
+import logging
+import sys
+import psycopg
+import copy
+
+from pathlib import Path
+
+from .exceptions import PumHookError, PumSqlError
+from .sql_content import SqlContent
+import abc
+
+logger = logging.getLogger(__name__)
+
+
+class HookBase(abc.ABC):
+    """Base class for Python migration hooks.
+    This class defines the interface for migration hooks that can be implemented in Python.
+    It requires the implementation of the `run_hook` method, which will be called during the migration process.
+    It can call the execute method to run SQL statements with the provided connection and parameters.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the HookBase class."""
+        self._parameters: dict | None = None
+
+    def _prepare(self, connection: psycopg.Connection, parameters: dict | None = None) -> None:
+        """Prepare the hook with the given connection and parameters.
+        Args:
+            connection: The database connection.
+            parameters: Parameters to bind to the SQL statement. Defaults to None.
+        Note:
+            Parameters are stored as a deep copy, any modification will not be used when calling execute.
+        """
+        self._connection = connection
+        self._parameters = copy.deepcopy(parameters)
+
+    @abc.abstractmethod
+    def run_hook(self, connection: psycopg.Connection, parameters: dict | None = None) -> None:
+        """Run the migration hook.
+        Args:
+            connection: The database connection.
+            parameters: Parameters to bind to the SQL statement. Defaults to None.
+
+        Note:
+            Parameters are given as a deep copy, any modification will not be used when calling execute.
+        """
+        raise NotImplementedError("The run_hook method must be implemented in the subclass.")
+
+    def execute(
+        self,
+        sql: str | psycopg.sql.SQL | Path,
+    ) -> None:
+        """Execute the migration hook with the provided SQL and parameters for the migration.
+        This is not committing the transaction and will be handled afterwards.
+
+        Args:
+            connection: The database connection.
+            sql: The SQL statement to execute or a path to a SQL file..
+        """
+        SqlContent(sql).execute(
+            connection=self._connection, parameters=self._parameters, commit=False
+        )
+
+    execute.__isfinal__ = True
+
+
+class HookHandler:
+    """Handler for migration hooks.
+    This class manages the execution of migration hooks, which can be either SQL files or Python functions."""
+
+    def __init__(
+        self,
+        *,
+        file: str | Path | None = None,
+        code: str | None = None,
+        base_path: Path | None = None,
+    ) -> None:
+        """Initialize a Hook instance.
+
+        Args:
+            type: The type of the hook (e.g., "pre", "post").
+            file: The file path of the hook.
+            code: The SQL code for the hook.
+
+        """
+        if file and code:
+            raise ValueError("Cannot specify both file and code. Choose one.")
+
+        self.file = file
+        self.code = code
+        self.hook_instance = None
+
+        if file:
+            if isinstance(file, str):
+                self.file = Path(file)
+            if not self.file.is_absolute():
+                if base_path is None:
+                    raise ValueError("Base path must be provided for relative file paths.")
+                self.file = base_path.absolute() / self.file
+            if not self.file.exists():
+                raise PumHookError(f"Hook file {self.file} does not exist.")
+            if not self.file.is_file():
+                raise PumHookError(f"Hook file {self.file} is not a file.")
+
+        if self.file and self.file.suffix == ".py":
+            # Support local imports in hook files by adding parent dir to sys.path
+            parent_dir = str(self.file.parent.resolve())
+            sys_path_modified = False
+            if parent_dir not in sys.path:
+                sys.path.insert(0, parent_dir)
+                sys_path_modified = True
+            try:
+                spec = importlib.util.spec_from_file_location(self.file.stem, self.file)
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+            finally:
+                if sys_path_modified:
+                    sys.path.remove(parent_dir)
+            # Check that the module contains a class named Hook inheriting from HookBase
+            hook_class = getattr(module, "Hook", None)
+            if not hook_class or not inspect.isclass(hook_class):
+                raise PumHookError(
+                    f"Python hook file {self.file} must define a class named 'Hook'."
+                )
+            if not issubclass(hook_class, HookBase):
+                raise PumHookError(f"Class 'Hook' in {self.file} must inherit from HookBase.")
+            if not hasattr(hook_class, "run_hook"):
+                raise PumHookError(f"Hook function 'run_hook' not found in {self.file}.")
+
+            self.hook_instance = hook_class()
+            arg_names = list(inspect.signature(hook_class.run_hook).parameters.keys())
+            if "connection" not in arg_names:
+                raise PumHookError(
+                    f"Hook function 'run_hook' in {self.file} must accept 'connection' as an argument."
+                )
+            self.parameter_args = [arg for arg in arg_names if arg not in ("self", "connection")]
+
+    def __repr__(self) -> str:
+        """Return a string representation of the Hook instance."""
+        return f"<hook: {self.file}>"
+
+    def __eq__(self, other: "HookHandler") -> bool:
+        """Check if two Hook instances are equal."""
+        if not isinstance(other, HookHandler):
+            return NotImplemented
+        return (not self.file or self.file == other.file) and (
+            not self.code or self.code == other.code
+        )
+
+    def validate(self, parameters: dict) -> None:
+        """Check if the parameters match the expected parameter definitions.
+        This is only effective for Python hooks for now.
+
+        Args:
+            parameters (dict): The parameters to check.
+
+        Raises:
+            PumHookError: If the parameters do not match the expected definitions.
+
+        """
+        if self.file and self.file.suffix == ".py":
+            for parameter_arg in self.parameter_args:
+                if parameter_arg not in parameters:
+                    raise PumHookError(
+                        f"Hook function 'run_hook' in {self.file} has an unexpected argument "
+                        f"'{parameter_arg}' which is not specified in the parameters."
+                    )
+
+        if self.file and self.file.suffix == ".sql":
+            SqlContent(self.file).validate(parameters=parameters)
+
+    def execute(
+        self,
+        connection: psycopg.Connection,
+        *,
+        commit: bool = False,
+        parameters: dict | None = None,
+    ) -> None:
+        """Execute the migration hook.
+        This method executes the SQL code or the Python file specified in the hook.
+
+        Args:
+            connection: The database connection.
+            commit: Whether to commit the transaction after executing the SQL.
+            parameters (dict, optional): Parameters to bind to the SQL statement. Defaults to ().
+
+        """
+        logger.info(
+            f"Executing hook from file: {self.file} or SQL code with parameters: {parameters}",
+        )
+
+        if self.file is None and self.code is None:
+            raise ValueError("No file or SQL code specified for the migration hook.")
+
+        if self.file:
+            if self.file.suffix == ".sql":
+                SqlContent(self.file).execute(
+                    connection=connection, commit=False, parameters=parameters
+                )
+            elif self.file.suffix == ".py":
+                for parameter_arg in self.parameter_args:
+                    if not parameters or parameter_arg not in self.parameter_args:
+                        raise PumHookError(
+                            f"Hook function 'run_hook' in {self.file} has an unexpected "
+                            f"argument '{parameter_arg}' which is not specified in the parameters."
+                        )
+
+                _hook_parameters = {}
+                for key, value in parameters.items():
+                    if key in self.parameter_args:
+                        _hook_parameters[key] = value
+                self.hook_instance._prepare(connection=connection, parameters=parameters)
+                try:
+                    if _hook_parameters:
+                        self.hook_instance.run_hook(connection=connection, **_hook_parameters)
+                    else:
+                        self.hook_instance.run_hook(connection=connection)
+                except PumSqlError as e:
+                    raise PumHookError(f"Error executing Python hook from {self.file}: {e}") from e
+
+            else:
+                raise PumHookError(
+                    f"Unsupported file type for migration hook: {self.file.suffix}. Only .sql and .py files are supported."
+                )
+        elif self.code:
+            SqlContent(self.code).execute(connection, parameters=parameters, commit=False)
+
+        if commit:
+            connection.commit()

pum/info.py

@@ -0,0 +1,30 @@
+import logging
+import sys
+import psycopg
+
+from .pum_config import PumConfig
+from .schema_migrations import SchemaMigrations
+
+logger = logging.getLogger(__name__)
+
+
+def run_info(connection: psycopg.Connection, config: PumConfig) -> None:
+    """Print info about the schema migrations.
+
+    Args:
+        connection: The database connection to use for checking migrations.
+        config: An instance of the PumConfig class containing configuration settings for the PUM system.
+
+    """
+    try:
+        schema_migrations = SchemaMigrations(connection, config)
+        if not schema_migrations.exists():
+            logger.info(
+                f"No migrations found in {config.pum.migration_table_schema}.{config.pum.migration_table_name}."
+            )
+        else:
+            # Add your logic for when migrations exist; for now, we simply print a message.
+            logger.info("Migrations found.")
+    except Exception:
+        logger.exception("An error occurred while checking for migrations.")
+        sys.exit(1)

pum/parameter.py

@@ -0,0 +1,72 @@
+from enum import Enum
+import psycopg
+
+
+class ParameterType(Enum):
+    """An enumeration of parameter types.
+    This class defines the types of parameters that can be used in migration definitions.
+
+    Attributes:
+        BOOLEAN (str): Represents a boolean parameter type.
+        INTEGER (str): Represents an integer parameter type.
+        TEXT (str): Represents a text parameter type.
+        DECIMAL (str): Represents a decimal parameter type.
+
+    """
+
+    BOOLEAN = "boolean"
+    INTEGER = "integer"
+    TEXT = "text"
+    DECIMAL = "decimal"
+
+
+class ParameterDefinition:
+    """A class to define a migration parameter."""
+
+    def __init__(
+        self,
+        name: str,
+        type: str | ParameterType,
+        default: str | float | int | None = None,
+        description: str | None = None,
+    ) -> None:
+        """Initialize a ParameterDefintion instance.
+
+        Args:
+            name: The name of the parameter.
+            type: The type of the parameter, as a string or ParameterType.
+            default: The default value for the parameter. Defaults to None.
+            description: A description of the parameter. Defaults to None.
+
+        Raises:
+            ValueError: If type is a string and not a valid ParameterType.
+            TypeError: If type is not a string or ParameterType.
+
+        """
+        self.name = name
+        if isinstance(type, ParameterType):
+            self.type = type
+        elif isinstance(type, str):
+            try:
+                self.type = ParameterType(type)
+            except ValueError:
+                raise ValueError(f"Parameter '{name}' has an invalid type: {type}. ") from None
+        else:
+            raise TypeError("type must be a str or ParameterType")
+        self.default = psycopg.sql.Literal(default)
+        self.description = description
+
+    def __repr__(self) -> str:
+        """Return a string representation of the ParameterDefinition instance."""
+        return f"Parameter({self.name}, type: {self.type}, default: {self.default})"
+
+    def __eq__(self, other: "ParameterDefinition") -> bool:
+        """Check if two ParameterDefinition instances are equal."""
+        if not isinstance(other, ParameterDefinition):
+            return NotImplemented
+        return (
+            self.name == other.name
+            and self.type == other.type
+            and self.default == other.default
+            and self.description == other.description
+        )

pum/pum_config.py

@@ -0,0 +1,231 @@
+from pathlib import Path
+import psycopg
+import yaml
+import packaging
+from pydantic import ValidationError
+import logging
+import importlib.metadata
+
+
+from .changelog import Changelog
+from .exceptions import PumConfigError, PumException, PumHookError, PumInvalidChangelog, PumSqlError
+from .parameter import ParameterDefinition
+from .role_manager import RoleManager
+from .config_model import ConfigModel
+from .hook import HookHandler
+
+
+try:
+    PUM_VERSION = packaging.version.Version(importlib.metadata.version("pum"))
+except importlib.metadata.PackageNotFoundError:
+    PUM_VERSION = packaging.version.Version("0.0.0")
+
+
+logger = logging.getLogger(__name__)
+
+
+class PumConfig:
+    """A class to hold configuration settings."""
+
+    def __init__(self, base_path: str | Path, validate: bool = True, **kwargs: dict) -> None:
+        """Initialize the configuration with key-value pairs.
+
+        Args:
+            base_path: The directory where the changelogs are located.
+            validate: Whether to validate the changelogs and hooks.
+            **kwargs: Key-value pairs representing configuration settings.
+
+        Raises:
+            PumConfigError: If the configuration is invalid.
+
+        """
+
+        if not isinstance(base_path, Path):
+            base_path = Path(base_path)
+        if not base_path.is_dir():
+            raise PumConfigError(f"Directory `{base_path}` does not exist.")
+        self._base_path = base_path
+
+        try:
+            self.config = ConfigModel(**kwargs)
+        except ValidationError as e:
+            logger.error("Config validation error: %s", e)
+            raise PumConfigError(e) from e
+
+        if validate:
+            if self.config.pum.minimum_version and PUM_VERSION < self.config.pum.minimum_version:
+                raise PumConfigError(
+                    f"Minimum required version of pum is {self.config.pum.minimum_version}, but the current version is {PUM_VERSION}. Please upgrade pum."
+                )
+            try:
+                self.validate()
+            except (PumInvalidChangelog, PumHookError) as e:
+                raise PumConfigError(
+                    f"Configuration is invalid: {e}. You can disable the validation when constructing the config."
+                ) from e
+
+    @classmethod
+    def from_yaml(cls, file_path: str | Path, *, validate: bool = True) -> "PumConfig":
+        """Create a PumConfig instance from a YAML file.
+
+        Args:
+            file_path: The path to the YAML file.
+            validate: Whether to validate the changelogs and hooks.
+
+        Returns:
+            PumConfig: An instance of the PumConfig class.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            yaml.YAMLError: If there is an error parsing the YAML file.
+
+        """
+        with Path.open(file_path) as file:
+            data = yaml.safe_load(file)
+
+        if "base_path" in data:
+            raise PumConfigError("base_path not allowed in configuration instead.")
+
+        base_path = Path(file_path).parent
+        return cls(base_path=base_path, validate=validate, **data)
+
+    @property
+    def base_path(self) -> Path:
+        """Return the base path used for configuration and changelogs."""
+        return self._base_path
+
+    def parameter(self, name: str) -> ParameterDefinition:
+        """Get a specific migration parameter by name.
+
+        Args:
+            name: The name of the parameter.
+
+        Returns:
+            ParameterDefintion: The migration parameter definition.
+
+        Raises:
+            PumConfigError: If the parameter name does not exist.
+
+        """
+        for parameter in self.config.parameters:
+            if parameter.name == name:
+                return ParameterDefinition(**parameter.model_dump())
+        raise PumConfigError(f"Parameter '{name}' not found in configuration.") from KeyError
+
+    def last_version(
+        self, min_version: str | None = None, max_version: str | None = None
+    ) -> str | None:
+        """Return the last version of the changelogs.
+        The changelogs are sorted by version.
+
+        Args:
+            min_version (str | None): The version to start from (inclusive).
+            max_version (str | None): The version to end at (inclusive).
+
+        Returns:
+            str | None: The last version of the changelogs. If no changelogs are found, None is returned.
+
+        """
+        changelogs = self.changelogs(min_version, max_version)
+        if not changelogs:
+            return None
+        if min_version:
+            changelogs = [
+                c for c in changelogs if c.version >= packaging.version.parse(min_version)
+            ]
+        if max_version:
+            changelogs = [
+                c for c in changelogs if c.version <= packaging.version.parse(max_version)
+            ]
+        if not changelogs:
+            return None
+        return changelogs[-1].version
+
+    def changelogs(self, min_version: str | None = None, max_version: str | None = None) -> list:
+        """Return a list of changelogs.
+        The changelogs are sorted by version.
+
+        Args:
+            min_version (str | None): The version to start from (inclusive).
+            max_version (str | None): The version to end at (inclusive).
+
+        Returns:
+            list: A list of changelogs. Each changelog is represented by a Changelog object.
+
+        """
+        path = self._base_path / self.config.changelogs_directory
+        if not path.is_dir():
+            raise PumException(f"Changelogs directory `{path}` does not exist.")
+        if not path.iterdir():
+            raise PumException(f"Changelogs directory `{path}` is empty.")
+
+        changelogs = [Changelog(d) for d in path.iterdir() if d.is_dir()]
+
+        if min_version:
+            changelogs = [
+                c for c in changelogs if c.version >= packaging.version.parse(min_version)
+            ]
+        if max_version:
+            changelogs = [
+                c for c in changelogs if c.version <= packaging.version.parse(max_version)
+            ]
+
+        changelogs.sort(key=lambda c: c.version)
+        return changelogs
+
+    def role_manager(self) -> RoleManager:
+        """Return a RoleManager instance based on the roles defined in the configuration."""
+        if not self.config.roles:
+            logger.warning("No roles defined in the configuration. Returning an empty RoleManager.")
+            return RoleManager()
+        return RoleManager([role.model_dump() for role in self.config.roles])
+
+    def pre_hook_handlers(self) -> list[HookHandler]:
+        """Return the list of pre-migration hook handlers."""
+        return (
+            [
+                HookHandler(base_path=self._base_path, **hook.model_dump())
+                for hook in self.config.migration_hooks.pre
+            ]
+            if self.config.migration_hooks.pre
+            else []
+        )
+
+    def post_hook_handlers(self) -> list[HookHandler]:
+        """Return the list of post-migration hook handlers."""
+        return (
+            [
+                HookHandler(base_path=self._base_path, **hook.model_dump())
+                for hook in self.config.migration_hooks.post
+            ]
+            if self.config.migration_hooks.post
+            else []
+        )
+
+    def demo_data(self) -> dict[str, str]:
+        """Return a dictionary of demo data files defined in the configuration."""
+        return {dm.name: dm.file for dm in self.config.demo_data}
+
+    def validate(self) -> None:
+        """Validate the chanbgelogs and hooks."""
+
+        parameter_defaults = {}
+        for parameter in self.config.parameters:
+            parameter_defaults[parameter.name] = psycopg.sql.Literal(parameter.default)
+
+        for changelog in self.changelogs():
+            try:
+                changelog.validate(parameters=parameter_defaults)
+            except (PumInvalidChangelog, PumSqlError) as e:
+                raise PumInvalidChangelog(f"Changelog `{changelog}` is invalid.") from e
+
+        hook_handlers = []
+        if self.config.migration_hooks.pre:
+            hook_handlers.extend(self.pre_hook_handlers())
+        if self.config.migration_hooks.post:
+            hook_handlers.extend(self.post_hook_handlers())
+        for hook_handler in hook_handlers:
+            try:
+                hook_handler.validate(parameter_defaults)
+            except PumHookError as e:
+                raise PumHookError(f"Hook `{hook_handler}` is invalid.") from e