plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/migrations/operations/special.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from .base import Operation
+
+if TYPE_CHECKING:
+    from plain.postgres.migrations.state import ProjectState
+    from plain.postgres.schema import DatabaseSchemaEditor
+
+
+class SeparateDatabaseAndState(Operation):
+    """
+    Take two lists of operations - ones that will be used for the database,
+    and ones that will be used for the state change. This allows operations
+    that don't support state change to have it applied, or have operations
+    that affect the state or not the database, or so on.
+    """
+
+    serialization_expand_args = ["database_operations", "state_operations"]
+
+    def __init__(
+        self,
+        database_operations: list[Operation] | None = None,
+        state_operations: list[Operation] | None = None,
+    ) -> None:
+        self.database_operations = database_operations or []
+        self.state_operations = state_operations or []
+
+    def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, list[Operation]]]:
+        kwargs: dict[str, list[Operation]] = {}
+        if self.database_operations:
+            kwargs["database_operations"] = self.database_operations
+        if self.state_operations:
+            kwargs["state_operations"] = self.state_operations
+        return (self.__class__.__qualname__, (), kwargs)
+
+    def state_forwards(self, package_label: str, state: ProjectState) -> None:
+        for state_operation in self.state_operations:
+            state_operation.state_forwards(package_label, state)
+
+    def database_forwards(
+        self,
+        package_label: str,
+        schema_editor: DatabaseSchemaEditor,
+        from_state: ProjectState,
+        to_state: ProjectState,
+    ) -> None:
+        # We calculate state separately in here since our state functions aren't useful
+        for database_operation in self.database_operations:
+            to_state = from_state.clone()
+            database_operation.state_forwards(package_label, to_state)
+            database_operation.database_forwards(
+                package_label, schema_editor, from_state, to_state
+            )
+            from_state = to_state
+
+    def describe(self) -> str:
+        return "Custom state/database change combination"
+
+
+class RunSQL(Operation):
+    """
+    Run some raw SQL.
+
+    Also accept a list of operations that represent the state change effected
+    by this SQL change, in case it's custom column/table creation/deletion.
+    """
+
+    def __init__(
+        self,
+        sql: str
+        | list[str | tuple[str, list[Any]]]
+        | tuple[str | tuple[str, list[Any]], ...],
+        *,
+        state_operations: list[Operation] | None = None,
+        elidable: bool = False,
+    ) -> None:
+        self.sql = sql
+        self.state_operations = state_operations or []
+        self.elidable = elidable
+
+    def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
+        kwargs: dict[str, Any] = {
+            "sql": self.sql,
+        }
+        if self.state_operations:
+            kwargs["state_operations"] = self.state_operations
+        return (self.__class__.__qualname__, (), kwargs)
+
+    def state_forwards(self, package_label: str, state: ProjectState) -> None:
+        for state_operation in self.state_operations:
+            state_operation.state_forwards(package_label, state)
+
+    def database_forwards(
+        self,
+        package_label: str,
+        schema_editor: DatabaseSchemaEditor,
+        from_state: ProjectState,
+        to_state: ProjectState,
+    ) -> None:
+        self._run_sql(schema_editor, self.sql)
+
+    def describe(self) -> str:
+        return "Raw SQL operation"
+
+    def _run_sql(
+        self,
+        schema_editor: DatabaseSchemaEditor,
+        sqls: str
+        | list[str | tuple[str, list[Any]]]
+        | tuple[str | tuple[str, list[Any]], ...],
+    ) -> None:
+        if isinstance(sqls, list | tuple):
+            for sql_item in sqls:
+                params: list[Any] | None = None
+                sql: str
+                if isinstance(sql_item, list | tuple):
+                    elements = len(sql_item)
+                    if elements == 2:
+                        sql, params = sql_item
+                    else:
+                        raise ValueError("Expected a 2-tuple but got %d" % elements)  # noqa: UP031
+                else:
+                    sql = sql_item
+                schema_editor.execute(sql, params=params)
+        else:
+            # PostgreSQL can handle multi-statement scripts in a single execute call
+            schema_editor.execute(sqls, params=None)
+
+
+class RunPython(Operation):
+    """
+    Run Python code in a context suitable for doing versioned ORM operations.
+    """
+
+    reduces_to_sql = False
+
+    def __init__(
+        self,
+        code: Callable[..., Any],
+        *,
+        atomic: bool | None = None,
+        elidable: bool = False,
+    ) -> None:
+        self.atomic = atomic
+        # Forwards code
+        if not callable(code):
+            raise ValueError("RunPython must be supplied with a callable")
+        self.code = code
+        self.elidable = elidable
+
+    def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
+        kwargs: dict[str, Any] = {
+            "code": self.code,
+        }
+        if self.atomic is not None:
+            kwargs["atomic"] = self.atomic
+        return (self.__class__.__qualname__, (), kwargs)
+
+    def state_forwards(self, package_label: str, state: Any) -> None:
+        # RunPython objects have no state effect. To add some, combine this
+        # with SeparateDatabaseAndState.
+        pass
+
+    def database_forwards(
+        self,
+        package_label: str,
+        schema_editor: DatabaseSchemaEditor,
+        from_state: ProjectState,
+        to_state: ProjectState,
+    ) -> None:
+        # RunPython has access to all models. Ensure that all models are
+        # reloaded in case any are delayed.
+        from_state.clear_delayed_models_cache()
+        # We now execute the Python code in a context that contains a 'models'
+        # object, representing the versioned models as an app registry.
+        # We could try to override the global cache, but then people will still
+        # use direct imports, so we go with a documentation approach instead.
+        self.code(from_state.models_registry, schema_editor)
+
+    def describe(self) -> str:
+        return "Raw Python operation"

