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

plain/models/CHANGELOG.md

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

plain/models/base.py

@@ -25,7 +25,7 @@ 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.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
@@ -168,7 +168,8 @@ class ModelBase(type):
                 index.set_name_with_model(cls)
 
     @property
-    def query(cls):
+    def query(cls) -> QuerySet:
+        """Create a new QuerySet for this model."""
         return cls._meta.queryset
 
 

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",
                 )
@@ -1236,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):
@@ -1266,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
@@ -1278,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.