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

plain/models/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

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/backends/base/creation.py

@@ -98,7 +98,7 @@ class BaseDatabaseCreation:
     #                 and package_config.package_label in loader.migrated_packages
     #             ):
     #                 for model in package_config.get_models():
-    #                     if model._meta.can_migrate(
+    #                     if model.model_options.can_migrate(
     #                         self.connection
     #                     ) and router.allow_migrate_model(self.connection.alias, model):
     #                         queryset = model._base_manager.using(
@@ -127,7 +127,7 @@ class BaseDatabaseCreation:
     #                 "json", data, using=self.connection.alias
     #             ):
     #                 obj.save()
-    #                 table_names.add(obj.object.__class__._meta.db_table)
+    #                 table_names.add(obj.object.model_options.db_table)
     #         # Manually check for any invalid keys that might have been added,
     #         # because constraint checks were disabled.
     #         self.connection.check_constraints(table_names=table_names)

plain/models/backends/base/introspection.py

@@ -94,7 +94,7 @@ class BaseDatabaseIntrospection:
             for model in models_registry.get_models(
                 package_label=package_config.package_label
             )
-            if model._meta.can_migrate(self.connection)
+            if model.model_options.can_migrate(self.connection)
         )
 
     def plain_table_names(
@@ -108,8 +108,10 @@ class BaseDatabaseIntrospection:
         """
         tables = set()
         for model in self.get_migratable_models():
-            tables.add(model._meta.db_table)
-            tables.update(f.m2m_db_table() for f in model._meta.local_many_to_many)
+            tables.add(model.model_options.db_table)
+            tables.update(
+                f.m2m_db_table() for f in model._model_meta.local_many_to_many
+            )
         tables = list(tables)
         if only_existing:
             existing_tables = set(self.table_names(include_views=include_views))
@@ -128,7 +130,9 @@ class BaseDatabaseIntrospection:
             for model in self.get_migratable_models():
                 sequence_list.extend(
                     self.get_sequences(
-                        cursor, model._meta.db_table, model._meta.local_fields
+                        cursor,
+                        model.model_options.db_table,
+                        model._model_meta.local_fields,
                     )
                 )
         return sequence_list