plain/postgres/migrations/optimizer.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MigrationOptimizer:
+    """
+    Power the optimization process, where you provide a list of Operations
+    and you are returned a list of equal or shorter length - operations
+    are merged into one if possible.
+
+    For example, a CreateModel and an AddField can be optimized into a
+    new CreateModel, and CreateModel and DeleteModel can be optimized into
+    nothing.
+    """
+
+    def optimize(self, operations: list[Any], package_label: str) -> list[Any]:
+        """
+        Main optimization entry point. Pass in a list of Operation instances,
+        get out a new list of Operation instances.
+
+        Unfortunately, due to the scope of the optimization (two combinable
+        operations might be separated by several hundred others), this can't be
+        done as a peephole optimization with checks/output implemented on
+        the Operations themselves; instead, the optimizer looks at each
+        individual operation and scans forwards in the list to see if there
+        are any matches, stopping at boundaries - operations which can't
+        be optimized over (RunSQL, operations on the same field/model, etc.)
+
+        The inner loop is run until the starting list is the same as the result
+        list, and then the result is returned. This means that operation
+        optimization must be stable and always return an equal or shorter list.
+        """
+        # Internal tracking variable for test assertions about # of loops
+        if package_label is None:
+            raise TypeError("package_label must be a str.")
+        while True:
+            result = self.optimize_inner(operations, package_label)
+            if result == operations:
+                return result
+            operations = result
+
+    def optimize_inner(self, operations: list[Any], package_label: str) -> list[Any]:
+        """Inner optimization loop."""
+        new_operations = []
+        for i, operation in enumerate(operations):
+            right = True  # Should we reduce on the right or on the left.
+            # Compare it to each operation after it
+            for j, other in enumerate(operations[i + 1 :]):
+                result = operation.reduce(other, package_label)
+                if isinstance(result, list):
+                    in_between = operations[i + 1 : i + j + 1]
+                    if right:
+                        new_operations.extend(in_between)
+                        new_operations.extend(result)
+                    elif all(
+                        op.reduce(other, package_label) is True for op in in_between
+                    ):
+                        # Perform a left reduction if all of the in-between
+                        # operations can optimize through other.
+                        new_operations.extend(result)
+                        new_operations.extend(in_between)
+                    else:
+                        # Otherwise keep trying.
+                        new_operations.append(operation)
+                        break
+                    new_operations.extend(operations[i + j + 2 :])
+                    return new_operations
+                elif not result:
+                    # Can't perform a right reduction.
+                    right = False
+            else:
+                new_operations.append(operation)
+        return new_operations

