plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/migrations/utils.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import datetime
+import re
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from plain.postgres.fields.related import (
+    RECURSIVE_RELATIONSHIP_CONSTANT,
+    RelatedField,
+)
+
+if TYPE_CHECKING:
+    from plain.postgres.fields import Field
+    from plain.postgres.fields.reverse_related import ForeignObjectRel
+
+
+class FieldReference(NamedTuple):
+    """Reference to a field in migrations, tracking direct and through relationships."""
+
+    to: tuple[ForeignObjectRel, list[str]] | None
+    through: tuple[ForeignObjectRel, tuple[str, ...] | None] | None
+
+
+COMPILED_REGEX_TYPE = type(re.compile(""))
+
+
+class RegexObject:
+    def __init__(self, obj: Any) -> None:
+        self.pattern = obj.pattern
+        self.flags = obj.flags
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, RegexObject):
+            return NotImplemented
+        return self.pattern == other.pattern and self.flags == other.flags
+
+
+def get_migration_name_timestamp() -> str:
+    return datetime.datetime.now().strftime("%Y%m%d_%H%M")
+
+
+def resolve_relation(
+    model: str | Any, package_label: str | None = None, model_name: str | None = None
+) -> tuple[str, str]:
+    """
+    Turn a model class or model reference string and return a model tuple.
+
+    package_label and model_name are used to resolve the scope of recursive and
+    unscoped model relationship.
+    """
+    if isinstance(model, str):
+        if model == RECURSIVE_RELATIONSHIP_CONSTANT:
+            if package_label is None or model_name is None:
+                raise TypeError(
+                    "package_label and model_name must be provided to resolve "
+                    "recursive relationships."
+                )
+            return package_label, model_name
+        if "." in model:
+            package_label, model_name = model.split(".", 1)
+            return package_label, model_name.lower()
+        if package_label is None:
+            raise TypeError(
+                "package_label must be provided to resolve unscoped model relationships."
+            )
+        return package_label, model.lower()
+    return model.model_options.package_label, model.model_options.model_name
+
+
+def field_references(
+    model_tuple: tuple[str, str],
+    field: Field,
+    reference_model_tuple: tuple[str, str],
+    reference_field_name: str | None = None,
+    reference_field: Field | None = None,
+) -> FieldReference | bool:
+    """
+    Return either False or a FieldReference if `field` references provided
+    context.
+
+    False positives can be returned if `reference_field_name` is provided
+    without `reference_field` because of the introspection limitation it
+    incurs. This should not be an issue when this function is used to determine
+    whether or not an optimization can take place.
+    """
+    # Only RelatedFields have remote_field attribute
+    if not isinstance(field, RelatedField):
+        return False
+    remote_field = field.remote_field
+    if not remote_field:
+        return False
+    references_to = None
+    references_through = None
+    if resolve_relation(remote_field.model, *model_tuple) == reference_model_tuple:
+        # ForeignObject always references 'id'
+        if (
+            reference_field_name is None
+            or reference_field_name == "id"
+            or (reference_field is None or reference_field.primary_key)
+        ):
+            references_to = (remote_field, ["id"])
+    through = getattr(remote_field, "through", None)
+    if through and resolve_relation(through, *model_tuple) == reference_model_tuple:
+        through_fields = getattr(remote_field, "through_fields", None)
+        if (
+            reference_field_name is None
+            or
+            # Unspecified through_fields.
+            through_fields is None
+            or
+            # Reference to field.
+            reference_field_name in through_fields
+        ):
+            references_through = (remote_field, through_fields)
+    if not (references_to or references_through):
+        return False
+    return FieldReference(references_to, references_through)
+
+
+def get_references(
+    state: Any, model_tuple: tuple[str, str], field_tuple: tuple[Any, ...] = ()
+) -> Generator[tuple[Any, str, Field, FieldReference]]:
+    """
+    Generator of (model_state, name, field, reference) referencing
+    provided context.
+
+    If field_tuple is provided only references to this particular field of
+    model_tuple will be generated.
+    """
+    for state_model_tuple, model_state in state.models.items():
+        for name, field in model_state.fields.items():
+            reference = field_references(
+                state_model_tuple,
+                field,
+                model_tuple,
+                *field_tuple,
+            )
+            if reference:
+                yield model_state, name, field, reference
+
+
+def field_is_referenced(
+    state: Any, model_tuple: tuple[str, str], field_tuple: tuple[Any, ...]
+) -> bool:
+    """Return whether `field_tuple` is referenced by any state models."""
+    return next(get_references(state, model_tuple, field_tuple), None) is not None

