plain.models 0.49.1__py3-none-any.whl → 0.50.0__py3-none-any.whl

plain/models/migrations/graph.py

@@ -1,9 +1,15 @@
+from __future__ import annotations
+
 from functools import total_ordering
+from typing import TYPE_CHECKING, Any
 
 from plain.models.migrations.state import ProjectState
 
 from .exceptions import CircularDependencyError, NodeNotFoundError
 
+if TYPE_CHECKING:
+    from plain.models.migrations.migration import Migration
+
 
 @total_ordering
 class Node:
@@ -12,33 +18,33 @@ class Node:
     nodes in either direction.
     """
 
-    def __init__(self, key):
+    def __init__(self, key: tuple[str, str]):
         self.key = key
-        self.children = set()
-        self.parents = set()
+        self.children: set[Node] = set()
+        self.parents: set[Node] = set()
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return self.key == other
 
-    def __lt__(self, other):
+    def __lt__(self, other: object) -> bool:
         return self.key < other
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.key)
 
-    def __getitem__(self, item):
+    def __getitem__(self, item: int) -> str:
         return self.key[item]
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self.key)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: ({self.key[0]!r}, {self.key[1]!r})>"
 
-    def add_child(self, child):
+    def add_child(self, child: Node) -> None:
         self.children.add(child)
 
-    def add_parent(self, parent):
+    def add_parent(self, parent: Node) -> None:
         self.parents.add(parent)
 
 
@@ -51,12 +57,14 @@ class DummyNode(Node):
     If there are any left, a nonexistent dependency error is raised.
     """
 
-    def __init__(self, key, origin, error_message):
+    def __init__(
+        self, key: tuple[str, str], origin: tuple[str, str], error_message: str
+    ):
         super().__init__(key)
         self.origin = origin
         self.error_message = error_message
 
-    def raise_error(self):
+    def raise_error(self) -> None:
         raise NodeNotFoundError(self.error_message, self.key, origin=self.origin)
 
 
@@ -84,21 +92,29 @@ class MigrationGraph:
     """
 
     def __init__(self):
-        self.node_map = {}
-        self.nodes = {}
+        self.node_map: dict[tuple[str, str], Node] = {}
+        self.nodes: dict[tuple[str, str], Migration | None] = {}
 
-    def add_node(self, key, migration):
+    def add_node(self, key: tuple[str, str], migration: Migration) -> None:
         assert key not in self.node_map
         node = Node(key)
         self.node_map[key] = node
         self.nodes[key] = migration
 
-    def add_dummy_node(self, key, origin, error_message):
+    def add_dummy_node(
+        self, key: tuple[str, str], origin: tuple[str, str], error_message: str
+    ) -> None:
         node = DummyNode(key, origin, error_message)
         self.node_map[key] = node
         self.nodes[key] = None
 
-    def add_dependency(self, migration, child, parent, skip_validation=False):
+    def add_dependency(
+        self,
+        migration: tuple[str, str] | None,
+        child: tuple[str, str],
+        parent: tuple[str, str],
+        skip_validation: bool = False,
+    ) -> None:
         """
         This may create dummy nodes if they don't yet exist. If
         `skip_validation=True`, validate_consistency() should be called
@@ -109,26 +125,28 @@ class MigrationGraph:
                 f"Migration {migration} dependencies reference nonexistent"
                 f" child node {child!r}"
             )
-            self.add_dummy_node(child, migration, error_message)
+            self.add_dummy_node(child, migration, error_message)  # type: ignore[arg-type]
         if parent not in self.nodes:
             error_message = (
                 f"Migration {migration} dependencies reference nonexistent"
                 f" parent node {parent!r}"
             )
-            self.add_dummy_node(parent, migration, error_message)
+            self.add_dummy_node(parent, migration, error_message)  # type: ignore[arg-type]
         self.node_map[child].add_parent(self.node_map[parent])
         self.node_map[parent].add_child(self.node_map[child])
         if not skip_validation:
             self.validate_consistency()
 
-    def remove_replaced_nodes(self, replacement, replaced):
+    def remove_replaced_nodes(
+        self, replacement: tuple[str, str], replaced: list[tuple[str, str]]
+    ) -> None:
         """
         Remove each of the `replaced` nodes (when they exist). Any
         dependencies that were referencing them are changed to reference the
         `replacement` node instead.
         """
         # Cast list of replaced keys to set to speed up lookup later.
-        replaced = set(replaced)
+        replaced_set: set[tuple[str, str]] = set(replaced)
         try:
             replacement_node = self.node_map[replacement]
         except KeyError as err:
