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

plain/models/CHANGELOG.md

@@ -1,5 +1,32 @@
 # plain-models changelog
 
+## [0.51.0](https://github.com/dropseed/plain/releases/plain-models@0.51.0) (2025-10-07)
+
+### What's changed
+
+- Model metadata has been split into two separate descriptors: `model_options` for user-defined configuration and `_model_meta` for internal metadata ([73ba469](https://github.com/dropseed/plain/commit/73ba469ba0), [17a378d](https://github.com/dropseed/plain/commit/17a378dcfb))
+- The `_meta` attribute has been replaced with `model_options` for user-defined options like indexes, constraints, and database settings ([17a378d](https://github.com/dropseed/plain/commit/17a378dcfb))
+- Custom QuerySets are now assigned directly to the `query` class attribute instead of using `Meta.queryset_class` ([2578301](https://github.com/dropseed/plain/commit/2578301819))
+- Added comprehensive type improvements to model metadata and related fields for better IDE support ([3b477a0](https://github.com/dropseed/plain/commit/3b477a0d43))
+
+### Upgrade instructions
+
+- Replace `Meta.queryset_class = CustomQuerySet` with `query = CustomQuerySet()` as a class attribute on your models
+- Replace `class Meta:` with `model_options = models.Options(...)` in your models
+
+## [0.50.0](https://github.com/dropseed/plain/releases/plain-models@0.50.0) (2025-10-06)
+
+### What's changed
+
+- Added comprehensive type annotations throughout plain-models, improving IDE support and type checking capabilities ([ea1a7df](https://github.com/dropseed/plain/commit/ea1a7df622), [f49ee32](https://github.com/dropseed/plain/commit/f49ee32a90), [369353f](https://github.com/dropseed/plain/commit/369353f9d6), [13b7d16](https://github.com/dropseed/plain/commit/13b7d16f8d), [e23a0ca](https://github.com/dropseed/plain/commit/e23a0cae7c), [02d8551](https://github.com/dropseed/plain/commit/02d85518f0))
+- The `QuerySet` class is now generic and the `model` parameter is now required in the `__init__` method ([719e792](https://github.com/dropseed/plain/commit/719e792c96))
+- Database wrapper classes have been renamed for consistency: `DatabaseWrapper` classes are now named `MySQLDatabaseWrapper`, `PostgreSQLDatabaseWrapper`, and `SQLiteDatabaseWrapper` ([5a39e85](https://github.com/dropseed/plain/commit/5a39e851e5))
+- The plain-models package now has 100% type annotation coverage and is validated in CI to prevent regressions
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.49.2](https://github.com/dropseed/plain/releases/plain-models@0.49.2) (2025-10-02)
 
 ### What's changed

plain/models/README.md

@@ -200,31 +200,32 @@ class User(models.Model):
     username = models.CharField(max_length=150)
     age = models.IntegerField()
 
-    class Meta:
-        indexes = [
+    model_options = models.Options(
+        indexes=[
             models.Index(fields=["email"]),
             models.Index(fields=["-created_at"], name="user_created_idx"),
-        ]
-        constraints = [
+        ],
+        constraints=[
             models.UniqueConstraint(fields=["email", "username"], name="unique_user"),
             models.CheckConstraint(check=models.Q(age__gte=0), name="age_positive"),
-        ]
+        ],
+    )
 ```
 
 ## Custom QuerySets
 
-With the Manager functionality now merged into QuerySet, you can customize [`QuerySet`](./query.py#QuerySet) classes to provide specialized query methods. There are several ways to use custom QuerySets:
-
-### Setting a default QuerySet for a model
+With the Manager functionality now merged into QuerySet, you can customize [`QuerySet`](./query.py#QuerySet) classes to provide specialized query methods.
 
-Use `Meta.queryset_class` to set a custom QuerySet that will be used by `Model.query`:
+Define a custom QuerySet and assign it to your model's `query` attribute:
 
 ```python
-class PublishedQuerySet(models.QuerySet):
-    def published_only(self):
+from typing import Self
+
+class PublishedQuerySet(models.QuerySet["Article"]):
+    def published_only(self) -> Self:
         return self.filter(status="published")
 
-    def draft_only(self):
+    def draft_only(self) -> Self:
         return self.filter(status="draft")
 
 @models.register_model
@@ -232,50 +233,33 @@ class Article(models.Model):
     title = models.CharField(max_length=200)
     status = models.CharField(max_length=20)
 
-    class Meta:
-        queryset_class = PublishedQuerySet
+    query = PublishedQuerySet()
 
-# Usage - all methods available on Article.objects
+# Usage - all methods available on Article.query
 all_articles = Article.query.all()
 published_articles = Article.query.published_only()
 draft_articles = Article.query.draft_only()
 ```
 
-### Using custom QuerySets without formal attachment
-
-You can also use custom QuerySets manually without setting them as the default:
+Custom methods can be chained with built-in QuerySet methods:
 
 ```python
-class SpecialQuerySet(models.QuerySet):
-    def special_filter(self):
-        return self.filter(special=True)
-
-# Create and use the QuerySet manually
-special_qs = SpecialQuerySet(model=Article)
-special_articles = special_qs.special_filter()
+# Chaining works naturally
+recent_published = Article.query.published_only().order_by("-created_at")[:10]
 ```
 
-### Using classmethods for convenience
+### Programmatic QuerySet usage
 
-For even cleaner API, add classmethods to your model:
+For internal code that needs to create QuerySet instances programmatically, use `from_model()`:
 
 ```python
-@models.register_model
-class Article(models.Model):
-    title = models.CharField(max_length=200)
-    status = models.CharField(max_length=20)
-
-    @classmethod
-    def published(cls):
-        return PublishedQuerySet(model=cls).published_only()
-
-    @classmethod
-    def drafts(cls):
-        return PublishedQuerySet(model=cls).draft_only()
+class SpecialQuerySet(models.QuerySet["Article"]):
+    def special_filter(self) -> Self:
+        return self.filter(special=True)
 
-# Usage
-published_articles = Article.published()
-draft_articles = Article.drafts()
+# Create and use the QuerySet programmatically
+special_qs = SpecialQuerySet.from_model(Article)
+special_articles = special_qs.special_filter()
 ```
 
 ## Forms

plain/models/__init__.py

@@ -63,6 +63,7 @@ from .registry import models_registry, register_model
 
 # Imports that would create circular imports if sorted
 from .base import DEFERRED, Model  # isort:skip
+from .options import Options  # isort:skip
 from .fields.related import (  # isort:skip
     ForeignKey,
     ManyToManyField,
@@ -104,6 +105,7 @@ __all__ += [
     "JSONField",
     "Lookup",
     "Transform",
+    "Options",
     "Prefetch",
     "Q",
     "QuerySet",

plain/models/aggregates.py

@@ -1,6 +1,6 @@
-"""
-Classes to represent the definitions of aggregate functions.
-"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
 
 from plain.models.exceptions import FieldError, FullResultSet
 from plain.models.expressions import Case, Func, Star, Value, When
@@ -11,6 +11,12 @@ from plain.models.functions.mixins import (
     NumericOutputFieldMixin,
 )
 
+if TYPE_CHECKING:
+    from plain.models.backends.base.base import BaseDatabaseWrapper
+    from plain.models.expressions import Expression
+    from plain.models.query_utils import Q
+    from plain.models.sql.compiler import SQLCompiler
+
 __all__ = [
     "Aggregate",
     "Avg",
@@ -33,8 +39,13 @@ class Aggregate(Func):
     empty_result_set_value = None
 
     def __init__(
-        self, *expressions, distinct=False, filter=None, default=None, **extra
-    ):
+        self,
+        *expressions: Any,
+        distinct: bool = False,
+        filter: Q | Expression | None = None,
+        default: Any = None,
+        **extra: Any,
+    ) -> None:
         if distinct and not self.allow_distinct:
             raise TypeError(f"{self.__class__.__name__} does not allow distinct.")
         if default is not None and self.empty_result_set_value is not None:
@@ -44,23 +55,28 @@ class Aggregate(Func):
         self.default = default
         super().__init__(*expressions, **extra)
 
-    def get_source_fields(self):
+    def get_source_fields(self) -> list[Any]:
         # Don't return the filter expression since it's not a source field.
         return [e._output_field_or_none for e in super().get_source_expressions()]
 
-    def get_source_expressions(self):
+    def get_source_expressions(self) -> list[Expression]:
         source_expressions = super().get_source_expressions()
         if self.filter:
             return source_expressions + [self.filter]
         return source_expressions
 
-    def set_source_expressions(self, exprs):
+    def set_source_expressions(self, exprs: list[Expression]) -> list[Expression]:
         self.filter = self.filter and exprs.pop()
         return super().set_source_expressions(exprs)
 
     def resolve_expression(
-        self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False
-    ):
+        self,
+        query: Any = None,
+        allow_joins: bool = True,
+        reuse: Any = None,
+        summarize: bool = False,
+        for_save: bool = False,
+    ) -> Expression:
         # Aggregates are not allowed in UPDATE queries, so ignore for_save
         c = super().resolve_expression(query, allow_joins, reuse, summarize)
         c.filter = c.filter and c.filter.resolve_expression(
@@ -95,16 +111,21 @@ class Aggregate(Func):
         return coalesce
 
     @property
-    def default_alias(self):
+    def default_alias(self) -> str:
         expressions = self.get_source_expressions()
         if len(expressions) == 1 and hasattr(expressions[0], "name"):
             return f"{expressions[0].name}__{self.name.lower()}"
         raise TypeError("Complex expressions require an alias")
 
-    def get_group_by_cols(self):
+    def get_group_by_cols(self) -> list[Any]:
         return []
 
-    def as_sql(self, compiler, connection, **extra_context):
+    def as_sql(
+        self,
+        compiler: SQLCompiler,
+        connection: BaseDatabaseWrapper,
+        **extra_context: Any,
+    ) -> tuple[str, tuple[Any, ...]]:
         extra_context["distinct"] = "DISTINCT " if self.distinct else ""
         if self.filter:
             if connection.features.supports_aggregate_filter_clause:
@@ -135,7 +156,7 @@ class Aggregate(Func):
                 )
         return super().as_sql(compiler, connection, **extra_context)
 
-    def _get_repr_options(self):
+    def _get_repr_options(self) -> dict[str, Any]:
         options = super()._get_repr_options()
         if self.distinct:
             options["distinct"] = self.distinct
@@ -157,7 +178,9 @@ class Count(Aggregate):
     allow_distinct = True
     empty_result_set_value = 0
 
-    def __init__(self, expression, filter=None, **extra):
+    def __init__(
+        self, expression: Any, filter: Q | Expression | None = None, **extra: Any
+    ) -> None:
         if expression == "*":
             expression = Star()
         if isinstance(expression, Star) and filter is not None:
@@ -178,11 +201,11 @@ class Min(Aggregate):
 class StdDev(NumericOutputFieldMixin, Aggregate):
     name = "StdDev"
 
-    def __init__(self, expression, sample=False, **extra):
+    def __init__(self, expression: Any, sample: bool = False, **extra: Any) -> None:
         self.function = "STDDEV_SAMP" if sample else "STDDEV_POP"
         super().__init__(expression, **extra)
 
-    def _get_repr_options(self):
+    def _get_repr_options(self) -> dict[str, Any]:
         return {**super()._get_repr_options(), "sample": self.function == "STDDEV_SAMP"}
 
 
@@ -195,9 +218,9 @@ class Sum(FixDurationInputMixin, Aggregate):
 class Variance(NumericOutputFieldMixin, Aggregate):
     name = "Variance"
 
-    def __init__(self, expression, sample=False, **extra):
+    def __init__(self, expression: Any, sample: bool = False, **extra: Any) -> None:
         self.function = "VAR_SAMP" if sample else "VAR_POP"
         super().__init__(expression, **extra)
 
-    def _get_repr_options(self):
+    def _get_repr_options(self) -> dict[str, Any]:
         return {**super()._get_repr_options(), "sample": self.function == "VAR_SAMP"}