plain/postgres/migrations/writer.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import os
+import re
+from importlib import import_module
+from typing import Any
+
+from plain.packages import packages_registry
+from plain.postgres import migrations
+from plain.postgres.migrations.loader import MigrationLoader
+from plain.postgres.migrations.migration import SettingsTuple
+from plain.postgres.migrations.serializer import serializer_factory
+from plain.runtime import __version__
+from plain.utils.inspect import get_func_args
+from plain.utils.module_loading import module_dir
+from plain.utils.timezone import now
+
+
+class OperationWriter:
+    def __init__(self, operation: Any, indentation: int = 2) -> None:
+        self.operation = operation
+        self.buff: list[str] = []
+        self.indentation = indentation
+
+    def serialize(self) -> tuple[str, set[str]]:
+        def _write(_arg_name: str, _arg_value: Any) -> None:
+            if _arg_name in self.operation.serialization_expand_args and isinstance(
+                _arg_value, list | tuple | dict
+            ):
+                if isinstance(_arg_value, dict):
+                    self.feed(f"{_arg_name}={{")
+                    self.indent()
+                    for key, value in _arg_value.items():
+                        key_string, key_imports = MigrationWriter.serialize(key)
+                        arg_string, arg_imports = MigrationWriter.serialize(value)
+                        args = arg_string.splitlines()
+                        if len(args) > 1:
+                            self.feed(f"{key_string}: {args[0]}")
+                            for arg in args[1:-1]:
+                                self.feed(arg)
+                            self.feed(f"{args[-1]},")
+                        else:
+                            self.feed(f"{key_string}: {arg_string},")
+                        imports.update(key_imports)
+                        imports.update(arg_imports)
+                    self.unindent()
+                    self.feed("},")
+                else:
+                    self.feed(f"{_arg_name}=[")
+                    self.indent()
+                    for item in _arg_value:
+                        arg_string, arg_imports = MigrationWriter.serialize(item)
+                        args = arg_string.splitlines()
+                        if len(args) > 1:
+                            for arg in args[:-1]:
+                                self.feed(arg)
+                            self.feed(f"{args[-1]},")
+                        else:
+                            self.feed(f"{arg_string},")
+                        imports.update(arg_imports)
+                    self.unindent()
+                    self.feed("],")
+            else:
+                arg_string, arg_imports = MigrationWriter.serialize(_arg_value)
+                args = arg_string.splitlines()
+                if len(args) > 1:
+                    self.feed(f"{_arg_name}={args[0]}")
+                    for arg in args[1:-1]:
+                        self.feed(arg)
+                    self.feed(f"{args[-1]},")
+                else:
+                    self.feed(f"{_arg_name}={arg_string},")
+                imports.update(arg_imports)
+
+        imports = set()
+        name, args, kwargs = self.operation.deconstruct()
+        operation_args = get_func_args(self.operation.__init__)
+
+        # See if this operation is in plain.postgres.migrations. If it is,
+        # We can just use the fact we already have that imported,
+        # otherwise, we need to add an import for the operation class.
+        if getattr(migrations, name, None) == self.operation.__class__:
+            self.feed(f"migrations.{name}(")
+        else:
+            imports.add(f"import {self.operation.__class__.__module__}")
+            self.feed(f"{self.operation.__class__.__module__}.{name}(")
+
+        self.indent()
+
+        for i, arg in enumerate(args):
+            arg_value = arg
+            arg_name = operation_args[i]
+            _write(arg_name, arg_value)
+
+        i = len(args)
+        # Only iterate over remaining arguments
+        for arg_name in operation_args[i:]:
+            if arg_name in kwargs:  # Don't sort to maintain signature order
+                arg_value = kwargs[arg_name]
+                _write(arg_name, arg_value)
+
+        self.unindent()
+        self.feed("),")
+        return self.render(), imports
+
+    def indent(self) -> None:
+        self.indentation += 1
+
+    def unindent(self) -> None:
+        self.indentation -= 1
+
+    def feed(self, line: str) -> None:
+        self.buff.append(" " * (self.indentation * 4) + line)
+
+    def render(self) -> str:
+        return "\n".join(self.buff)
+
+
+class MigrationWriter:
+    """
+    Take a Migration instance and is able to produce the contents
+    of the migration file from it.
+    """
+
+    def __init__(self, migration: Any, include_header: bool = True) -> None:
+        self.migration = migration
+        self.include_header = include_header
+        self.needs_manual_porting = False
+
+    def as_string(self) -> str:
+        """Return a string of the file contents."""
+        items = {
+            "replaces_str": "",
+            "initial_str": "",
+        }
+
+        imports = set()
+
+        # Deconstruct operations
+        operations = []
+        for operation in self.migration.operations:
+            operation_string, operation_imports = OperationWriter(operation).serialize()
+            imports.update(operation_imports)
+            operations.append(operation_string)
+        items["operations"] = "\n".join(operations) + "\n" if operations else ""
+
+        # Format dependencies and write out settings dependencies right
+        dependencies = []
+        for dependency in self.migration.dependencies:
+            if isinstance(dependency, SettingsTuple):
+                dependencies.append(
+                    f"        migrations.settings_dependency(settings.{dependency[1]}),"
+                )
+                imports.add("from plain.runtime import settings")
+            else:
+                dependencies.append(f"        {self.serialize(dependency)[0]},")
+        items["dependencies"] = "\n".join(dependencies) + "\n" if dependencies else ""
+
+        # Format imports nicely, swapping imports of functions from migration files
+        # for comments
+        migration_imports = set()
+        for line in list(imports):
+            if re.match(r"^import (.*)\.\d+[^\s]*$", line):
+                migration_imports.add(line.split("import")[1].strip())
+                imports.remove(line)
+                self.needs_manual_porting = True
+
+        imports.add("from plain.postgres import migrations")
+
+        # Sort imports by the package / module to be imported (the part after
+        # "from" in "from ... import ..." or after "import" in "import ...").
+        # First group the "import" statements, then "from ... import ...".
+        sorted_imports = sorted(
+            imports, key=lambda i: (i.split()[0] == "from", i.split()[1])
+        )
+        items["imports"] = "\n".join(sorted_imports) + "\n" if imports else ""
+        if migration_imports:
+            items["imports"] += (
+                "\n\n# Functions from the following migrations need manual "
+                "copying.\n# Move them and any dependencies into this file, "
+                "then update the\n# RunPython operations to refer to the local "
+                "versions:\n# {}"
+            ).format("\n# ".join(sorted(migration_imports)))
+        # If there's a replaces, make a string for it
+        if self.migration.replaces:
+            items["replaces_str"] = (
+                f"\n    replaces = {self.serialize(self.migration.replaces)[0]}\n"
+            )
+        # Hinting that goes into comment
+        if self.include_header:
+            items["migration_header"] = MIGRATION_HEADER_TEMPLATE % {
+                "version": __version__,
+                "timestamp": now().strftime("%Y-%m-%d %H:%M"),
+            }
+        else:
+            items["migration_header"] = ""
+
+        if self.migration.initial:
+            items["initial_str"] = "\n    initial = True\n"
+
+        return MIGRATION_TEMPLATE % items
+
+    @property
+    def basedir(self) -> str:
+        migrations_package_name, _ = MigrationLoader.migrations_module(
+            self.migration.package_label
+        )
+
+        if migrations_package_name is None:
+            raise ValueError(
+                f"Plain can't create migrations for app '{self.migration.package_label}' because "
+                "migrations have been disabled via the MIGRATION_MODULES "
+                "setting."
+            )
+
+        # See if we can import the migrations module directly
+        try:
+            migrations_module = import_module(migrations_package_name)
+        except ImportError:
+            pass
+        else:
+            try:
+                return module_dir(migrations_module)
+            except ValueError:
+                pass
+
+        # Alright, see if it's a direct submodule of the app
+        package_config = packages_registry.get_package_config(
+            self.migration.package_label
+        )
+        (
+            maybe_package_name,
+            _,
+            migrations_package_basename,
+        ) = migrations_package_name.rpartition(".")
+        if package_config.name == maybe_package_name:
+            return os.path.join(package_config.path, migrations_package_basename)
+
+        # In case of using MIGRATION_MODULES setting and the custom package
+        # doesn't exist, create one, starting from an existing package
+        existing_dirs, missing_dirs = migrations_package_name.split("."), []
+        while existing_dirs:
+            missing_dirs.insert(0, existing_dirs.pop(-1))
+            try:
+                base_module = import_module(".".join(existing_dirs))
+            except (ImportError, ValueError):
+                continue
+            else:
+                try:
+                    base_dir = module_dir(base_module)
+                except ValueError:
+                    continue
+                else:
+                    break
+        else:
+            raise ValueError(
+                "Could not locate an appropriate location to create "
+                f"migrations package {migrations_package_name}. Make sure the toplevel "
+                "package exists and can be imported."
+            )
+
+        final_dir = os.path.join(base_dir, *missing_dirs)
+        os.makedirs(final_dir, exist_ok=True)
+        for missing_dir in missing_dirs:
+            base_dir = os.path.join(base_dir, missing_dir)
+            with open(os.path.join(base_dir, "__init__.py"), "w"):
+                pass
+
+        return final_dir
+
+    @property
+    def filename(self) -> str:
+        return f"{self.migration.name}.py"
+
+    @property
+    def path(self) -> str:
+        return os.path.join(self.basedir, self.filename)
+
+    @classmethod
+    def serialize(cls, value: Any) -> tuple[str, set[str]]:
+        return serializer_factory(value).serialize()
+
+
+MIGRATION_HEADER_TEMPLATE = """\
+# Generated by Plain %(version)s on %(timestamp)s
+
+"""
+
+
+MIGRATION_TEMPLATE = """\
+%(migration_header)s%(imports)s
+
+class Migration(migrations.Migration):
+%(replaces_str)s%(initial_str)s
+    dependencies = [
+%(dependencies)s\
+    ]
+
+    operations = [
+%(operations)s\
+    ]
+"""