@@ -137,7 +155,7 @@ class MigrationGraph:
                 " to the migration graph, or has been removed.",
                 replacement,
             ) from err
-        for replaced_key in replaced:
+        for replaced_key in replaced_set:
             self.nodes.pop(replaced_key, None)
             replaced_node = self.node_map.pop(replaced_key, None)
             if replaced_node:
@@ -146,17 +164,19 @@ class MigrationGraph:
                     # We don't want to create dependencies between the replaced
                     # node and the replacement node as this would lead to
                     # self-referencing on the replacement node at a later iteration.
-                    if child.key not in replaced:
+                    if child.key not in replaced_set:
                         replacement_node.add_child(child)
                         child.add_parent(replacement_node)
                 for parent in replaced_node.parents:
                     parent.children.remove(replaced_node)
                     # Again, to avoid self-referencing.
-                    if parent.key not in replaced:
+                    if parent.key not in replaced_set:
                         replacement_node.add_parent(parent)
                         parent.add_child(replacement_node)
 
-    def remove_replacement_node(self, replacement, replaced):
+    def remove_replacement_node(
+        self, replacement: tuple[str, str], replaced: list[tuple[str, str]]
+    ) -> None:
         """
         The inverse operation to `remove_replaced_nodes`. Almost. Remove the
         replacement node `replacement` and remap its child nodes to `replaced`
@@ -172,8 +192,8 @@ class MigrationGraph:
                 " to the migration graph, or has been removed already.",
                 replacement,
             ) from err
-        replaced_nodes = set()
-        replaced_nodes_parents = set()
+        replaced_nodes: set[Node] = set()
+        replaced_nodes_parents: set[Node] = set()
         for key in replaced:
             replaced_node = self.node_map.get(key)
             if replaced_node:
@@ -192,11 +212,11 @@ class MigrationGraph:
             # NOTE: There is no need to remap parent dependencies as we can
             # assume the replaced nodes already have the correct ancestry.
 
-    def validate_consistency(self):
+    def validate_consistency(self) -> None:
         """Ensure there are no dummy nodes remaining in the graph."""
         [n.raise_error() for n in self.node_map.values() if isinstance(n, DummyNode)]
 
-    def forwards_plan(self, target):
+    def forwards_plan(self, target: tuple[str, str]) -> list[tuple[str, str]]:
         """
         Given a node, return a list of which previous nodes (dependencies) must
         be applied, ending with the node itself. This is the list you would
@@ -206,11 +226,13 @@ class MigrationGraph:
             raise NodeNotFoundError(f"Node {target!r} not a valid node", target)
         return self.iterative_dfs(self.node_map[target])
 
-    def iterative_dfs(self, start, forwards=True):
+    def iterative_dfs(
+        self, start: Node, forwards: bool = True
+    ) -> list[tuple[str, str]]:
         """Iterative depth-first search for finding dependencies."""
-        visited = []
-        visited_set = set()
-        stack = [(start, False)]
+        visited: list[tuple[str, str]] = []
+        visited_set: set[Node] = set()
+        stack: list[tuple[Node, bool]] = [(start, False)]
         while stack:
             node, processed = stack.pop()
             if node in visited_set:
@@ -226,12 +248,12 @@ class MigrationGraph:
                 ]
         return visited
 
-    def root_nodes(self, app=None):
+    def root_nodes(self, app: str | None = None) -> list[tuple[str, str]]:
         """
         Return all root nodes - that is, nodes with no dependencies inside
         their app. These are the starting point for an app.
         """
