plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/enums.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import enum
+from types import DynamicClassAttribute
+from typing import Any
+
+from plain.utils.functional import Promise
+
+__all__ = ["Choices", "IntegerChoices", "TextChoices"]
+
+
+class ChoicesMeta(enum.EnumMeta):
+    """A metaclass for creating a enum choices."""
+
+    def __new__(
+        metacls: type,
+        classname: str,
+        bases: tuple[type, ...],
+        classdict: Any,
+        **kwds: Any,
+    ) -> type:
+        labels = []
+        for key in classdict._member_names:
+            value = classdict[key]
+            if (
+                isinstance(value, list | tuple)
+                and len(value) > 1
+                and isinstance(value[-1], Promise | str)
+            ):
+                *value, label = value
+                value = tuple(value)
+            else:
+                label = key.replace("_", " ").title()
+            labels.append(label)
+            # Use dict.__setitem__() to suppress defenses against double
+            # assignment in enum's classdict.
+            dict.__setitem__(classdict, key, value)
+        cls = super().__new__(metacls, classname, bases, classdict, **kwds)  # type: ignore[misc]
+        for member, label in zip(cls.__members__.values(), labels):
+            member._label_ = label
+        return enum.unique(cls)
+
+    def __contains__(cls, member: object) -> bool:  # type: ignore[override]
+        if not isinstance(member, enum.Enum):
+            # Allow non-enums to match against member values.
+            return any(x.value == member for x in cls)  # type: ignore[attr-defined]
+        return super().__contains__(member)
+
+    @property
+    def names(cls) -> list[str]:
+        empty = ["__empty__"] if hasattr(cls, "__empty__") else []
+        return empty + [member.name for member in cls]  # type: ignore[attr-defined]
+
+    @property
+    def choices(cls) -> list[tuple[Any, str]]:
+        empty = [(None, cls.__empty__)] if hasattr(cls, "__empty__") else []
+        return empty + [(member.value, member.label) for member in cls]  # type: ignore[attr-defined]
+
+    @property
+    def labels(cls) -> list[str]:
+        return [label for _, label in cls.choices]
+
+    @property
+    def values(cls) -> list[Any]:
+        return [value for value, _ in cls.choices]
+
+
+class Choices(enum.Enum, metaclass=ChoicesMeta):
+    """Class for creating enumerated choices."""
+
+    # Dynamically set by metaclass
+    _label_: str
+
+    @DynamicClassAttribute
+    def label(self) -> str:
+        return self._label_
+
+    def __str__(self) -> str:
+        """
+        Use value when cast to str, so that Choices set as model instance
+        attributes are rendered as expected in templates and similar contexts.
+        """
+        return str(self.value)
+
+    # A similar format was proposed for Python 3.10.
+    def __repr__(self) -> str:
+        return f"{self.__class__.__qualname__}.{self._name_}"
+
+
+class IntegerChoices(int, Choices):
+    """Class for creating enumerated integer choices."""
+
+    pass
+
+
+class TextChoices(str, Choices):
+    """Class for creating enumerated string choices."""
+
+    @staticmethod
+    def _generate_next_value_(
+        name: str, start: int, count: int, last_values: list[str]
+    ) -> str:
+        return name

plain/postgres/exceptions.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+import psycopg
+
+if TYPE_CHECKING:
+    from plain.postgres.connection import DatabaseConnection
+
+F = TypeVar("F", bound=Callable[..., 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:
+            # type() returns a subclass of ObjectDoesNotExist
+            exc_class: type[ObjectDoesNotExist] = cast(
+                type[ObjectDoesNotExist],
+                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:
+            # type() returns a subclass of MultipleObjectsReturned
+            exc_class = cast(
+                type[MultipleObjectsReturned],
+                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 DatabaseErrorWrapper:
+    """
+    Context manager and decorator that reraises backend-specific database
+    exceptions using Plain's common wrappers.
+    """
+
+    def __init__(self, wrapper: DatabaseConnection) -> None:
+        """
+        wrapper is a database wrapper.
+
+        It must have a Database attribute defining PEP-249 exceptions.
+        """
+        self.wrapper = wrapper
+
+    def __enter__(self) -> None:
+        pass
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: Any,
+    ) -> None:
+        if exc_type is None:
+            return
+        for plain_exc_type in (
+            DataError,
+            OperationalError,
+            IntegrityError,
+            InternalError,
+            ProgrammingError,
+            NotSupportedError,
+            DatabaseError,
+            InterfaceError,
+            Error,
+        ):
+            db_exc_type = getattr(psycopg, plain_exc_type.__name__)
+            if issubclass(exc_type, db_exc_type):
+                plain_exc_value = (
+                    plain_exc_type(*exc_value.args) if exc_value else plain_exc_type()
+                )
+                # 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: F) -> F:
+        # Note that we are intentionally not using @wraps here for performance
+        # reasons. Refs #21109.
+        def inner(*args: Any, **kwargs: Any) -> Any:
+            with self:
+                return func(*args, **kwargs)
+
+        return cast(F, inner)