plain/postgres/options.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from plain.packages import packages_registry
+from plain.postgres.dialect import MAX_NAME_LENGTH
+from plain.postgres.utils import truncate_name
+
+if TYPE_CHECKING:
+    from plain.postgres.base import Model
+    from plain.postgres.constraints import BaseConstraint
+    from plain.postgres.indexes import Index
+
+
+class Options:
+    """
+    Model options descriptor and container.
+
+    Acts as both a descriptor (for lazy initialization and access control)
+    and the actual options instance (cached per model class).
+    """
+
+    # Type annotations for attributes set in _create_and_cache
+    # These exist on cached instances, not on the descriptor itself
+    model: type[Model]
+    package_label: str
+    db_table: str
+    ordering: Sequence[str]
+    indexes: Sequence[Index]
+    constraints: Sequence[BaseConstraint]
+    _provided_options: set[str]
+
+    def __init__(
+        self,
+        *,
+        db_table: str | None = None,
+        ordering: Sequence[str] | None = None,
+        indexes: Sequence[Index] | None = None,
+        constraints: Sequence[BaseConstraint] | None = None,
+        package_label: str | None = None,
+    ):
+        """
+        Initialize the descriptor with optional configuration.
+
+        This is called ONCE when defining the base Model class, or when
+        a user explicitly sets model_options = Options(...) on their model.
+        The descriptor then creates cached instances per model subclass.
+        """
+        self._config = {
+            "db_table": db_table,
+            "ordering": ordering,
+            "indexes": indexes,
+            "constraints": constraints,
+            "package_label": package_label,
+        }
+        self._cache: dict[type[Model], Options] = {}
+
+    def __get__(self, instance: Any, owner: type[Model]) -> Options:
+        """
+        Descriptor protocol - returns cached Options for the model class.
+
+        This is called when accessing Model.model_options and returns a per-class
+        cached instance created by _create_and_cache().
+
+        Can be accessed from both class and instances:
+        - MyModel.model_options (class access)
+        - my_instance.model_options (instance access - returns class's options)
+        """
+        # Allow instance access - just return the class's options
+        if instance is not None:
+            owner = instance.__class__
+
+        # Skip for the base Model class - return descriptor
+        if owner.__name__ == "Model" and owner.__module__ == "plain.postgres.base":
+            return self
+
+        # Return cached instance or create new one
+        if owner not in self._cache:
+            return self._create_and_cache(owner)
+
+        return self._cache[owner]
+
+    def _create_and_cache(self, model: type[Model]) -> Options:
+        """Create Options and cache it."""
+        # Create instance without calling __init__
+        instance = Options.__new__(Options)
+
+        # Track which options were explicitly provided by user
+        # Note: package_label is excluded because it's passed separately in migrations
+        instance._provided_options = {
+            k for k, v in self._config.items() if v is not None and k != "package_label"
+        }
+
+        instance.model = model
+
+        # Resolve package_label
+        package_label = self._config.get("package_label")
+        if package_label is None:
+            module = model.__module__
+            package_config = packages_registry.get_containing_package_config(module)
+            if package_config is None:
+                raise RuntimeError(
+                    f"Model class {module}.{model.__name__} doesn't declare an explicit "
+                    "package_label and isn't in an application in INSTALLED_PACKAGES."
+                )
+            instance.package_label = package_config.package_label
+        else:
+            instance.package_label = package_label
+
+        # Set db_table
+        db_table = self._config.get("db_table")
+        if db_table is None:
+            instance.db_table = truncate_name(
+                f"{instance.package_label}_{model.__name__.lower()}",
+                MAX_NAME_LENGTH,
+            )
+        else:
+            instance.db_table = db_table
+
+        instance.ordering = self._config.get("ordering") or []
+        instance.indexes = self._config.get("indexes") or []
+        instance.constraints = self._config.get("constraints") or []
+
+        # Format names with class interpolation
+        instance.constraints = instance._format_names_with_class(instance.constraints)
+        instance.indexes = instance._format_names_with_class(instance.indexes)
+
+        # Cache early to prevent recursion if needed
+        self._cache[model] = instance
+
+        return instance
+
+    @property
+    def object_name(self) -> str:
+        """The model class name."""
+        return self.model.__name__
+
+    @property
+    def model_name(self) -> str:
+        """The model class name in lowercase."""
+        return self.object_name.lower()
+
+    @property
+    def label(self) -> str:
+        """The model label: package_label.ClassName"""
+        return f"{self.package_label}.{self.object_name}"
+
+    @property
+    def label_lower(self) -> str:
+        """The model label in lowercase: package_label.classname"""
+        return f"{self.package_label}.{self.model_name}"
+
+    def _format_names_with_class(self, objs: list[Any]) -> list[Any]:
+        """Package label/class name interpolation for object names."""
+        new_objs = []
+        for obj in objs:
+            obj = obj.clone()
+            obj.name = obj.name % {
+                "package_label": self.package_label.lower(),
+                "class": self.model.__name__.lower(),
+            }
+            new_objs.append(obj)
+        return new_objs
+
+    def export_for_migrations(self) -> dict[str, Any]:
+        """Export user-provided options for migrations."""
+        options = {}
+        for name in self._provided_options:
+            if name == "indexes":
+                # Clone indexes and ensure names are set
+                indexes = [idx.clone() for idx in self.indexes]
+                for index in indexes:
+                    if not index.name:
+                        index.set_name_with_model(self.model)
+                options["indexes"] = indexes
+            elif name == "constraints":
+                # Clone constraints
+                options["constraints"] = [con.clone() for con in self.constraints]
+            else:
+                # Use current attribute value
+                options[name] = getattr(self, name)
+        return options
+
+    @property
+    def total_unique_constraints(self) -> list[Any]:
+        """
+        Return a list of total unique constraints. Useful for determining set
+        of fields guaranteed to be unique for all rows.
+        """
+        from plain.postgres.constraints import UniqueConstraint
+
+        return [
+            constraint
+            for constraint in self.constraints
+            if (
+                isinstance(constraint, UniqueConstraint)
+                and constraint.condition is None
+                and not constraint.contains_expressions
+            )
+        ]
+
+    def __repr__(self) -> str:
+        return f"<Options for {self.model.__name__}>"
+
+    def __str__(self) -> str:
+        return f"{self.package_label}.{self.model.__name__.lower()}"