plain.models 0.48.0__tar.gz → 0.49.0__tar.gz

{plain_models-0.48.0 → plain_models-0.49.0}/.gitignore

@@ -15,3 +15,4 @@ plain*/tests/.plain
 .plain
 
 .vscode
+/.claude

{plain_models-0.48.0 → plain_models-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.models
-Version: 0.48.0
+Version: 0.49.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/CHANGELOG.md

@@ -1,5 +1,21 @@
 # plain-models changelog
 
+## [0.49.0](https://github.com/dropseed/plain/releases/plain-models@0.49.0) (2025-09-29)
+
+### What's changed
+
+- Model exceptions (`FieldDoesNotExist`, `FieldError`, `ObjectDoesNotExist`, `MultipleObjectsReturned`, `EmptyResultSet`, `FullResultSet`) have been moved from `plain.exceptions` to `plain.models.exceptions` ([1c02564](https://github.com/dropseed/plain/commit/1c02564561))
+- The `get_FOO_display()` methods for fields with choices have been replaced with a single `get_field_display(field_name)` method ([e796e71](https://github.com/dropseed/plain/commit/e796e71e02))
+- The `get_next_by_*` and `get_previous_by_*` methods for date fields have been removed ([3a5b8a8](https://github.com/dropseed/plain/commit/3a5b8a89d1))
+- The `id` primary key field is now defined directly on the Model base class instead of being added dynamically via Options ([e164dc7](https://github.com/dropseed/plain/commit/e164dc7982))
+- Model `DoesNotExist` and `MultipleObjectsReturned` exceptions now use descriptors for better performance ([8f54ea3](https://github.com/dropseed/plain/commit/8f54ea3a62))
+
+### Upgrade instructions
+
+- Update imports for model exceptions from `plain.exceptions` to `plain.models.exceptions` (e.g., `from plain.exceptions import ObjectDoesNotExist` becomes `from plain.models.exceptions import ObjectDoesNotExist`)
+- Replace any usage of `instance.get_FOO_display()` with `instance.get_field_display("FOO")` where FOO is the field name
+- Remove any usage of `get_next_by_*` and `get_previous_by_*` methods - use QuerySet ordering instead (e.g., `Model.query.filter(date__gt=obj.date).order_by("date").first()`)
+
 ## [0.48.0](https://github.com/dropseed/plain/releases/plain-models@0.48.0) (2025-09-26)
 
 ### What's changed

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/__init__.py

@@ -1,5 +1,3 @@
-from plain.exceptions import ObjectDoesNotExist
-
 from . import (
     preflight,  # noqa
 )
@@ -78,7 +76,6 @@ from .fields.reverse_related import (  # isort:skip
 
 __all__ = aggregates_all + constraints_all + enums_all + fields_all + indexes_all
 __all__ += [
-    "ObjectDoesNotExist",
     "CASCADE",
     "DO_NOTHING",
     "PROTECT",

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/aggregates.py

@@ -2,7 +2,7 @@
 Classes to represent the definitions of aggregate functions.
 """
 
-from plain.exceptions import FieldError, FullResultSet
+from plain.models.exceptions import FieldError, FullResultSet
 from plain.models.expressions import Case, Func, Star, Value, When
 from plain.models.fields import IntegerField
 from plain.models.functions.comparison import Coalesce

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/backends/mysql/compiler.py

@@ -1,4 +1,4 @@
-from plain.exceptions import FieldError, FullResultSet
+from plain.models.exceptions import FieldError, FullResultSet
 from plain.models.expressions import Col
 from plain.models.sql import compiler
 

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/backends/sqlite3/operations.py

@@ -4,10 +4,10 @@ import uuid
 from functools import cached_property, lru_cache
 
 from plain import models
-from plain.exceptions import FieldError
 from plain.models.backends.base.operations import BaseDatabaseOperations
 from plain.models.constants import OnConflict
 from plain.models.db import DatabaseError, NotSupportedError
+from plain.models.exceptions import FieldError
 from plain.models.expressions import Col
 from plain.utils import timezone
 from plain.utils.dateparse import parse_date, parse_datetime, parse_time

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/base.py

@@ -4,13 +4,7 @@ import warnings
 from itertools import chain
 
 import plain.runtime
-from plain.exceptions import (
-    NON_FIELD_ERRORS,
-    FieldDoesNotExist,
-    MultipleObjectsReturned,
-    ObjectDoesNotExist,
-    ValidationError,
-)
+from plain.exceptions import NON_FIELD_ERRORS, ValidationError
 from plain.models import models_registry, transaction
 from plain.models.constants import LOOKUP_SEP
 from plain.models.constraints import CheckConstraint, UniqueConstraint
@@ -20,8 +14,13 @@ from plain.models.db import (
     db_connection,
 )
 from plain.models.deletion import Collector
+from plain.models.exceptions import (
+    DoesNotExistDescriptor,
+    FieldDoesNotExist,
+    MultipleObjectsReturnedDescriptor,
+)
 from plain.models.expressions import RawSQL, Value
-from plain.models.fields import NOT_PROVIDED
+from plain.models.fields import NOT_PROVIDED, PrimaryKeyField
 from plain.models.fields.reverse_related import ForeignObjectRel
 from plain.models.options import Options
 from plain.models.query import F, Q, QuerySet
@@ -42,11 +41,6 @@ class Deferred:
 DEFERRED = Deferred()
 
 
-def _has_contribute_to_class(value):
-    # Only call contribute_to_class() if it's bound.
-    return not inspect.isclass(value) and hasattr(value, "contribute_to_class")
-
-
 class ModelBase(type):
     """Metaclass for all models."""
 
@@ -71,7 +65,6 @@ class ModelBase(type):
         new_class = super().__new__(cls, name, bases, attrs, **kwargs)
 
         new_class._setup_meta()
-        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 and meta options.
@@ -79,7 +72,9 @@ class ModelBase(type):
             if attr_name.startswith("_"):
                 continue
 
-            if _has_contribute_to_class(attr_value):
+            if not inspect.isclass(attr_value) and hasattr(
+                attr_value, "contribute_to_class"
+            ):
                 if attr_name not in attrs:
                     # If the field came from an inherited class/mixin,
                     # we need to make a copy of it to avoid altering the
@@ -87,25 +82,17 @@ class ModelBase(type):
                     field = copy.deepcopy(attr_value)
                 else:
                     field = attr_value
-                new_class.add_to_class(attr_name, field)
-
-        new_class._meta.concrete_model = new_class
-
-        # Copy indexes so that index names are unique when models extend another class.
-        new_class._meta.indexes = [
-            copy.deepcopy(idx) for idx in new_class._meta.indexes
-        ]
+                field.contribute_to_class(new_class, attr_name)
 
-        new_class._prepare()
+        # 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.
+        for index in new_class._meta.indexes:
+            if not index.name:
+                index.set_name_with_model(new_class)
 
         return new_class
 
-    def add_to_class(cls, name, value):
-        if _has_contribute_to_class(value):
-            value.contribute_to_class(cls, name)
-        else:
-            setattr(cls, name, value)
-
     def _setup_meta(cls):
         name = cls.__name__
         module = cls.__module__
@@ -127,45 +114,7 @@ class ModelBase(type):
             else:
                 package_label = package_config.package_label
 
-        cls.add_to_class("_meta", Options(meta, package_label))
-
-    def _add_exceptions(cls):
-        cls.DoesNotExist = type(
-            "DoesNotExist",
-            (ObjectDoesNotExist,),
-            {
-                "__module__": cls.__module__,
-                "__qualname__": f"{cls.__qualname__}.DoesNotExist",
-            },
-        )
-
-        cls.MultipleObjectsReturned = type(
-            "MultipleObjectsReturned",
-            (MultipleObjectsReturned,),
-            {
-                "__module__": cls.__module__,
-                "__qualname__": f"{cls.__qualname__}.MultipleObjectsReturned",
-            },
-        )
-
-    def _prepare(cls):
-        """Create some methods once self._meta has been populated."""
-        opts = cls._meta
-        opts._prepare(cls)
-
-        # Give the class a docstring -- its definition.
-        if cls.__doc__ is None:
-            cls.__doc__ = "{}({})".format(
-                cls.__name__,
-                ", ".join(f.name for f in opts.fields),
-            )
-
-        # 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.
-        for index in cls._meta.indexes:
-            if not index.name:
-                index.set_name_with_model(cls)
+        Options(meta, package_label).contribute_to_class(cls, "_meta")
 
     @property
     def query(cls) -> QuerySet:
@@ -194,8 +143,13 @@ class ModelState:
 
 class Model(metaclass=ModelBase):
     _meta: Options
-    DoesNotExist: type[ObjectDoesNotExist]
-    MultipleObjectsReturned: type[MultipleObjectsReturned]
+
+    # Use descriptors for exception classes instead of metaclass generation
+    DoesNotExist = DoesNotExistDescriptor()
+    MultipleObjectsReturned = MultipleObjectsReturnedDescriptor()
+
+    # Every model gets an automatic id field
+    id = PrimaryKeyField()
 
     def __init__(self, *args, **kwargs):
         # Alias some things as locals to avoid repeat global lookups
@@ -327,7 +281,7 @@ class Model(metaclass=ModelBase):
     def __eq__(self, other):
         if not isinstance(other, Model):
             return NotImplemented
-        if self._meta.concrete_model != other._meta.concrete_model:
+        if self.__class__ != other.__class__:
             return False
         my_id = self.id
         if my_id is None:
@@ -711,34 +665,20 @@ class Model(metaclass=ModelBase):
         collector.collect([self])
         return collector.delete()
 
-    def _get_FIELD_display(self, field):
+    def get_field_display(self, field):
+        """Get the display value for a field, especially useful for fields with choices."""
         value = getattr(self, field.attname)
+
+        # If field has no choices, just return the value as string
+        if not hasattr(field, "flatchoices") or not field.flatchoices:
+            return force_str(value, strings_only=True)
+
+        # For fields with choices, look up the display value
         choices_dict = dict(make_hashable(field.flatchoices))
-        # force_str() to coerce lazy strings.
         return force_str(
             choices_dict.get(make_hashable(value), value), strings_only=True
         )
 
-    def _get_next_or_previous_by_FIELD(self, field, is_next, **kwargs):
-        if not self.id:
-            raise ValueError("get_next/get_previous cannot be used on unsaved objects.")
-        op = "gt" if is_next else "lt"
-        order = "" if is_next else "-"
-        param = getattr(self, field.attname)
-        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__.query.filter(**kwargs)
-            .filter(q)
-            .order_by(f"{order}{field.name}", f"{order}id")
-        )
-        try:
-            return qs[0]
-        except IndexError:
-            raise self.DoesNotExist(
-                f"{self.__class__._meta.object_name} matching query does not exist."
-            )
-
     def _get_field_value_map(self, meta, exclude=None):
         if exclude is None:
             exclude = set()

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/constraints.py

@@ -1,7 +1,8 @@
 from enum import Enum
 from types import NoneType
 
-from plain.exceptions import FieldError, ValidationError
+from plain.exceptions import ValidationError
+from plain.models.exceptions import FieldError
 from plain.models.expressions import Exists, ExpressionList, F, OrderBy
 from plain.models.indexes import IndexExpression
 from plain.models.lookups import Exact

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/deletion.py

@@ -139,9 +139,7 @@ class Collector:
     def add_dependency(self, model, dependency, reverse_dependency=False):
         if reverse_dependency:
             model, dependency = dependency, model
-        self.dependencies[model._meta.concrete_model].add(
-            dependency._meta.concrete_model
-        )
+        self.dependencies[model].add(dependency)
         self.data.setdefault(dependency, self.data.default_factory())
 
     def add_field_update(self, field, value, objs):
@@ -363,10 +361,10 @@ class Collector:
             for model in models:
                 if model in sorted_models:
                     continue
-                dependencies = self.dependencies.get(model._meta.concrete_model)
+                dependencies = self.dependencies.get(model)
                 if not (dependencies and dependencies.difference(concrete_models)):
                     sorted_models.append(model)
-                    concrete_models.add(model._meta.concrete_model)
+                    concrete_models.add(model)
                     found = True
             if not found:
                 return

plain_models-0.49.0/plain/models/exceptions.py

@@ -0,0 +1,196 @@
+from typing import Any
+
+# MARK: Database Query Exceptions
+
+
+class EmptyResultSet(Exception):
+    """A database query predicate is impossible."""
+
+    pass
+
+
+class FullResultSet(Exception):
+    """A database query predicate is matches everything."""
+
+    pass
+
+
+# MARK: Model and Field Errors
+
+
+class FieldDoesNotExist(Exception):
+    """The requested model field does not exist"""
+
+    pass
+
+
+class FieldError(Exception):
+    """Some kind of problem with a model field."""
+
+    pass
+
+
+class ObjectDoesNotExist(Exception):
+    """The requested object does not exist"""
+
+    pass
+
+
+class MultipleObjectsReturned(Exception):
+    """The query returned multiple objects when only one was expected."""
+
+    pass
+
+
+# MARK: Model Exception Descriptors
+
+
+class DoesNotExistDescriptor:
+    """Descriptor that creates a unique DoesNotExist exception class per model."""
+
+    def __init__(self) -> None:
+        self._exceptions_by_class: dict[type, type[ObjectDoesNotExist]] = {}
+
+    def __get__(self, instance: Any, owner: type | None) -> type[ObjectDoesNotExist]:
+        if owner is None:
+            return ObjectDoesNotExist  # Return base class as fallback
+
+        # Create a unique exception class for this model if we haven't already
+        if owner not in self._exceptions_by_class:
+            exc_class = type(
+                "DoesNotExist",
+                (ObjectDoesNotExist,),
+                {
+                    "__module__": owner.__module__,
+                    "__qualname__": f"{owner.__qualname__}.DoesNotExist",
+                },
+            )
+            self._exceptions_by_class[owner] = exc_class
+
+        return self._exceptions_by_class[owner]
+
+    def __set__(self, instance: Any, value: Any) -> None:
+        raise AttributeError("Cannot set DoesNotExist")
+
+
+class MultipleObjectsReturnedDescriptor:
+    """Descriptor that creates a unique MultipleObjectsReturned exception class per model."""
+
+    def __init__(self) -> None:
+        self._exceptions_by_class: dict[type, type[MultipleObjectsReturned]] = {}
+
+    def __get__(
+        self, instance: Any, owner: type | None
+    ) -> type[MultipleObjectsReturned]:
+        if owner is None:
+            return MultipleObjectsReturned  # Return base class as fallback
+
+        # Create a unique exception class for this model if we haven't already
+        if owner not in self._exceptions_by_class:
+            exc_class = type(
+                "MultipleObjectsReturned",
+                (MultipleObjectsReturned,),
+                {
+                    "__module__": owner.__module__,
+                    "__qualname__": f"{owner.__qualname__}.MultipleObjectsReturned",
+                },
+            )
+            self._exceptions_by_class[owner] = exc_class
+
+        return self._exceptions_by_class[owner]
+
+    def __set__(self, instance: Any, value: Any) -> None:
+        raise AttributeError("Cannot set MultipleObjectsReturned")
+
+
+# MARK: Database Exceptions (PEP-249)
+
+
+class Error(Exception):
+    pass
+
+
+class InterfaceError(Error):
+    pass
+
+
+class DatabaseError(Error):
+    pass
+
+
+class DataError(DatabaseError):
+    pass
+
+
+class OperationalError(DatabaseError):
+    pass
+
+
+class IntegrityError(DatabaseError):
+    pass
+
+
+class InternalError(DatabaseError):
+    pass
+
+
+class ProgrammingError(DatabaseError):
+    pass
+
+
+class NotSupportedError(DatabaseError):
+    pass
+
+
+class ConnectionDoesNotExist(Exception):
+    pass
+
+
+class DatabaseErrorWrapper:
+    """
+    Context manager and decorator that reraises backend-specific database
+    exceptions using Plain's common wrappers.
+    """
+
+    def __init__(self, wrapper):
+        """
+        wrapper is a database wrapper.
+
+        It must have a Database attribute defining PEP-249 exceptions.
+        """
+        self.wrapper = wrapper
+
+    def __enter__(self):
+        pass
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if exc_type is None:
+            return
+        for plain_exc_type in (
+            DataError,
+            OperationalError,
+            IntegrityError,
+            InternalError,
+            ProgrammingError,
+            NotSupportedError,
+            DatabaseError,
+            InterfaceError,
+            Error,
+        ):
+            db_exc_type = getattr(self.wrapper.Database, plain_exc_type.__name__)
+            if issubclass(exc_type, db_exc_type):
+                plain_exc_value = plain_exc_type(*exc_value.args)
+                # Only set the 'errors_occurred' flag for errors that may make
+                # the connection unusable.
+                if plain_exc_type not in (DataError, IntegrityError):
+                    self.wrapper.errors_occurred = True
+                raise plain_exc_value.with_traceback(traceback) from exc_value
+
+    def __call__(self, func):
+        # Note that we are intentionally not using @wraps here for performance
+        # reasons. Refs #21109.
+        def inner(*args, **kwargs):
+            with self:
+                return func(*args, **kwargs)
+
+        return inner

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/expressions.py

@@ -8,7 +8,6 @@ from functools import cached_property
 from types import NoneType
 from uuid import UUID
 
-from plain.exceptions import EmptyResultSet, FieldError, FullResultSet
 from plain.models import fields
 from plain.models.constants import LOOKUP_SEP
 from plain.models.db import (
@@ -16,6 +15,7 @@ from plain.models.db import (
     NotSupportedError,
     db_connection,
 )
+from plain.models.exceptions import EmptyResultSet, FieldError, FullResultSet
 from plain.models.query_utils import Q
 from plain.utils.deconstruct import deconstructible
 from plain.utils.hashable import make_hashable

{plain_models-0.48.0 → plain_models-0.49.0}/plain/models/fields/__init__.py

@@ -7,7 +7,7 @@ import operator
 import uuid
 import warnings
 from base64 import b64decode, b64encode
-from functools import cached_property, partialmethod, total_ordering
+from functools import cached_property, total_ordering
 
 from plain import exceptions, validators
 from plain.models.constants import LOOKUP_SEP
@@ -759,29 +759,15 @@ class Field(RegisterLookupMixin):
         self.attname, self.column = self.get_attname_column()
         self.concrete = self.column is not None
 
-    def contribute_to_class(self, cls, name, private_only=False):
+    def contribute_to_class(self, cls, name):
         """
         Register the field with the model class it belongs to.
-
-        If private_only is True, create a separate instance of this field
-        for every subclass of cls, even if cls is not an abstract model.
         """
         self.set_attributes_from_name(name)
         self.model = cls
-        cls._meta.add_field(self, private=private_only)
+        cls._meta.add_field(self)
         if self.column:
             setattr(cls, self.attname, self.descriptor_class(self))
-        if self.choices is not None:
-            # Don't override a get_FOO_display() method defined explicitly on
-            # this class, but don't check methods derived from inheritance, to
-            # allow overriding inherited choices. For more complex inheritance
-            # structures users should override contribute_to_class().
-            if f"get_{self.name}_display" not in cls.__dict__:
-                setattr(
-                    cls,
-                    f"get_{self.name}_display",
-                    partialmethod(cls._get_FIELD_display, field=self),
-                )
 
     def get_attname(self):
         return self.name
@@ -1200,24 +1186,6 @@ class DateField(DateTimeCheckMixin, Field):
         else:
             return super().pre_save(model_instance, add)
 
-    def contribute_to_class(self, cls, name, **kwargs):
-        super().contribute_to_class(cls, name, **kwargs)
-        if not self.allow_null:
-            setattr(
-                cls,
-                f"get_next_by_{self.name}",
-                partialmethod(
-                    cls._get_next_or_previous_by_FIELD, field=self, is_next=True
-                ),
-            )
-            setattr(
-                cls,
-                f"get_previous_by_{self.name}",
-                partialmethod(
-                    cls._get_next_or_previous_by_FIELD, field=self, is_next=False
-                ),
-            )
-
     def get_prep_value(self, value):
         value = super().get_prep_value(value)
         return self.to_python(value)
@@ -1319,9 +1287,6 @@ class DateTimeField(DateField):
         else:
             return super().pre_save(model_instance, add)
 
-    # contribute_to_class is inherited from DateField, it registers
-    # get_next_by_FOO and get_prev_by_FOO
-
     def get_prep_value(self, value):
         value = super().get_prep_value(value)
         value = self.to_python(value)
@@ -2145,9 +2110,6 @@ class PrimaryKeyField(BigIntegerField):
             value = connection.ops.validate_autopk_value(value)
         return value
 
-    def contribute_to_class(self, cls, name, **kwargs):
-        super().contribute_to_class(cls, name, **kwargs)
-
     def get_internal_type(self):
         return "PrimaryKeyField"