plain.models 0.41.1__py3-none-any.whl → 0.43.0__py3-none-any.whl

plain/models/CHANGELOG.md

@@ -1,5 +1,37 @@
 # plain-models changelog
 
+## [0.43.0](https://github.com/dropseed/plain/releases/plain-models@0.43.0) (2025-09-12)
+
+### What's changed
+
+- The `related_name` parameter is now required for ForeignKey and ManyToManyField relationships if you want a reverse accessor. The `"+"` suffix to disable reverse relations has been removed, and automatic `_set` suffixes are no longer generated ([89fa03979f](https://github.com/dropseed/plain/commit/89fa03979f))
+- Refactored related descriptors and managers for better internal organization and type safety ([9f0b03957a](https://github.com/dropseed/plain/commit/9f0b03957a))
+- Added docstrings and return type annotations to model `query` property and related manager methods for improved developer experience ([544d85b60b](https://github.com/dropseed/plain/commit/544d85b60b))
+
+### Upgrade instructions
+
+- Remove any `related_name="+"` usage - if you don't want a reverse accessor, simply omit the `related_name` parameter entirely
+- Update any code that relied on automatic `_set` suffixes - these are no longer generated, so you must use explicit `related_name` values
+- Add explicit `related_name` arguments to all ForeignKey and ManyToManyField definitions where you want reverse access (e.g., `models.ForeignKey(User, on_delete=models.CASCADE, related_name="articles")`)
+- Consider removing `related_name` arguments that are not used in practice
+
+## [0.42.0](https://github.com/dropseed/plain/releases/plain-models@0.42.0) (2025-09-12)
+
+### What's changed
+
+- The model manager interface has been renamed from `.objects` to `.query` ([037a239](https://github.com/dropseed/plain/commit/037a239ef4))
+- Manager functionality has been merged into QuerySet, simplifying the architecture - custom QuerySets can now be set directly via `Meta.queryset_class` ([bbaee93](https://github.com/dropseed/plain/commit/bbaee93839))
+- The `objects` manager is now set directly on the Model class for better type checking ([fccc5be](https://github.com/dropseed/plain/commit/fccc5be13e))
+- Database backups are now created automatically during migrations when in DEBUG mode ([c8023074](https://github.com/dropseed/plain/commit/c8023074e9))
+- Removed several legacy manager features: `default_related_name`, `base_manager_name`, `creation_counter`, `use_in_migrations`, `auto_created`, and routing hints ([multiple commits](https://github.com/dropseed/plain/compare/plain-models@0.41.1...037a239ef4))
+
+### Upgrade instructions
+
+- Replace all usage of `Model.objects` with `Model.query` in your codebase (e.g., `User.objects.filter()` becomes `User.query.filter()`)
+- If you have custom managers, convert them to custom QuerySets and set them using `Meta.queryset_class` instead of assigning to class attributes (if there is more than one custom manager on a class, invoke the new QuerySet class directly or add a shortcut on the Model using `@classmethod`)
+- Remove any usage of the removed manager features: `default_related_name`, `base_manager_name`, manager `creation_counter`, `use_in_migrations`, `auto_created`, and database routing hints
+- Any reverse accessors (typically `<related_model>_set` or defined by `related_name`) will now return a manager class for the additional `add()`, `remove()`, `clear()`, etc. methods and the regular queryset methods will be available via `.query` (e.g., `user.articles.first()` becomes `user.articles.query.first()`)
+
 ## [0.41.1](https://github.com/dropseed/plain/releases/plain-models@0.41.1) (2025-09-09)
 
 ### What's changed

plain/models/README.md

@@ -9,7 +9,7 @@
 - [Fields](#fields)
 - [Validation](#validation)
 - [Indexes and constraints](#indexes-and-constraints)
-- [Managers](#managers)
+- [Custom QuerySets](#custom-querysets)
 - [Forms](#forms)
 - [Sharing fields across models](#sharing-fields-across-models)
 - [Installation](#installation)
@@ -43,7 +43,7 @@ from .models import User
 
 
 # Create a new user
-user = User.objects.create(
+user = User.query.create(
     email="test@example.com",
     password="password",
 )
@@ -56,7 +56,7 @@ user.save()
 user.delete()
 
 # Query for users
-admin_users = User.objects.filter(is_admin=True)
+admin_users = User.query.filter(is_admin=True)
 ```
 
 ## Database connection
@@ -85,30 +85,30 @@ Multiple backends are supported, including Postgres, MySQL, and SQLite.
 
 ## Querying
 
-Models come with a powerful query API through their [`Manager`](./manager.py#Manager) interface:
+Models come with a powerful query API through their [`QuerySet`](./query.py#QuerySet) interface:
 
 ```python
 # Get all users
-all_users = User.objects.all()
+all_users = User.query.all()
 
 # Filter users
-admin_users = User.objects.filter(is_admin=True)
-recent_users = User.objects.filter(created_at__gte=datetime.now() - timedelta(days=7))
+admin_users = User.query.filter(is_admin=True)
+recent_users = User.query.filter(created_at__gte=datetime.now() - timedelta(days=7))
 
 # Get a single user
-user = User.objects.get(email="test@example.com")
+user = User.query.get(email="test@example.com")
 
 # Complex queries with Q objects
 from plain.models import Q
-users = User.objects.filter(
+users = User.query.filter(
     Q(is_admin=True) | Q(email__endswith="@example.com")
 )
 
 # Ordering
-users = User.objects.order_by("-created_at")
+users = User.query.order_by("-created_at")
 
 # Limiting results
-first_10_users = User.objects.all()[:10]
+first_10_users = User.query.all()[:10]
 ```
 
 For more advanced querying options, see the [`QuerySet`](./query.py#QuerySet) class.
@@ -211,28 +211,71 @@ class User(models.Model):
         ]
 ```
 
-## Managers
+## Custom QuerySets
 
-[`Manager`](./manager.py#Manager) objects provide the interface for querying models:
+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
+
+Use `Meta.queryset_class` to set a custom QuerySet that will be used by `Model.query`:
+
+```python
+class PublishedQuerySet(models.QuerySet):
+    def published_only(self):
+        return self.filter(status="published")
+
+    def draft_only(self):
+        return self.filter(status="draft")
+
+@models.register_model
+class Article(models.Model):
+    title = models.CharField(max_length=200)
+    status = models.CharField(max_length=20)
+
+    class Meta:
+        queryset_class = PublishedQuerySet
+
+# Usage - all methods available on Article.objects
+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:
 
 ```python
-class PublishedManager(models.Manager):
-    def get_queryset(self):
-        return super().get_queryset().filter(status="published")
+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()
+```
+
+### Using classmethods for convenience
+
+For even cleaner API, add classmethods to your model:
+
+```python
+@models.register_model
 class Article(models.Model):
     title = models.CharField(max_length=200)
     status = models.CharField(max_length=20)
 
-    # Default manager
-    objects = models.Manager()
+    @classmethod
+    def published(cls):
+        return PublishedQuerySet(model=cls).published_only()
 
-    # Custom manager
-    published = PublishedManager()
+    @classmethod
+    def drafts(cls):
+        return PublishedQuerySet(model=cls).draft_only()
 
 # Usage
-all_articles = Article.objects.all()
-published_articles = Article.published.all()
+published_articles = Article.published()
+draft_articles = Article.drafts()
 ```
 
 ## Forms

plain/models/__init__.py

@@ -59,7 +59,6 @@ from .fields.json import JSONField
 from .indexes import *  # NOQA
 from .indexes import __all__ as indexes_all
 from .lookups import Lookup, Transform
-from .manager import Manager
 from .query import Prefetch, QuerySet, prefetch_related_objects
 from .query_utils import FilteredRelation, Q
 from .registry import models_registry, register_model
@@ -108,7 +107,6 @@ __all__ += [
     "JSONField",
     "Lookup",
     "Transform",
-    "Manager",
     "Prefetch",
     "Q",
     "QuerySet",

plain/models/base.py

@@ -24,9 +24,8 @@ from plain.models.deletion import Collector
 from plain.models.expressions import RawSQL, Value
 from plain.models.fields import NOT_PROVIDED
 from plain.models.fields.reverse_related import ForeignObjectRel
-from plain.models.manager import Manager
 from plain.models.options import Options
-from plain.models.query import F, Q
+from plain.models.query import F, Q, QuerySet
 from plain.packages import packages_registry
 from plain.utils.encoding import force_str
 from plain.utils.hashable import make_hashable
@@ -75,7 +74,7 @@ class ModelBase(type):
         new_class._add_exceptions()
 
         # Now go back over all the attrs on this class see if they have a contribute_to_class() method.
-        # Attributes with contribute_to_class are fields, meta options, and managers.
+        # Attributes with contribute_to_class are fields and meta options.
         for attr_name, attr_value in inspect.getmembers(new_class):
             if attr_name.startswith("_"):
                 continue
@@ -161,16 +160,6 @@ class ModelBase(type):
                 ", ".join(f.name for f in opts.fields),
             )
 
-        if not opts.managers:
-            if any(f.name == "objects" for f in opts.fields):
-                raise ValueError(
-                    f"Model {cls.__name__} must specify a custom Manager, because it has a "
-                    "field named 'objects'."
-                )
-            manager = Manager()
-            manager.auto_created = True
-            cls.add_to_class("objects", manager)
-
         # Set the name of _meta.indexes. This can't be done in
         # Options.contribute_to_class() because fields haven't been added to
         # the model at that point.
@@ -179,12 +168,9 @@ class ModelBase(type):
                 index.set_name_with_model(cls)
 
     @property
-    def _base_manager(cls):
-        return cls._meta.base_manager
-
-    @property
-    def _default_manager(cls):
-        return cls._meta.default_manager
+    def query(cls) -> QuerySet:
+        """Create a new QuerySet for this model."""
+        return cls._meta.queryset
 
 
 class ModelStateFieldsCacheDescriptor:
@@ -207,6 +193,9 @@ class ModelState:
 
 
 class Model(metaclass=ModelBase):
+    DoesNotExist: type[ObjectDoesNotExist]
+    MultipleObjectsReturned: type[MultipleObjectsReturned]
+
     def __init__(self, *args, **kwargs):
         # Alias some things as locals to avoid repeat global lookups
         cls = self.__class__
@@ -434,7 +423,7 @@ class Model(metaclass=ModelBase):
                     "are not allowed in fields."
                 )
 
-        db_instance_qs = self.__class__._base_manager.get_queryset().filter(id=self.id)
+        db_instance_qs = self.__class__._meta.base_queryset.filter(id=self.id)
 
         # Use provided fields, if not set then reload all non-deferred fields.
         deferred_fields = self.get_deferred_fields()
@@ -617,7 +606,7 @@ class Model(metaclass=ModelBase):
             force_insert = True
         # If possible, try an UPDATE. If that doesn't update anything, do an INSERT.
         if id_set and not force_insert:
-            base_qs = cls._base_manager
+            base_qs = meta.base_queryset
             values = [
                 (
                     f,
@@ -641,7 +630,7 @@ class Model(metaclass=ModelBase):
                 fields = [f for f in fields if f is not id_field]
 
             returning_fields = meta.db_returning_fields
-            results = self._do_insert(cls._base_manager, fields, returning_fields, raw)
+            results = self._do_insert(meta.base_queryset, fields, returning_fields, raw)
             if results:
                 for value, field in zip(results[0], returning_fields):
                     setattr(self, field.attname, value)
@@ -738,7 +727,7 @@ class Model(metaclass=ModelBase):
         q = Q.create([(field.name, param), (f"id__{op}", self.id)], connector=Q.AND)
         q = Q.create([q, (f"{field.name}__{op}", param)], connector=Q.OR)
         qs = (
-            self.__class__._default_manager.filter(**kwargs)
+            self.__class__.query.filter(**kwargs)
             .filter(q)
             .order_by(f"{order}{field.name}", f"{order}id")
         )
@@ -836,7 +825,7 @@ class Model(metaclass=ModelBase):
             if len(unique_check) != len(lookup_kwargs):
                 continue
 
-            qs = model_class._default_manager.filter(**lookup_kwargs)
+            qs = model_class.query.filter(**lookup_kwargs)
 
             # Exclude the current object from the query if we are editing an
             # instance (as opposed to creating a new one)
@@ -995,9 +984,7 @@ class Model(metaclass=ModelBase):
 
     @classmethod
     def check(cls, **kwargs):
-        errors = [
-            *cls._check_managers(**kwargs),
-        ]
+        errors = []
 
         database = kwargs.get("database", False)
         errors += [
@@ -1045,14 +1032,6 @@ class Model(metaclass=ModelBase):
             )
         return errors
 
-    @classmethod
-    def _check_managers(cls, **kwargs):
-        """Perform all manager checks."""
-        errors = []
-        for manager in cls._meta.managers:
-            errors.extend(manager.check(**kwargs))
-        return errors
-
     @classmethod
     def _check_fields(cls, **kwargs):
         """Perform all field checks."""

plain/models/cli.py

@@ -479,7 +479,7 @@ def migrate(
                 "Migrations can be pruned only when a package is specified."
             )
         if verbosity > 0:
-            click.echo("Pruning migrations:", color="cyan")
+            click.secho("Pruning migrations:", fg="cyan")
         to_prune = set(executor.loader.applied_migrations) - set(
             executor.loader.disk_migrations
         )
@@ -529,16 +529,16 @@ def migrate(
     migration_plan = executor.migration_plan(targets)
 
     if plan:
-        click.echo("Planned operations:", color="cyan")
+        click.secho("Planned operations:", fg="cyan")
         if not migration_plan:
             click.echo("  No planned migration operations.")
         else:
             for migration in migration_plan:
-                click.echo(str(migration), color="cyan")
+                click.secho(str(migration), fg="cyan")
                 for operation in migration.operations:
                     message, is_error = describe_operation(operation)
                     if is_error:
-                        click.echo("    " + message, fg="yellow")
+                        click.secho("    " + message, fg="yellow")
                     else:
                         click.echo("    " + message)
         if check_unapplied:
@@ -555,18 +555,18 @@ def migrate(
 
     # Print some useful info
     if verbosity >= 1:
-        click.echo("Operations to perform:", color="cyan")
+        click.secho("Operations to perform:", fg="cyan")
 
         if target_package_labels_only:
-            click.echo(
+            click.secho(
                 "  Apply all migrations: "
                 + (", ".join(sorted({a for a, n in targets})) or "(none)"),
-                color="yellow",
+                fg="yellow",
             )
         else:
-            click.echo(
+            click.secho(
                 f"  Target specific migration: {targets[0][1]}, from {targets[0][0]}",
-                color="yellow",
+                fg="yellow",
             )
 
     pre_migrate_state = executor._create_project_state(with_applied_migrations=True)
@@ -575,30 +575,24 @@ def migrate(
     # pprint(sql)
 
     if migration_plan:
-        if backup or (
-            backup is None
-            and settings.DEBUG
-            and (
-                no_input
-                or click.confirm(
-                    "\nYou are in DEBUG mode. Would you like to make a database backup before running migrations?",
-                    default=True,
-                )
-            )
-        ):
+        if backup or (backup is None and settings.DEBUG):
             backup_name = f"migrate_{time.strftime('%Y%m%d_%H%M%S')}"
+            click.secho(
+                f"Creating backup before applying migrations: {backup_name}",
+                bold=True,
+            )
             # Can't use ctx.invoke because this is called by the test db creation currently,
             # which doesn't have a context.
             create_backup.callback(
                 backup_name=backup_name,
                 pg_dump=os.environ.get(
                     "PG_DUMP", "pg_dump"
-                ),  # Have to this again manually
+                ),  # Have to pass this in manually
             )
             print()
 
         if verbosity >= 1:
-            click.echo("Running migrations:", color="cyan")
+            click.secho("Running migrations:", fg="cyan")
 
         post_migrate_state = executor.migrate(
             targets,

plain/models/constraints.py

@@ -347,7 +347,7 @@ class UniqueConstraint(BaseConstraint):
         return path, self.expressions, kwargs
 
     def validate(self, model, instance, exclude=None):
-        queryset = model._default_manager
+        queryset = model.query
         if self.fields:
             lookup_kwargs = {}
             for field_name in self.fields:

plain/models/deletion.py

@@ -352,7 +352,7 @@ class Collector:
             [(f"{related_field.name}__in", objs) for related_field in related_fields],
             connector=query_utils.Q.OR,
         )
-        return related_model._base_manager.filter(predicate)
+        return related_model._meta.base_queryset.filter(predicate)
 
     def sort(self):
         sorted_models = []

plain/models/fields/__init__.py

@@ -901,7 +901,7 @@ class Field(RegisterLookupMixin):
             if hasattr(self.remote_field, "get_related_field")
             else "id"
         )
-        qs = rel_model._default_manager.complex_filter(limit_choices_to)
+        qs = rel_model.query.complex_filter(limit_choices_to)
         if ordering:
             qs = qs.order_by(*ordering)
         return (blank_choice if include_blank else []) + [

plain/models/fields/related.py

@@ -12,8 +12,9 @@ from . import Field
 from .mixins import FieldCacheMixin
 from .related_descriptors import (
     ForeignKeyDeferredAttribute,
+    ForwardManyToManyDescriptor,
     ForwardManyToOneDescriptor,
-    ManyToManyDescriptor,
+    ReverseManyToManyDescriptor,
     ReverseManyToOneDescriptor,
 )
 from .related_lookups import (
@@ -123,14 +124,11 @@ class RelatedField(FieldCacheMixin, Field):
         is_valid_id = (
             not keyword.iskeyword(related_name) and related_name.isidentifier()
         )
-        if not (is_valid_id or related_name.endswith("+")):
+        if not is_valid_id:
             return [
                 preflight.Error(
                     f"The name '{self.remote_field.related_name}' is invalid related_name for field {self.model._meta.object_name}.{self.name}",
-                    hint=(
-                        "Related name must be a valid Python identifier or end with a "
-                        "'+'"
-                    ),
+                    hint="Related name must be a valid Python identifier.",
                     obj=self,
                     id="fields.E306",
                 )
@@ -310,9 +308,6 @@ class RelatedField(FieldCacheMixin, Field):
 
         if self.remote_field.related_name:
             related_name = self.remote_field.related_name
-        else:
-            related_name = self.opts.default_related_name
-        if related_name:
             related_name %= {
                 "class": cls.__name__.lower(),
                 "model_name": cls._meta.model_name.lower(),
@@ -672,7 +667,7 @@ class ForeignKey(RelatedField):
         if value is None:
             return
 
-        qs = self.remote_field.model._base_manager.filter(
+        qs = self.remote_field.model._meta.base_queryset.filter(
             **{self.remote_field.field_name: value}
         )
         qs = qs.complex_filter(self.get_limit_choices_to())
@@ -1239,26 +1234,6 @@ class ManyToManyField(RelatedField):
         return getattr(self, cache_attr)
 
     def contribute_to_class(self, cls, name, **kwargs):
-        # To support multiple relations to self, it's useful to have a non-None
-        # related name on symmetrical relations for internal reasons. The
-        # concept doesn't make a lot of sense externally ("you want me to
-        # specify *what* on my non-reversible relation?!"), so we set it up
-        # automatically. The funky name reduces the chance of an accidental
-        # clash.
-        if self.remote_field.symmetrical and (
-            self.remote_field.model == RECURSIVE_RELATIONSHIP_CONSTANT
-            or self.remote_field.model == cls._meta.object_name
-        ):
-            self.remote_field.related_name = f"{name}_rel_+"
-        elif self.remote_field.is_hidden():
-            # If the backwards relation is disabled, replace the original
-            # related_name with one generated from the m2m field name. Plain
-            # still uses backwards relations internally and we need to avoid
-            # clashes between multiple m2m fields with related_name == '+'.
-            self.remote_field.related_name = (
-                f"_{cls._meta.package_label}_{cls.__name__.lower()}_{name}_+"
-            )
-
         super().contribute_to_class(cls, name, **kwargs)
 
         def resolve_through_model(_, model, field):
@@ -1269,7 +1244,7 @@ class ManyToManyField(RelatedField):
         )
 
         # Add the descriptor for the m2m relation.
-        setattr(cls, self.name, ManyToManyDescriptor(self.remote_field, reverse=False))
+        setattr(cls, self.name, ForwardManyToManyDescriptor(self.remote_field))
 
         # Set up the accessor for the m2m table name for the relation.
         self.m2m_db_table = self._get_m2m_db_table
@@ -1281,7 +1256,7 @@ class ManyToManyField(RelatedField):
             setattr(
                 cls,
                 related.get_accessor_name(),
-                ManyToManyDescriptor(self.remote_field, reverse=True),
+                ReverseManyToManyDescriptor(self.remote_field),
             )
 
         # Set up the accessors for the column names on the m2m table.