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

plain/models/migrations/utils.py

@@ -1,30 +1,39 @@
+from __future__ import annotations
+
 import datetime
 import re
 from collections import namedtuple
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any
 
 from plain.models.fields.related import RECURSIVE_RELATIONSHIP_CONSTANT
 
+if TYPE_CHECKING:
+    from plain.models.fields import Field
+
 FieldReference = namedtuple("FieldReference", "to through")
 
 COMPILED_REGEX_TYPE = type(re.compile(""))
 
 
 class RegexObject:
-    def __init__(self, obj):
+    def __init__(self, obj: Any) -> None:
         self.pattern = obj.pattern
         self.flags = obj.flags
 
-    def __eq__(self, other):
+    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():
+def get_migration_name_timestamp() -> str:
     return datetime.datetime.now().strftime("%Y%m%d_%H%M")
 
 
-def resolve_relation(model, package_label=None, model_name=None):
+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.
 
@@ -51,12 +60,12 @@ def resolve_relation(model, package_label=None, model_name=None):
 
 
 def field_references(
-    model_tuple,
-    field,
-    reference_model_tuple,
-    reference_field_name=None,
-    reference_field=None,
-):
+    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.
@@ -97,7 +106,9 @@ def field_references(
     return FieldReference(references_to, references_through)
 
 
-def get_references(state, model_tuple, field_tuple=()):
+def get_references(
+    state: Any, model_tuple: tuple[str, str], field_tuple: tuple[Any, ...] = ()
+) -> Generator[tuple[Any, str, Field, FieldReference], None, None]:
     """
     Generator of (model_state, name, field, reference) referencing
     provided context.
@@ -108,12 +119,17 @@ def get_references(state, model_tuple, field_tuple=()):
     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
+                state_model_tuple,
+                field,
+                model_tuple,
+                *field_tuple,  # type: ignore[arg-type]
             )
             if reference:
                 yield model_state, name, field, reference
 
 
-def field_is_referenced(state, model_tuple, field_tuple):
+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/models/migrations/writer.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import os
 import re
 from importlib import import_module
+from typing import Any
 
 from plain.models import migrations
 from plain.models.migrations.loader import MigrationLoader
@@ -14,13 +17,13 @@ from plain.utils.timezone import now
 
 
 class OperationWriter:
-    def __init__(self, operation, indentation=2):
+    def __init__(self, operation: Any, indentation: int = 2) -> None:
         self.operation = operation
-        self.buff = []
+        self.buff: list[str] = []
         self.indentation = indentation
 
-    def serialize(self):
-        def _write(_arg_name, _arg_value):
+    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
             ):
@@ -100,16 +103,16 @@ class OperationWriter:
         self.feed("),")
         return self.render(), imports
 
-    def indent(self):
+    def indent(self) -> None:
         self.indentation += 1
 
-    def unindent(self):
+    def unindent(self) -> None:
         self.indentation -= 1
 
-    def feed(self, line):
+    def feed(self, line: str) -> None:
         self.buff.append(" " * (self.indentation * 4) + line)
 
-    def render(self):
+    def render(self) -> str:
         return "\n".join(self.buff)
 
 
@@ -119,12 +122,12 @@ class MigrationWriter:
     of the migration file from it.
     """
 
-    def __init__(self, migration, include_header=True):
+    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):
+    def as_string(self) -> str:
         """Return a string of the file contents."""
         items = {
             "replaces_str": "",
@@ -198,7 +201,7 @@ class MigrationWriter:
         return MIGRATION_TEMPLATE % items
 
     @property
-    def basedir(self):
+    def basedir(self) -> str:
         migrations_package_name, _ = MigrationLoader.migrations_module(
             self.migration.package_label
         )
@@ -266,15 +269,15 @@ class MigrationWriter:
         return final_dir
 
     @property
-    def filename(self):
+    def filename(self) -> str:
         return f"{self.migration.name}.py"
 
     @property
-    def path(self):
+    def path(self) -> str:
         return os.path.join(self.basedir, self.filename)
 
     @classmethod
-    def serialize(cls, value):
+    def serialize(cls, value: Any) -> tuple[str, set[str]]:
         return serializer_factory(value).serialize()
 
 

plain/models/options.py

@@ -1,7 +1,10 @@
+from __future__ import annotations
+
 import bisect
 import inspect
 from collections import defaultdict
 from functools import cached_property
+from typing import TYPE_CHECKING, Any
 
 from plain.models import models_registry
 from plain.models.constraints import UniqueConstraint
@@ -10,6 +13,10 @@ from plain.models.exceptions import FieldDoesNotExist
 from plain.models.query import QuerySet
 from plain.utils.datastructures import ImmutableList
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.fields import Field
+
 PROXY_PARENTS = object()
 
 EMPTY_RELATION_TREE = ()
@@ -33,7 +40,7 @@ DEFAULT_NAMES = (
 )
 
 
-def make_immutable_fields_list(name, data):
+def make_immutable_fields_list(name: str, data: Any) -> ImmutableList:
     return ImmutableList(data, warning=IMMUTABLE_WARNING % name)
 
 
@@ -52,43 +59,43 @@ class Options:
 
     default_models_registry = models_registry
 
-    def __init__(self, meta, package_label=None):
-        self._get_fields_cache = {}
-        self.local_fields = []
-        self.local_many_to_many = []
-        self.queryset_class = None
-        self.model_name = None
-        self.db_table = ""
-        self.db_table_comment = ""
-        self.ordering = []
-        self.indexes = []
-        self.constraints = []
-        self.object_name = None
-        self.package_label = package_label
-        self.required_db_features = []
-        self.required_db_vendor = None
-        self.meta = meta
+    def __init__(self, meta: Any, package_label: str | None = None):
+        self._get_fields_cache: dict[tuple[bool, bool, bool, bool], Any] = {}
+        self.local_fields: list[Field] = []
+        self.local_many_to_many: list[Field] = []
+        self.queryset_class: type[QuerySet] | None = None
+        self.model_name: str | None = None
+        self.db_table: str = ""
+        self.db_table_comment: str = ""
+        self.ordering: list[Any] = []
+        self.indexes: list[Any] = []
+        self.constraints: list[Any] = []
+        self.object_name: str | None = None
+        self.package_label: str | None = package_label
+        self.required_db_features: list[str] = []
+        self.required_db_vendor: str | None = None
+        self.meta: Any = meta
 
         # List of all lookups defined in ForeignKey 'limit_choices_to' options
         # from *other* models. Needed for some admin checks. Internal use only.
-        self.related_fkey_lookups = []
+        self.related_fkey_lookups: list[Any] = []
 
         # A custom app registry to use, if you're making a separate model set.
-        self.models_registry = self.default_models_registry
+        self.models_registry: Any = self.default_models_registry
 
     @property
-    def label(self):
+    def label(self) -> str:
         return f"{self.package_label}.{self.object_name}"
 
     @property
-    def label_lower(self):
+    def label_lower(self) -> str:
         return f"{self.package_label}.{self.model_name}"
 
-    def contribute_to_class(self, cls, name):
+    def contribute_to_class(self, cls: type[Any], name: str) -> None:
         from plain.models.backends.utils import truncate_name
 
         cls._meta = self
-        self.model = cls
+        self.model: type[Any] = cls
         # First, construct the default values for these options.
         self.object_name = cls.__name__
         self.model_name = self.object_name.lower()
@@ -138,7 +145,7 @@ class Options:
                 db_connection.ops.max_name_length(),
             )
 