plain/postgres/migrations/questioner.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+import datetime
+import importlib
+import os
+import sys
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from plain.packages import packages_registry
+from plain.postgres.fields import NOT_PROVIDED
+from plain.utils import timezone
+
+from .loader import MigrationLoader
+
+if TYPE_CHECKING:
+    from plain.postgres.fields import Field
+
+
+class MigrationQuestioner:
+    """
+    Give the autodetector responses to questions it might have.
+    This base class has a built-in noninteractive mode, but the
+    interactive subclass is what the command-line arguments will use.
+    """
+
+    def __init__(
+        self,
+        defaults: dict[str, Any] | None = None,
+        specified_packages: set[str] | None = None,
+        dry_run: bool | None = None,
+    ) -> None:
+        self.defaults = defaults or {}
+        self.specified_packages = specified_packages or set()
+        self.dry_run = dry_run
+
+    def ask_initial(self, package_label: str) -> bool:
+        """Should we create an initial migration for the app?"""
+        # If it was specified on the command line, definitely true
+        if package_label in self.specified_packages:
+            return True
+        # Otherwise, we look to see if it has a migrations module
+        # without any Python files in it, apart from __init__.py.
+        # Packages from the new app template will have these; the Python
+        # file check will ensure we skip South ones.
+        try:
+            package_config = packages_registry.get_package_config(package_label)
+        except LookupError:  # It's a fake app.
+            return self.defaults.get("ask_initial", False)
+        migrations_import_path, _ = MigrationLoader.migrations_module(
+            package_config.package_label
+        )
+        if migrations_import_path is None:
+            # It's an application with migrations disabled.
+            return self.defaults.get("ask_initial", False)
+        try:
+            migrations_module = importlib.import_module(migrations_import_path)
+        except ImportError:
+            return self.defaults.get("ask_initial", False)
+        else:
+            if file := getattr(migrations_module, "__file__", None):
+                filenames = os.listdir(os.path.dirname(file))
+            elif hasattr(migrations_module, "__path__"):
+                if len(migrations_module.__path__) > 1:
+                    return False
+                filenames = os.listdir(list(migrations_module.__path__)[0])
+            return not any(x.endswith(".py") for x in filenames if x != "__init__.py")
+
+    def ask_not_null_addition(self, field_name: str, model_name: str) -> Any:
+        """Adding a NOT NULL field to a model."""
+        # None means quit
+        return None
+
+    def ask_not_null_alteration(self, field_name: str, model_name: str) -> Any:
+        """Changing a NULL field to NOT NULL."""
+        # None means quit
+        return None
+
+    def ask_rename(
+        self, model_name: str, old_name: str, new_name: str, field_instance: Field
+    ) -> bool:
+        """Was this field really renamed?"""
+        return self.defaults.get("ask_rename", False)
+
+    def ask_rename_model(self, old_model_state: Any, new_model_state: Any) -> bool:
+        """Was this model really renamed?"""
+        return self.defaults.get("ask_rename_model", False)
+
+    def ask_auto_now_add_addition(self, field_name: str, model_name: str) -> Any:
+        """Adding an auto_now_add field to a model."""
+        # None means quit
+        return None
+
+    def ask_unique_callable_default_addition(
+        self, field_name: str, model_name: str
+    ) -> Any:
+        """Adding a unique field with a callable default."""
+        # None means continue.
+        return None
+
+
+class InteractiveMigrationQuestioner(MigrationQuestioner):
+    def __init__(
+        self,
+        defaults: dict[str, Any] | None = None,
+        specified_packages: set[str] | None = None,
+        dry_run: bool | None = None,
+    ) -> None:
+        super().__init__(
+            defaults=defaults, specified_packages=specified_packages, dry_run=dry_run
+        )
+
+    def _boolean_input(self, question: str, default: bool | None = None) -> bool:
+        return click.confirm(question, default=default)
+
+    def _choice_input(self, question: str, choices: list[str]) -> int:
+        choice_map = {str(i + 1): choice for i, choice in enumerate(choices)}
+        choice_map_str = "\n".join(
+            [f"{i}) {choice}" for i, choice in choice_map.items()]
+        )
+        choice = click.prompt(
+            f"{question}\n{choice_map_str}\nSelect an option",
+            type=click.Choice(choice_map.keys()),
+        )
+        return int(choice)
+
+    def _ask_default(self, default: str = "") -> Any:
+        """
+        Prompt for a default value.
+
+        The ``default`` argument allows providing a custom default value (as a
+        string) which will be shown to the user and used as the return value
+        if the user doesn't provide any other input.
+        """
+        click.echo("Please enter the default value as valid Python.")
+        if default:
+            click.echo(
+                f"Accept the default '{default}' by pressing 'Enter' or "
+                f"provide another value."
+            )
+        click.echo(
+            "The datetime and plain.utils.timezone modules are available, so "
+            "it is possible to provide e.g. timezone.now as a value."
+        )
+        click.echo("Type 'exit' to exit this prompt")
+        while True:
+            if default:
+                prompt = f"[default: {default}] >>> "
+            else:
+                prompt = ">>> "
+            code = click.prompt(prompt, default=default, show_default=False)
+            if not code and default:
+                code = default
+            if not code:
+                click.echo(
+                    "Please enter some code, or 'exit' (without quotes) to exit."
+                )
+            elif code == "exit":
+                sys.exit(1)
+            else:
+                try:
+                    return eval(code, {}, {"datetime": datetime, "timezone": timezone})
+                except (SyntaxError, NameError) as e:
+                    click.echo(f"Invalid input: {e}")
+
+    def ask_not_null_addition(self, field_name: str, model_name: str) -> Any:
+        """Adding a NOT NULL field to a model."""
+        if not self.dry_run:
+            choice = self._choice_input(
+                f"It is impossible to add a non-nullable field '{field_name}' "
+                f"to {model_name} without specifying a default. This is "
+                f"because the database needs something to populate existing "
+                f"rows.\n"
+                f"Please select a fix:",
+                [
+                    (
+                        "Provide a one-off default now (will be set on all existing "
+                        "rows with a null value for this column)"
+                    ),
+                    "Quit and manually define a default value in models.py.",
+                ],
+            )
+            if choice == 2:
+                sys.exit(3)
+            else:
+                return self._ask_default()
+        return None
+
+    def ask_not_null_alteration(self, field_name: str, model_name: str) -> Any:
+        """Changing a NULL field to NOT NULL."""
+        if not self.dry_run:
+            choice = self._choice_input(
+                f"It is impossible to change a nullable field '{field_name}' "
+                f"on {model_name} to non-nullable without providing a "
+                f"default. This is because the database needs something to "
+                f"populate existing rows.\n"
+                f"Please select a fix:",
+                [
+                    (
+                        "Provide a one-off default now (will be set on all existing "
+                        "rows with a null value for this column)"
+                    ),
+                    "Ignore for now. Existing rows that contain NULL values "
+                    "will have to be handled manually, for example with a "
+                    "RunPython or RunSQL operation.",
+                    "Quit and manually define a default value in models.py.",
+                ],
+            )
+            if choice == 2:
+                return NOT_PROVIDED
+            elif choice == 3:
+                sys.exit(3)
+            else:
+                return self._ask_default()
+        return None
+
+    def ask_rename(
+        self, model_name: str, old_name: str, new_name: str, field_instance: Field
+    ) -> bool:
+        """Was this field really renamed?"""
+        msg = "Was %s.%s renamed to %s.%s (a %s)?"
+        return self._boolean_input(
+            msg
+            % (
+                model_name,
+                old_name,
+                model_name,
+                new_name,
+                field_instance.__class__.__name__,
+            ),
+            default=False,
+        )
+
+    def ask_rename_model(self, old_model_state: Any, new_model_state: Any) -> bool:
+        """Was this model really renamed?"""
+        msg = "Was the model %s.%s renamed to %s?"
+        return self._boolean_input(
+            msg
+            % (
+                old_model_state.package_label,
+                old_model_state.name,
+                new_model_state.name,
+            ),
+            default=False,
+        )
+
+    def ask_auto_now_add_addition(self, field_name: str, model_name: str) -> Any:
+        """Adding an auto_now_add field to a model."""
+        if not self.dry_run:
+            choice = self._choice_input(
+                f"It is impossible to add the field '{field_name}' with "
+                f"'auto_now_add=True' to {model_name} without providing a "
+                f"default. This is because the database needs something to "
+                f"populate existing rows.\n",
+                [
+                    "Provide a one-off default now which will be set on all "
+                    "existing rows",
+                    "Quit and manually define a default value in models.py.",
+                ],
+            )
+            if choice == 2:
+                sys.exit(3)
+            else:
+                return self._ask_default(default="timezone.now")
+        return None
+
+    def ask_unique_callable_default_addition(
+        self, field_name: str, model_name: str
+    ) -> Any:
+        """Adding a unique field with a callable default."""
+        if not self.dry_run:
+            choice = self._choice_input(
+                f"Callable default on unique field {model_name}.{field_name} "
+                f"will not generate unique values upon migrating.\n"
+                f"Please choose how to proceed:\n",
+                [
+                    "Continue making this migration as the first step in "
+                    "writing a manual migration to generate unique values.",
+                    "Quit and edit field options in models.py.",
+                ],
+            )
+            if choice == 2:
+                sys.exit(3)
+        return None
+
+
+class NonInteractiveMigrationQuestioner(MigrationQuestioner):
+    def __init__(
+        self,
+        defaults: dict[str, Any] | None = None,
+        specified_packages: set[str] | None = None,
+        dry_run: bool | None = None,
+        verbosity: int = 1,
+        log: Callable[[str], Any] | None = None,
+    ) -> None:
+        self.verbosity = verbosity
+        self.log = log
+        super().__init__(
+            defaults=defaults,
+            specified_packages=specified_packages,
+            dry_run=dry_run,
+        )
+
+    def log_lack_of_migration(
+        self, field_name: str, model_name: str, reason: str
+    ) -> None:
+        if self.verbosity > 0 and self.log:
+            self.log(
+                f"Field '{field_name}' on model '{model_name}' not migrated: {reason}."
+            )
+
+    def ask_not_null_addition(self, field_name: str, model_name: str) -> Any:
+        # We can't ask the user, so act like the user aborted.
+        self.log_lack_of_migration(
+            field_name,
+            model_name,
+            "it is impossible to add a non-nullable field without specifying a default",
+        )
+        sys.exit(3)
+
+    def ask_not_null_alteration(self, field_name: str, model_name: str) -> Any:
+        # We can't ask the user, so set as not provided.
+        if self.log:
+            self.log(
+                f"Field '{field_name}' on model '{model_name}' given a default of "
+                f"NOT PROVIDED and must be corrected."
+            )
+        return NOT_PROVIDED
+
+    def ask_auto_now_add_addition(self, field_name: str, model_name: str) -> Any:
+        # We can't ask the user, so act like the user aborted.
+        self.log_lack_of_migration(
+            field_name,
+            model_name,
+            "it is impossible to add a field with 'auto_now_add=True' without "
+            "specifying a default",
+        )
+        sys.exit(3)