pum 1.2.3__py3-none-any.whl → 1.3.0__py3-none-any.whl

pum/config_model.py

@@ -1,6 +1,6 @@
-import packaging
+from packaging.version import Version
 from pydantic import BaseModel, ConfigDict, Field, model_validator
-from typing import List, Optional, Any, Literal
+from typing import Any, Literal
 
 
 from .exceptions import PumConfigError
@@ -8,7 +8,7 @@ from .parameter import ParameterType
 
 
 class PumCustomBaseModel(BaseModel):
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
 
 
 class ParameterDefinitionModel(PumCustomBaseModel):
@@ -23,8 +23,8 @@ class ParameterDefinitionModel(PumCustomBaseModel):
 
     name: str
     type: ParameterType = Field(default=ParameterType.TEXT, description="Type of the parameter")
-    default: Optional[Any] = None
-    description: Optional[str] = None
+    default: Any | None = None
+    description: str | None = None
 
     @model_validator(mode="before")
     def validate_default(cls, values):
@@ -43,8 +43,8 @@ class HookModel(PumCustomBaseModel):
         code: Optional SQL code to execute as a hook.
     """
 
-    file: Optional[str] = None
-    code: Optional[str] = None
+    file: str | None = None
+    code: str | None = None
 
     @model_validator(mode="after")
     def validate_args(self):
@@ -54,17 +54,27 @@ class HookModel(PumCustomBaseModel):
         return self
 
 
-class MigrationHooksModel(PumCustomBaseModel):
+class ApplicationModel(PumCustomBaseModel):
     """
-    MigrationHooksModel holds the configuration for migration hooks.
+    ApplicationModel holds the configuration for application hooks.
 
     Attributes:
-        pre: List of pre-migration hooks.
-        post: List of post-migration hooks.
+        drop: Hooks to drop the application before applying migrations.
+        create: Hooks to create the application after applying migrations.
     """
 
-    pre: Optional[List[HookModel]] = []
-    post: Optional[List[HookModel]] = []
+    drop: list[HookModel] | None = Field(default=[], alias="pre")
+    create: list[HookModel] | None = Field(default=[], alias="post")
+
+    @model_validator(mode="before")
+    def handle_legacy_names(cls, values):
+        """Support legacy field names for backward compatibility."""
+        # If new names don't exist but old names do, use old names
+        if "drop" not in values and "pre" in values:
+            values["drop"] = values.pop("pre")
+        if "create" not in values and "post" in values:
+            values["create"] = values.pop("post")
+        return values
 
 
 class PumModel(PumCustomBaseModel):
@@ -72,16 +82,18 @@ class PumModel(PumCustomBaseModel):
     PumModel holds some PUM specifics.
 
     Attributes:
+        module: Name of the module being managed.
         migration_table_schema: Name of schema for the migration table. The table will always be named `pum_migrations`.
         minimum_version: Minimum required version of PUM.
     """
 
     model_config = {"arbitrary_types_allowed": True}