-    def _format_names_with_class(self, cls, objs):
+    def _format_names_with_class(self, cls: type[Any], objs: list[Any]) -> list[Any]:
         """Package label/class name interpolation for object names."""
         new_objs = []
         for obj in objs:
@@ -150,7 +157,7 @@ class Options:
             new_objs.append(obj)
         return new_objs
 
-    def add_field(self, field):
+    def add_field(self, field: Field) -> None:
         # Insert the given field in the order in which it was created, using
         # the "creation_counter" attribute of the field.
         # Move many-to-many related fields from self.fields into
@@ -181,13 +188,13 @@ class Options:
         else:
             self._expire_cache(reverse=False)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Options for {self.object_name}>"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.label_lower
 
-    def can_migrate(self, connection):
+    def can_migrate(self, connection: BaseDatabaseWrapper) -> bool:
         """
         Return True if the model can/should be migrated on the given
         `connection` object.
@@ -202,7 +209,7 @@ class Options:
         return True
 
     @property
-    def base_queryset(self):
+    def base_queryset(self) -> QuerySet:
         """
         The base queryset is used by Plain's internal operations like cascading
         deletes, migrations, and related object lookups. It provides access to
@@ -216,13 +223,13 @@ class Options:
         return QuerySet(model=self.model)
 
     @property