-        roots = set()
+        roots: set[tuple[str, str]] = set()
         for node in self.nodes:
             if all(key[0] != node[0] for key in self.node_map[node].parents) and (
                 not app or app == node[0]
@@ -239,7 +261,7 @@ class MigrationGraph:
                 roots.add(node)
         return sorted(roots)
 
-    def leaf_nodes(self, app=None):
+    def leaf_nodes(self, app: str | None = None) -> list[tuple[str, str]]:
         """
         Return all leaf nodes - that is, nodes with no dependents in their app.
         These are the "most current" version of an app's schema.
@@ -247,7 +269,7 @@ class MigrationGraph:
         gets handled further up, in the interactive command - it's usually the
         result of a VCS merge and needs some user input.
         """
-        leaves = set()
+        leaves: set[tuple[str, str]] = set()
         for node in self.nodes:
             if all(key[0] != node[0] for key in self.node_map[node].children) and (
                 not app or app == node[0]
@@ -255,13 +277,13 @@ class MigrationGraph:
                 leaves.add(node)
         return sorted(leaves)
 
-    def ensure_not_cyclic(self):
+    def ensure_not_cyclic(self) -> None:
         # Algo from GvR:
         # https://neopythonic.blogspot.com/2009/01/detecting-cycles-in-directed-graph.html
-        todo = set(self.nodes)
+        todo: set[tuple[str, str]] = set(self.nodes)
         while todo:
             node = todo.pop()
-            stack = [node]
+            stack: list[tuple[str, str]] = [node]
             while stack:
                 top = stack[-1]
                 for child in self.node_map[top].children:
@@ -280,27 +302,34 @@ class MigrationGraph:
                 else:
                     node = stack.pop()
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "Graph: {} nodes, {} edges".format(*self._nodes_and_edges())
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         nodes, edges = self._nodes_and_edges()
         return f"<{self.__class__.__name__}: nodes={nodes}, edges={edges}>"
 
-    def _nodes_and_edges(self):
+    def _nodes_and_edges(self) -> tuple[int, int]:
         return len(self.nodes), sum(
             len(node.parents) for node in self.node_map.values()
         )
 
-    def _generate_plan(self, nodes, at_end):
-        plan = []
+    def _generate_plan(
+        self, nodes: list[tuple[str, str]], at_end: bool
+    ) -> list[tuple[str, str]]:
+        plan: list[tuple[str, str]] = []
         for node in nodes:
             for migration in self.forwards_plan(node):
                 if migration not in plan and (at_end or migration not in nodes):
                     plan.append(migration)
         return plan
 
-    def make_state(self, nodes=None, at_end=True, real_packages=None):
+    def make_state(
+        self,
+        nodes: tuple[str, str] | list[tuple[str, str]] | None = None,
+        at_end: bool = True,
+        real_packages: Any = None,
+    ) -> ProjectState:
         """
         Given a migration node or nodes, return a complete ProjectState for it.
         If at_end is False, return the state before the migration has run.
@@ -311,12 +340,12 @@ class MigrationGraph:
         if not nodes:
             return ProjectState()
         if not isinstance(nodes[0], tuple):
-            nodes = [nodes]
+            nodes = [nodes]  # type: ignore[list-item]
         plan = self._generate_plan(nodes, at_end)
         project_state = ProjectState(real_packages=real_packages)
         for node in plan:
-            project_state = self.nodes[node].mutate_state(project_state, preserve=False)
+            project_state = self.nodes[node].mutate_state(project_state, preserve=False)  # type: ignore[union-attr]
         return project_state
 
-    def __contains__(self, node):
+    def __contains__(self, node: tuple[str, str]) -> bool:
         return node in self.nodes

plain/models/migrations/loader.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import pkgutil
 import sys
 from importlib import import_module, reload
+from typing import TYPE_CHECKING, Any
 
 from plain.models.migrations.graph import MigrationGraph
 from plain.models.migrations.recorder import MigrationRecorder
@@ -13,6 +16,10 @@ from .exceptions import (
     NodeNotFoundError,
 )
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.migrations.migration import Migration
+
 MIGRATIONS_MODULE_NAME = "migrations"
 
 
@@ -43,21 +50,25 @@ class MigrationLoader:
 
     def __init__(
         self,
-        connection,
-        load=True,
-        ignore_no_migrations=False,
-        replace_migrations=True,
+        connection: BaseDatabaseWrapper | None,
+        load: bool = True,
+        ignore_no_migrations: bool = False,
+        replace_migrations: bool = True,
     ):
         self.connection = connection
-        self.disk_migrations = None
-        self.applied_migrations = None
+        self.disk_migrations: dict[tuple[str, str], Migration] | None = None
+        self.applied_migrations: dict[tuple[str, str], Any] | None = None
         self.ignore_no_migrations = ignore_no_migrations
         self.replace_migrations = replace_migrations
+        self.unmigrated_packages: set[str]
+        self.migrated_packages: set[str]
+        self.graph: MigrationGraph
+        self.replacements: dict[tuple[str, str], Migration]
         if load:
             self.build_graph()
 
     @classmethod
-    def migrations_module(cls, package_label):
+    def migrations_module(cls, package_label: str) -> tuple[str | None, bool]:
         """
         Return the path to the migrations module for the specified package_label
         and a boolean indicating if the module is specified in
@@ -71,7 +82,7 @@ class MigrationLoader:
         app = packages_registry.get_package_config(package_label)
         return f"{app.name}.{MIGRATIONS_MODULE_NAME}", False
 
-    def load_disk(self):
+    def load_disk(self) -> None:
         """Load the migrations from all INSTALLED_PACKAGES from disk."""
         self.disk_migrations = {}
         self.unmigrated_packages = set()
@@ -87,7 +98,9 @@ class MigrationLoader:
                 module = import_module(module_name)
             except ModuleNotFoundError as e:
                 if (explicit and self.ignore_no_migrations) or (
-                    not explicit and MIGRATIONS_MODULE_NAME in e.name.split(".")
+                    not explicit
+                    and e.name is not None
+                    and MIGRATIONS_MODULE_NAME in e.name.split(".")
                 ):
                     self.unmigrated_packages.add(package_config.package_label)
                     continue
@@ -132,17 +145,19 @@ class MigrationLoader:
                         f"Migration {migration_name} in app {package_config.package_label} has no Migration class"
                     )
                 self.disk_migrations[package_config.package_label, migration_name] = (
-                    migration_module.Migration(
+                    migration_module.Migration(  # type: ignore[call-non-callable]
                         migration_name,
                         package_config.package_label,
                     )
                 )
 
-    def get_migration(self, package_label, name_prefix):
+    def get_migration(self, package_label: str, name_prefix: str) -> Migration | None:
         """Return the named migration or raise NodeNotFoundError."""
         return self.graph.nodes[package_label, name_prefix]
 
-    def get_migration_by_prefix(self, package_label, name_prefix):
+    def get_migration_by_prefix(
+        self, package_label: str, name_prefix: str
+    ) -> Migration:
         """
         Return the migration(s) which match the given app label and name_prefix.
         """
@@ -165,7 +180,9 @@ class MigrationLoader:
         else:
             return self.disk_migrations[results[0]]
 
-    def check_key(self, key, current_package):
+    def check_key(
+        self, key: tuple[str, str], current_package: str
+    ) -> tuple[str, str] | None:
         if (key[1] != "__first__" and key[1] != "__latest__") or key in self.graph:
             return key
         # Special-case __first__, which means "the first migration" for
@@ -174,12 +191,12 @@ class MigrationLoader:
         # migrations.
         if key[0] == current_package:
             # Ignore __first__ references to the same app (#22325)
-            return
+            return None
         if key[0] in self.unmigrated_packages:
             # This app isn't migrated, but something depends on it.
             # The models will get auto-added into the state, though
             # so we're fine.
-            return
+            return None
         if key[0] in self.migrated_packages:
             try:
                 if key[1] == "__first__":
@@ -193,7 +210,9 @@ class MigrationLoader:
                     raise ValueError(f"Dependency on app with no migrations: {key[0]}")
         raise ValueError(f"Dependency on unknown app: {key[0]}")
 
-    def add_internal_dependencies(self, key, migration):
+    def add_internal_dependencies(
+        self, key: tuple[str, str], migration: Migration
+    ) -> None:
         """
         Internal dependencies need to be added first to ensure `__first__`
         dependencies find the correct root node.
@@ -203,7 +222,9 @@ class MigrationLoader:
             if parent[0] == key[0] and parent[1] != "__first__":
                 self.graph.add_dependency(migration, key, parent, skip_validation=True)
 
-    def add_external_dependencies(self, key, migration):
+    def add_external_dependencies(
+        self, key: tuple[str, str], migration: Migration
+    ) -> None:
         for parent in migration.dependencies:
             # Skip internal dependencies
             if key[0] == parent[0]:
@@ -212,7 +233,7 @@ class MigrationLoader:
             if parent is not None:
                 self.graph.add_dependency(migration, key, parent, skip_validation=True)
 
-    def build_graph(self):
+    def build_graph(self) -> None:
         """
         Build a migration dependency graph using both the disk and database.
         You'll need to rebuild the graph if you apply migrations. This isn't
@@ -295,7 +316,7 @@ class MigrationLoader:
             raise
         self.graph.ensure_not_cyclic()
 
-    def check_consistent_history(self, connection):
+    def check_consistent_history(self, connection: BaseDatabaseWrapper) -> None:
         """
         Raise InconsistentMigrationHistory if any applied migrations have
         unapplied dependencies.
@@ -320,7 +341,7 @@ class MigrationLoader:
                         f"{parent[0]}.{parent[1]} on the database."
                     )
 
-    def detect_conflicts(self):
+    def detect_conflicts(self) -> dict[str, list[str]]:
         """
         Look through the loaded graph and detect any conflicts - packages
         with more than one leaf migration. Return a dict of the app labels
@@ -337,7 +358,9 @@ class MigrationLoader:
             for package_label in conflicting_packages
         }
 
-    def project_state(self, nodes=None, at_end=True):
+    def project_state(
+        self, nodes: tuple[str, str] | None = None, at_end: bool = True
+    ) -> Any:
         """
         Return a ProjectState object representing the most recent state
         that the loaded migrations represent.
@@ -348,7 +371,7 @@ class MigrationLoader:
             nodes=nodes, at_end=at_end, real_packages=self.unmigrated_packages
         )
 
-    def collect_sql(self, plan):
+    def collect_sql(self, plan: list[Migration]) -> list[str]:
         """
         Take a migration plan and return a list of collected SQL statements
         that represent the best-efforts version of that plan.

plain/models/migrations/migration.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import re
+from typing import Any
 
 from plain.models.migrations.utils import get_migration_name_timestamp
 from plain.models.transaction import atomic
@@ -22,29 +25,29 @@ class Migration:
     """
 
     # Operations to apply during this migration, in order.
-    operations = []
+    operations: list[Any] = []
 
     # Other migrations that should be run before this migration.
     # Should be a list of (app, migration_name).
-    dependencies = []
+    dependencies: list[tuple[str, str]] = []
 
     # Migration names in this app that this migration replaces. If this is
     # non-empty, this migration will only be applied if all these migrations
     # are not applied.
-    replaces = []
+    replaces: list[str] = []
 
     # Is this an initial migration? Initial migrations are skipped on
     # --fake-initial if the table or fields already exist. If None, check if
     # the migration has any dependencies to determine if there are dependencies
     # to tell if db introspection needs to be done. If True, always perform
     # introspection. If False, never perform introspection.
-    initial = None
+    initial: bool | None = None
 
     # Whether to wrap the whole migration in a transaction. Only has an effect
     # on database backends which support transactional DDL.
-    atomic = True
+    atomic: bool = True
 
-    def __init__(self, name, package_label):
+    def __init__(self, name: str, package_label: str) -> None:
         self.name = name
         self.package_label = package_label
         # Copy dependencies & other attrs as we might mutate them at runtime
@@ -52,23 +55,23 @@ class Migration:
         self.dependencies = list(self.__class__.dependencies)
         self.replaces = list(self.__class__.replaces)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, Migration)
             and self.name == other.name
             and self.package_label == other.package_label
         )
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Migration {self.package_label}.{self.name}>"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.package_label}.{self.name}"
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(f"{self.package_label}.{self.name}")
 
-    def mutate_state(self, project_state, preserve=True):
+    def mutate_state(self, project_state: Any, preserve: bool = True) -> Any:
         """
         Take a ProjectState and return a new one with the migration's
         operations applied to it. Preserve the original object state by
@@ -82,7 +85,9 @@ class Migration:
             operation.state_forwards(self.package_label, new_state)
         return new_state
 
-    def apply(self, project_state, schema_editor, collect_sql=False):
+    def apply(
+        self, project_state: Any, schema_editor: Any, collect_sql: bool = False
+    ) -> Any:
         """
         Take a project_state representing all migrations prior to this one
         and a schema_editor for a live database and apply the migration
@@ -127,7 +132,7 @@ class Migration:
                 schema_editor.collected_sql.append("-- (no-op)")
         return project_state
 
-    def suggest_name(self):
+    def suggest_name(self) -> str:
         """
         Suggest a name for the operations this migration might represent. Names
         are not guaranteed to be unique, but put some effort into the fallback
@@ -152,18 +157,18 @@ class Migration:
         return name
 
 
-class SettingsTuple(tuple):
+class SettingsTuple(tuple):  # type: ignore[type-arg]
     """
     Subclass of tuple so Plain can tell this was originally a settings
     dependency when it reads the migration file.
     """
 
-    def __new__(cls, value, setting):
+    def __new__(cls, value: tuple[str, str], setting: str) -> SettingsTuple:
         self = tuple.__new__(cls, value)
-        self.setting = setting
-        return self
+        self.setting = setting  # type: ignore[attr-defined]
+        return self  # type: ignore[return-value]
 
 
-def settings_dependency(value):
+def settings_dependency(value: str) -> SettingsTuple:
     """Turn a setting value into a dependency."""
     return SettingsTuple((value.split(".", 1)[0], "__first__"), value)