-    migration_table_schema: Optional[str] = Field(
+    module: str = Field(..., description="Name of the module being managed")
+    migration_table_schema: str | None = Field(
         default="public", description="Name of schema for the migration table"
     )
 
-    minimum_version: Optional[packaging.version.Version] = Field(
+    minimum_version: Version | None = Field(
         default=None,
         description="Minimum required version of pum.",
     )
@@ -90,7 +102,7 @@ class PumModel(PumCustomBaseModel):
     def parse_minimum_version(cls, values):
         min_ver = values.get("minimum_version")
         if isinstance(min_ver, str):
-            values["minimum_version"] = packaging.version.Version(min_ver)
+            values["minimum_version"] = Version(min_ver)
         return values
 
 
@@ -104,7 +116,7 @@ class PermissionModel(PumCustomBaseModel):
     """
 
     type: Literal["read", "write"] = Field(..., description="Permission type ('read' or 'write').")
-    schemas: List[str] = Field(
+    schemas: list[str] = Field(
         default_factory=list, description="List of schemas this permission applies to."
     )
 
@@ -120,11 +132,11 @@ class RoleModel(PumCustomBaseModel):
     """
 
     name: str = Field(..., description="Name of the role.")
-    permissions: List[PermissionModel] = Field(
+    permissions: list[PermissionModel] = Field(
         default_factory=list, description="List of permissions for the role."
     )
-    inherit: Optional[str] = Field(None, description="Name of the role to inherit from.")
-    description: Optional[str] = Field(None, description="Description of the role.")
+    inherit: str | None = Field(None, description="Name of the role to inherit from.")
+    description: str | None = Field(None, description="Description of the role.")
 
 
 class DemoDataModel(PumCustomBaseModel):
@@ -139,8 +151,8 @@ class DemoDataModel(PumCustomBaseModel):
 
     name: str = Field(..., description="Name of the demo data.")
 
-    file: Optional[str] = None
-    files: Optional[List[str]] = None
+    file: str | None = None
+    files: list[str] | None = None
 
     @model_validator(mode="after")
     def validate_args(self):
@@ -162,11 +174,11 @@ class DependencyModel(PumCustomBaseModel):
     model_config = {"arbitrary_types_allowed": True}
 
     name: str = Field(..., description="Name of the Python dependency.")
-    minimum_version: Optional[packaging.version.Version] = Field(
+    minimum_version: Version | None = Field(
         default=None,
         description="Specific minimum required version of the package.",
     )
-    maximum_version: Optional[packaging.version.Version] = Field(
+    maximum_version: Version | None = Field(
         default=None,
         description="Specific maximum required version of the package.",
     )
@@ -176,7 +188,7 @@ class DependencyModel(PumCustomBaseModel):
         for value in ("minimum_version", "maximum_version"):
             ver = values.get(value)
             if isinstance(ver, str):
-                values[value] = packaging.version.Version(ver)
+                values[value] = Version(ver)
             return values
 
 
@@ -187,15 +199,26 @@ class ConfigModel(PumCustomBaseModel):
     Attributes:
         pum: The PUM (Project Update Manager) configuration. Defaults to a new PumModel instance.
         parameters: List of parameter definitions. Defaults to an empty list.
-        migration_hooks: Configuration for migration hooks. Defaults to a new MigrationHooksModel instance.
+        application: Configuration for application hooks. Defaults to a new ApplicationModel instance.
         changelogs_directory: Directory path for changelogs. Defaults to "changelogs".
         roles: List of role definitions. Defaults to None.
     """
 
-    pum: Optional[PumModel] = Field(default_factory=PumModel)
-    parameters: Optional[List[ParameterDefinitionModel]] = []
-    migration_hooks: Optional[MigrationHooksModel] = Field(default_factory=MigrationHooksModel)
-    changelogs_directory: Optional[str] = "changelogs"
-    roles: Optional[List[RoleModel]] = []
-    demo_data: Optional[List[DemoDataModel]] = []
-    dependencies: Optional[List[DependencyModel]] = []
+    pum: PumModel | None = Field(default_factory=PumModel)
+    parameters: list[ParameterDefinitionModel] | None = []
+    application: ApplicationModel | None = Field(
+        default_factory=ApplicationModel, alias="migration_hooks"
+    )
+    changelogs_directory: str | None = "changelogs"
+    roles: list[RoleModel] | None = []
+    demo_data: list[DemoDataModel] | None = []
+    dependencies: list[DependencyModel] | None = []
+    uninstall: list[HookModel] | None = []
+
+    @model_validator(mode="before")
+    def handle_legacy_field_names(cls, values):
+        """Support legacy field names for backward compatibility."""
+        # If new name doesn't exist but old name does, use old name
+        if "application" not in values and "migration_hooks" in values:
+            values["application"] = values.pop("migration_hooks")
+        return values

pum/connection.py

@@ -0,0 +1,30 @@
+"""Utilities for handling PostgreSQL connection strings."""
+
+
+def format_connection_string(pg_connection: str) -> str:
+    """Format a connection string for use with psycopg.
+
+    Detects whether the input is a service name or a full connection string.
+    If it's a service name (simple identifier), wraps it as 'service=name'.
+    If it's a connection string (contains '=' or '://'), returns as-is.
+
+    Args:
+        pg_connection: Either a service name or a PostgreSQL connection string
+
+    Returns:
+        A properly formatted connection string for psycopg
+
+    Examples:
+        >>> format_connection_string('myservice')
+        'service=myservice'
+        >>> format_connection_string('postgresql://user:pass@localhost/db')
+        'postgresql://user:pass@localhost/db'
+        >>> format_connection_string('host=localhost dbname=mydb')
+        'host=localhost dbname=mydb'
+
+    """
+    # If it contains '=' or '://', it's already a connection string
+    if "=" in pg_connection or "://" in pg_connection:
+        return pg_connection
+    # Otherwise, it's a service name
+    return f"service={pg_connection}"

pum/dependency_handler.py

@@ -5,6 +5,7 @@ import os
 import sys
 import importlib.metadata
 import subprocess
+from pathlib import Path
 
 from .exceptions import PumDependencyError
 
@@ -51,7 +52,7 @@ class DependencyHandler:
                     f"Installed version of `{self.name}` ({installed_version}) is higher than the maximum allowed ({self.maximum_version})."
                 )
 
-            logger.info(f"Dependency {self.name} is satisfied.")
+            logger.debug(f"Dependency {self.name} is satisfied.")
 
         except importlib.metadata.PackageNotFoundError as e:
             if not install_dependencies:
@@ -59,6 +60,11 @@ class DependencyHandler:
                     f"Dependency `{self.name}` is not installed. You can activate the installation."
                 ) from e
             else:
+                if install_path is None:
+                    raise PumDependencyError(
+                        f"Dependency `{self.name}` is not installed and no install path was provided."
+                    )
+                logger.debug(f"Dependency {self.name} is not installed, proceeding to install.")
                 logger.warning(f"Dependency {self.name} is not installed, trying to install {e}")
                 self.pip_install(install_path=install_path)
                 logger.warning(f"Dependency {self.name} is now installed in {install_path}")
@@ -77,10 +83,54 @@ class DependencyHandler:
         elif self.maximum_version:
             req += f"<={self.maximum_version}"
 
-        command = [self.python_command(), "-m", "pip", "install", req, "--target", install_path]
+        python_cmd = self.python_command()
 
+        # First, ensure pip is installed in the target directory and upgrade it if needed
         try:
-            output = subprocess.run(command, capture_output=True, text=True, check=False)
+            pip_version_output = subprocess.run(
+                [python_cmd, "-m", "pip", "--version"], capture_output=True, text=True, check=False
+            )
+            if pip_version_output.returncode == 0:
+                # Extract pip version (format: "pip X.Y.Z from ...")
+                pip_version_str = pip_version_output.stdout.split()[1]
+                pip_version = packaging.version.Version(pip_version_str)
+                if pip_version < packaging.version.Version("22.0"):
+                    logger.warning(
+                        f"pip version {pip_version} is outdated, installing newer pip to target directory..."
+                    )
+                    # Install a newer pip to the target directory first
+                    # This will be used by subsequent installations
+                    upgrade_cmd = [
+                        python_cmd,
+                        "-m",
+                        "pip",
+                        "install",
+                        "--upgrade",
+                        "pip>=22.0",
+                        "--target",
+                        install_path,
+                    ]
+                    upgrade_result = subprocess.run(
+                        upgrade_cmd, capture_output=True, text=True, check=False
+                    )
+                    if upgrade_result.returncode == 0:
+                        logger.info(f"Successfully upgraded pip in {install_path}")
+        except Exception as e:
+            logger.debug(f"Could not check/upgrade pip version: {e}")
+
+        # Set PYTHONPATH to include install_path so pip can find itself and other packages
+        env = os.environ.copy()
+        # Ensure install_path is a string for environment variables (Windows compatibility)
+        install_path_str = str(install_path)
+        if "PYTHONPATH" in env:
+            env["PYTHONPATH"] = f"{install_path_str}{os.pathsep}{env['PYTHONPATH']}"
+        else:
+            env["PYTHONPATH"] = install_path_str
+
+        command = [python_cmd, "-m", "pip", "install", req, "--target", install_path_str]
+
+        try:
+            output = subprocess.run(command, capture_output=True, text=True, check=False, env=env)
             if output.returncode != 0:
                 logger.error("pip installed failed: %s", output.stderr)
                 raise PumDependencyError(output.stderr)
@@ -91,4 +141,19 @@ class DependencyHandler:
     def python_command(self):
         # python is normally found at sys.executable, but there is an issue on windows qgis so use 'python' instead
         # https://github.com/qgis/QGIS/issues/45646
-        return "python" if os.name == "nt" else sys.executable
+        if os.name == "nt":
+            return "python"
+
+        # On macOS and Linux, if we're running inside QGIS, sys.executable points to the QGIS app
+        # Look for the python executable in the same directory as sys.executable
+        if sys.executable and "QGIS" in sys.executable:
+            python_dir = Path(sys.executable).parent
+            python_executable = python_dir / "python"
+            if python_executable.exists():
+                return str(python_executable)
+            # Try python3 as fallback
+            python3_executable = python_dir / "python3"
+            if python3_executable.exists():
+                return str(python3_executable)
+
+        return sys.executable

pum/dumper.py

@@ -8,6 +8,7 @@ from .exceptions import (
     PgRestoreCommandError,
     PgRestoreFailed,
 )
+from .connection import format_connection_string
 
 logger = logging.getLogger(__name__)
 
@@ -27,8 +28,17 @@ class DumpFormat(Enum):
 class Dumper:
     """This class is used to dump and restore a Postgres database."""
 
-    def __init__(self, pg_service: str, dump_path: str):
-        self.pg_service = pg_service
+    def __init__(self, pg_connection: str, dump_path: str):
+        """Initialize the Dumper.
+
+        Args:
+            pg_connection: PostgreSQL service name or connection string.
+                Can be a service name (e.g., 'mydb') or a full connection string
+                (e.g., 'postgresql://user:pass@host/db' or 'host=localhost dbname=mydb').
+            dump_path: Path where the dump file will be saved or loaded from.
+
+        """
+        self.pg_connection = pg_connection
         self.dump_path = dump_path
 
     def pg_dump(
@@ -49,7 +59,7 @@ class Dumper:
             format: DumpFormat, either custom (default) or plain
         """
 
-        connection = f"service={self.pg_service}"
+        connection = format_connection_string(self.pg_connection)
         if dbname:
             connection = f"{connection} dbname={dbname}"
 
@@ -85,7 +95,7 @@ class Dumper:
     ):
         """ """
 
-        connection = f"service={self.pg_service}"
+        connection = format_connection_string(self.pg_connection)
         if dbname:
             connection = f"{connection} dbname={dbname}"
 

pum/exceptions.py

@@ -18,6 +18,15 @@ class PumInvalidChangelog(PumException):
     """Exception raised for invalid changelog."""
 
 
+# --- Schema Migration Errors ---
+class PumSchemaMigrationError(PumException):
+    """Exception raised for errors related to schema migrations."""
+
+
+class PumSchemaMigrationNoBaselineError(PumSchemaMigrationError):
+    """Exception raised when no baseline version is found in the migration table."""
+
+
 # --- Hook Errors ---
 
 

pum/feedback.py

@@ -0,0 +1,119 @@
+"""Feedback system for reporting progress and handling cancellation during operations."""
+
+import abc
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Feedback(abc.ABC):
+    """Base class for feedback during install/upgrade operations.
+
+    This class provides methods for progress reporting and cancellation handling.
+    Subclasses should implement the abstract methods to provide custom feedback mechanisms.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the feedback instance."""
+        self._is_cancelled = False
+        self._cancellation_locked = False
+        self._current_step = 0
+        self._total_steps = 0
+
+    def set_total_steps(self, total: int) -> None:
+        """Set the total number of steps for the operation.
+
+        Args:
+            total: The total number of steps.
+        """
+        self._total_steps = total
+        self._current_step = 0
+
+    def increment_step(self) -> None:
+        """Increment the current step counter."""
+        self._current_step += 1
+
+    def get_progress(self) -> tuple[int, int]:
+        """Get the current progress.
+
+        Returns:
+            A tuple of (current_step, total_steps).
+        """
+        return (self._current_step, self._total_steps)
+
+    @abc.abstractmethod
+    def report_progress(self, message: str, current: int = 0, total: int = 0) -> None:
+        """Report progress during an operation.
+
+        Args:
+            message: A message describing the current operation.
+            current: The current progress value (e.g., changelog number).
+            total: The total number of steps.
+        """
+        pass
+
+    def is_cancelled(self) -> bool:
+        """Check if the operation has been cancelled.
+
+        Returns:
+            True if the operation should be cancelled, False otherwise.
+            Always returns False if cancellation has been locked (after commit).
+        """
+        if self._cancellation_locked:
+            return False
+        return self._is_cancelled
+
+    def cancel(self) -> None:
+        """Cancel the operation.
+
+        Note: This will have no effect if cancellation has been locked (after commit).
+        """
+        if not self._cancellation_locked:
+            self._is_cancelled = True
+
+    def reset(self) -> None:
+        """Reset the cancellation status."""
+        self._is_cancelled = False
+
+    def lock_cancellation(self) -> None:
+        """Lock cancellation to prevent it after a commit.
+
+        Once locked, is_cancelled() will always return False and cancel() will have no effect.
+        This should be called immediately before committing database changes.
+        """
+        self._cancellation_locked = True
+
+
+class LogFeedback(Feedback):
+    """Feedback implementation that logs progress messages.
+
+    This is the default feedback implementation that simply logs messages
+    without any UI interaction.
+    """
+
+    def report_progress(self, message: str, current: int = 0, total: int = 0) -> None:
+        """Report progress by logging the message.
+
+        Args:
+            message: A message describing the current operation.
+            current: The current progress value (ignored, uses internal counter).
+            total: The total number of steps (ignored, uses internal counter).
+        """
+        logger.info(message)
+
+
+class SilentFeedback(Feedback):
+    """Feedback implementation that does nothing.
+
+    This can be used when no feedback is desired.
+    """
+
+    def report_progress(self, message: str, current: int = 0, total: int = 0) -> None:
+        """Do nothing - silent feedback.
+
+        Args:
+            message: A message describing the current operation (ignored).
+            current: The current progress value (ignored).
+            total: The total number of steps (ignored).
+        """
+        pass