-    def queryset(self):
+    def queryset(self) -> QuerySet:
         if self.queryset_class:
             return self.queryset_class(model=self.model)
         return QuerySet(model=self.model)
 
     @cached_property
-    def fields(self):
+    def fields(self) -> ImmutableList:
         """
         Return a list of all forward fields on the model and its parents,
         excluding ManyToManyFields.
@@ -239,13 +246,13 @@ class Options:
         # use that property directly because related_model is a cached property,
         # and all the models may not have been loaded yet; we don't want to cache
         # the string reference to the related_model.
-        def is_not_an_m2m_field(f):
+        def is_not_an_m2m_field(f: Any) -> bool:
             return not (f.is_relation and f.many_to_many)
 
-        def is_not_a_generic_relation(f):
+        def is_not_a_generic_relation(f: Any) -> bool:
             return not (f.is_relation and f.one_to_many)
 
-        def is_not_a_generic_foreign_key(f):
+        def is_not_a_generic_foreign_key(f: Any) -> bool:
             return not (
                 f.is_relation
                 and f.many_to_one
@@ -264,7 +271,7 @@ class Options:
         )
 
     @cached_property
-    def concrete_fields(self):
+    def concrete_fields(self) -> ImmutableList:
         """
         Return a list of all concrete fields on the model and its parents.
 
@@ -277,7 +284,7 @@ class Options:
         )
 
     @cached_property
-    def local_concrete_fields(self):
+    def local_concrete_fields(self) -> ImmutableList:
         """
         Return a list of all concrete fields on the model.
 
@@ -290,7 +297,7 @@ class Options:
         )
 
     @cached_property
-    def many_to_many(self):
+    def many_to_many(self) -> ImmutableList:
         """
         Return a list of all many to many fields on the model and its parents.
 
@@ -308,7 +315,7 @@ class Options:
         )
 
     @cached_property
-    def related_objects(self):
+    def related_objects(self) -> ImmutableList:
         """
         Return all related objects pointing to the current model. The related
         objects can come from a one-to-one, one-to-many, or many-to-many field
@@ -331,7 +338,7 @@ class Options:
         )
 
     @cached_property
-    def _forward_fields_map(self):
+    def _forward_fields_map(self) -> dict[str, Any]:
         res = {}
         fields = self._get_fields(reverse=False)
         for field in fields:
@@ -346,7 +353,7 @@ class Options:
         return res
 
     @cached_property
-    def fields_map(self):
+    def fields_map(self) -> dict[str, Any]:
         res = {}
         fields = self._get_fields(forward=False, include_hidden=True)
         for field in fields:
@@ -360,7 +367,7 @@ class Options:
                 pass
         return res
 
-    def get_field(self, field_name):
+    def get_field(self, field_name: str) -> Any:
         """
         Return a field instance given the name of a forward or reverse field.
         """
@@ -387,14 +394,14 @@ class Options:
                 f"{self.object_name} has no field named '{field_name}'"
             )
 
-    def _populate_directed_relation_graph(self):
+    def _populate_directed_relation_graph(self) -> Any:
         """
         This method is used by each model to find its reverse objects. As this
         method is very expensive and is accessed frequently (it looks up every
         field in a model, in every app), it is computed on first access and then
         is set as a property on every model.
         """
-        related_objects_graph = defaultdict(list)
+        related_objects_graph: defaultdict[str, list[Any]] = defaultdict(list)
 
         all_models = self.models_registry.get_models()
         for model in all_models:
@@ -423,10 +430,10 @@ class Options:
         return self.__dict__.get("_relation_tree", EMPTY_RELATION_TREE)
 
     @cached_property
-    def _relation_tree(self):
+    def _relation_tree(self) -> Any:
         return self._populate_directed_relation_graph()
 
-    def _expire_cache(self, forward=True, reverse=True):
+    def _expire_cache(self, forward: bool = True, reverse: bool = True) -> None:
         # This method is usually called by packages.cache_clear(), when the
         # registry is finalized, or when a new field is added.
         if forward:
@@ -439,7 +446,7 @@ class Options:
                     delattr(self, cache_key)
         self._get_fields_cache = {}
 
-    def get_fields(self, include_hidden=False):
+    def get_fields(self, include_hidden: bool = False) -> ImmutableList:
         """
         Return a list of fields associated to the model. By default, include
         forward and reverse fields, fields derived from inheritance, but not
