plain.models 0.47.0__tar.gz → 0.49.0__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.models
-Version: 0.47.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.47.0 → plain_models-0.49.0}/plain/models/CHANGELOG.md

@@ -1,5 +1,32 @@
 # 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
+
+- Migrations now run in a single transaction by default for databases that support transactional DDL, providing all-or-nothing migration batches for better safety and consistency ([6d0c105](https://github.com/dropseed/plain/commit/6d0c105fa9))
+- Added `--atomic-batch/--no-atomic-batch` options to `plain migrate` to explicitly control whether migrations are run in a single transaction ([6d0c105](https://github.com/dropseed/plain/commit/6d0c105fa9))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.47.0](https://github.com/dropseed/plain/releases/plain-models@0.47.0) (2025-09-25)
 
 ### What's changed

{plain_models-0.47.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.47.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.47.0 → plain_models-0.49.0}/plain/models/backends/base/creation.py

@@ -59,6 +59,7 @@ class BaseDatabaseCreation:
             prune=False,
             no_input=True,
             verbosity=max(verbosity - 1, 0),
+            atomic_batch=False,  # No need for atomic batch when creating test database
         )
 
         # Ensure a connection for the side effect of initializing the test database.

{plain_models-0.47.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.47.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.47.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.47.0 → plain_models-0.49.0}/plain/models/cli.py

@@ -362,6 +362,11 @@ def makemigrations(package_labels, dry_run, empty, no_input, name, check, verbos
     default=1,
     help="Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output",
 )
+@click.option(
+    "--atomic-batch/--no-atomic-batch",
+    default=None,
+    help="Run migrations in a single transaction (auto-detected by default)",
+)
 def migrate(
     package_label,
     migration_name,
@@ -372,6 +377,7 @@ def migrate(
     prune,
     no_input,
     verbosity,
+    atomic_batch,
 ):
     """Updates database schema. Manages both packages with migrations and those without."""
 
@@ -575,6 +581,65 @@ def migrate(
     # pprint(sql)
 
     if migration_plan:
+        # Determine whether to use atomic batch
+        use_atomic_batch = False
+        if len(migration_plan) > 1:
+            # Check database capabilities
+            can_rollback_ddl = db_connection.features.can_rollback_ddl
+
+            # Check if all migrations support atomic
+            non_atomic_migrations = [m for m in migration_plan if not m.atomic]
+
+            if atomic_batch is True:
+                # User explicitly requested atomic batch
+                if not can_rollback_ddl:
+                    raise click.UsageError(
+                        f"--atomic-batch not supported on {db_connection.vendor}. "
+                        "Remove the flag or use a database that supports transactional DDL."
+                    )
+                if non_atomic_migrations:
+                    names = ", ".join(
+                        f"{m.package_label}.{m.name}" for m in non_atomic_migrations[:3]
+                    )
+                    if len(non_atomic_migrations) > 3:
+                        names += f", and {len(non_atomic_migrations) - 3} more"
+                    raise click.UsageError(
+                        f"--atomic-batch requested but these migrations have atomic=False: {names}"
+                    )
+                use_atomic_batch = True
+                if verbosity >= 1:
+                    click.echo(
+                        f"  Running {len(migration_plan)} migrations in atomic batch (all-or-nothing)"
+                    )
+            elif atomic_batch is False:
+                # User explicitly disabled atomic batch
+                use_atomic_batch = False
+                if verbosity >= 1:
+                    click.echo(f"  Running {len(migration_plan)} migrations separately")
+            else:
+                # Auto-detect (atomic_batch is None)
+                if can_rollback_ddl and not non_atomic_migrations:
+                    use_atomic_batch = True
+                    if verbosity >= 1:
+                        click.echo(
+                            f"  Running {len(migration_plan)} migrations in atomic batch (all-or-nothing)"
+                        )
+                else:
+                    use_atomic_batch = False
+                    if verbosity >= 1:
+                        if not can_rollback_ddl:
+                            click.echo(
+                                f"  Running {len(migration_plan)} migrations separately ({db_connection.vendor} doesn't support batch transactions)"
+                            )
+                        elif non_atomic_migrations:
+                            click.echo(
+                                f"  Running {len(migration_plan)} migrations separately (some migrations have atomic=False)"
+                            )
+                        else:
+                            click.echo(
+                                f"  Running {len(migration_plan)} migrations separately"
+                            )
+
         if backup or (backup is None and settings.DEBUG):
             backup_name = f"migrate_{time.strftime('%Y%m%d_%H%M%S')}"
             click.secho(
@@ -599,6 +664,7 @@ def migrate(
             plan=migration_plan,
             state=pre_migrate_state.clone(),
             fake=fake,
+            atomic_batch=use_atomic_batch,
         )
         # post_migrate signals have access to all models. Ensure that all models
         # are reloaded in case any are delayed.

{plain_models-0.47.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.47.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.47.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