@@ -452,11 +459,11 @@ class Options:
 
     def _get_fields(
         self,
-        forward=True,
-        reverse=True,
-        include_hidden=False,
-        seen_models=None,
-    ):
+        forward: bool = True,
+        reverse: bool = True,
+        include_hidden: bool = False,
+        seen_models: set[type[Any]] | None = None,
+    ) -> ImmutableList:
         """
         Internal helper function to return fields of the model.
         * If forward=True, then fields defined on this model are returned.
@@ -471,7 +478,7 @@ class Options:
         # We must keep track of which models we have already seen. Otherwise we
         # could include the same field multiple times from different models.
         topmost_call = seen_models is None
-        if topmost_call:
+        if seen_models is None:
             seen_models = set()
         seen_models.add(self.model)
 
@@ -511,7 +518,7 @@ class Options:
         return fields
 
     @cached_property
-    def total_unique_constraints(self):
+    def total_unique_constraints(self) -> list[UniqueConstraint]:
         """
         Return a list of total unique constraints. Useful for determining set
         of fields guaranteed to be unique for all rows.
@@ -527,7 +534,7 @@ class Options:
         ]
 
     @cached_property
-    def _property_names(self):
+    def _property_names(self) -> frozenset[str]:
         """Return a set of the names of the properties defined on the model."""
         names = []
         for name in dir(self.model):
@@ -537,7 +544,7 @@ class Options:
         return frozenset(names)
 
     @cached_property
-    def _non_pk_concrete_field_names(self):
+    def _non_pk_concrete_field_names(self) -> frozenset[str]:
         """
         Return a set of the non-primary key concrete field names defined on the model.
         """
@@ -550,7 +557,7 @@ class Options:
         return frozenset(names)
 
     @cached_property
-    def db_returning_fields(self):
+    def db_returning_fields(self) -> list[Field]:
         """
         Private API intended only to be used by Plain itself.
         Fields to be returned after a database insert.

plain/models/otel.py

@@ -1,10 +1,18 @@
+from __future__ import annotations
+
 import re
 import traceback
+from collections.abc import Generator
 from contextlib import contextmanager
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from opentelemetry import context as otel_context
 from opentelemetry import trace
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span
+
+    from plain.models.backends.base.base import BaseDatabaseWrapper
 from opentelemetry.semconv._incubating.attributes.db_attributes import (
     DB_QUERY_PARAMETER_TEMPLATE,
     DB_USER,
@@ -99,7 +107,9 @@ def _clean_identifier(identifier: str) -> str:
 
 
 @contextmanager
-def db_span(db, sql: Any, *, many: bool = False, params=None):
+def db_span(
+    db: BaseDatabaseWrapper, sql: Any, *, many: bool = False, params: Any = None
+) -> Generator[Span | None, None, None]:
     """Open an OpenTelemetry CLIENT span for a database query.
 
     All common attributes (`db.*`, `network.*`, etc.) are set automatically.
@@ -107,7 +117,7 @@ def db_span(db, sql: Any, *, many: bool = False, params=None):
     """
 
     # Fast-exit if instrumentation suppression flag set in context.
-    if otel_context.get_value(_SUPPRESS_KEY):
+    if otel_context.get_value(_SUPPRESS_KEY):  # type: ignore[arg-type]
         yield None
         return
 
@@ -177,15 +187,15 @@ def db_span(db, sql: Any, *, many: bool = False, params=None):
 
 
 @contextmanager
-def suppress_db_tracing():
-    token = otel_context.attach(otel_context.set_value(_SUPPRESS_KEY, True))
+def suppress_db_tracing() -> Generator[None, None, None]:
+    token = otel_context.attach(otel_context.set_value(_SUPPRESS_KEY, True))  # type: ignore[arg-type]
     try:
         yield
     finally:
         otel_context.detach(token)
 
 
-def _get_code_attributes():
+def _get_code_attributes() -> dict[str, Any]:
     """Extract code context attributes for the current database query.
 
     Returns a dict of OpenTelemetry code attributes.