plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/connections.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, TypedDict
+
+from plain.exceptions import ImproperlyConfigured
+from plain.runtime import settings as plain_settings
+
+if TYPE_CHECKING:
+    from plain.postgres.connection import DatabaseConnection
+
+
+class DatabaseConfig(TypedDict, total=False):
+    CONN_MAX_AGE: int | None
+    CONN_HEALTH_CHECKS: bool
+    HOST: str
+    DATABASE: str | None
+    OPTIONS: dict[str, Any]
+    PASSWORD: str
+    PORT: int | None
+    TEST: dict[str, Any]
+    TIME_ZONE: str | None
+    USER: str
+
+
+# Module-level ContextVar for per-task/per-thread connection storage.
+# Each asyncio.Task gets its own copy (since Python 3.7.1).
+# Thread pool threads maintain their own native context across work items,
+# so connections persist across requests (honoring CONN_MAX_AGE).
+_db_conn: ContextVar[DatabaseConnection | None] = ContextVar("_db_conn", default=None)
+
+
+def _configure_settings() -> DatabaseConfig:
+    if plain_settings.POSTGRES_DATABASE == "":
+        raise ImproperlyConfigured(
+            "The PostgreSQL database has been disabled (DATABASE_URL=none). "
+            "No database operations are available in this context."
+        )
+    if not plain_settings.POSTGRES_DATABASE:  # None or unresolved setting
+        raise ImproperlyConfigured(
+            "PostgreSQL database is not configured. "
+            "Set DATABASE_URL or the individual POSTGRES_* settings."
+        )
+
+    return {
+        "DATABASE": plain_settings.POSTGRES_DATABASE,
+        "USER": plain_settings.POSTGRES_USER,
+        "PASSWORD": plain_settings.POSTGRES_PASSWORD,
+        "HOST": plain_settings.POSTGRES_HOST,
+        "PORT": plain_settings.POSTGRES_PORT,
+        "CONN_MAX_AGE": plain_settings.POSTGRES_CONN_MAX_AGE,
+        "CONN_HEALTH_CHECKS": plain_settings.POSTGRES_CONN_HEALTH_CHECKS,
+        "OPTIONS": plain_settings.POSTGRES_OPTIONS,
+        "TIME_ZONE": plain_settings.POSTGRES_TIME_ZONE,
+        "TEST": {"DATABASE": None},
+    }
+
+
+def _create_connection() -> DatabaseConnection:
+    from plain.postgres.connection import DatabaseConnection
+
+    database_config = _configure_settings()
+    return DatabaseConnection(database_config)
+
+
+def get_connection() -> DatabaseConnection:
+    """Get or create the database connection for the current context."""
+    conn = _db_conn.get()
+    if conn is None:
+        conn = _create_connection()
+        _db_conn.set(conn)
+    return conn
+
+
+def has_connection() -> bool:
+    """Check if a database connection exists in the current context."""
+    return _db_conn.get() is not None

plain/postgres/constants.py

@@ -0,0 +1,13 @@
+"""
+Constants used across the ORM in general.
+"""
+
+from enum import Enum
+
+# Separator used to split filter strings apart.
+LOOKUP_SEP = "__"
+
+
+class OnConflict(Enum):
+    IGNORE = "ignore"
+    UPDATE = "update"

plain/postgres/constraints.py

@@ -0,0 +1,495 @@
+from __future__ import annotations
+
+from enum import Enum
+from types import NoneType
+from typing import TYPE_CHECKING, Any
+
+from plain.exceptions import ValidationError
+from plain.postgres.exceptions import FieldError
+from plain.postgres.expressions import (
+    Exists,
+    ExpressionList,
+    F,
+    OrderBy,
+    ReplaceableExpression,
+)
+from plain.postgres.indexes import IndexExpression
+from plain.postgres.lookups import Exact
+from plain.postgres.query_utils import Q
+from plain.postgres.sql.query import Query
+
+if TYPE_CHECKING:
+    from plain.postgres.base import Model
+    from plain.postgres.schema import DatabaseSchemaEditor, Statement
+
+__all__ = ["BaseConstraint", "CheckConstraint", "Deferrable", "UniqueConstraint"]
+
+
+class BaseConstraint:
+    default_violation_error_message = 'Constraint "%(name)s" is violated.'
+    violation_error_code: str | None = None
+    violation_error_message: str | None = None
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        violation_error_code: str | None = None,
+        violation_error_message: str | None = None,
+    ) -> None:
+        self.name = name
+        if violation_error_code is not None:
+            self.violation_error_code = violation_error_code
+        if violation_error_message is not None:
+            self.violation_error_message = violation_error_message
+        else:
+            self.violation_error_message = self.default_violation_error_message
+
+    @property
+    def contains_expressions(self) -> bool:
+        return False
+
+    def constraint_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str | None:
+        raise NotImplementedError(
+            "subclasses of BaseConstraint must provide a constraint_sql() method"
+        )
+
+    def create_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str | Statement | None:
+        raise NotImplementedError(
+            "subclasses of BaseConstraint must provide a create_sql() method"
+        )
+
+    def remove_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str | Statement | None:
+        raise NotImplementedError(
+            "subclasses of BaseConstraint must provide a remove_sql() method"
+        )
+
+    def validate(
+        self, model: type[Model], instance: Model, exclude: set[str] | None = None
+    ) -> None:
+        raise NotImplementedError(
+            "subclasses of BaseConstraint must provide a validate() method"
+        )
+
+    def get_violation_error_message(self) -> str:
+        assert self.violation_error_message is not None
+        return self.violation_error_message % {"name": self.name}
+
+    def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
+        path = f"{self.__class__.__module__}.{self.__class__.__name__}"
+        path = path.replace("plain.postgres.constraints", "plain.postgres")
+        kwargs: dict[str, Any] = {"name": self.name}
+        if (
+            self.violation_error_message is not None
+            and self.violation_error_message != self.default_violation_error_message
+        ):
+            kwargs["violation_error_message"] = self.violation_error_message
+        if self.violation_error_code is not None:
+            kwargs["violation_error_code"] = self.violation_error_code
+        return (path, (), kwargs)
+
+    def clone(self) -> BaseConstraint:
+        _, args, kwargs = self.deconstruct()
+        return self.__class__(*args, **kwargs)
+
+
+class CheckConstraint(BaseConstraint):
+    def __init__(
+        self,
+        *,
+        check: Q,
+        name: str,
+        violation_error_code: str | None = None,
+        violation_error_message: str | None = None,
+    ) -> None:
+        self.check = check
+        if not getattr(check, "conditional", False):
+            raise TypeError(
+                "CheckConstraint.check must be a Q instance or boolean expression."
+            )
+        super().__init__(
+            name=name,
+            violation_error_code=violation_error_code,
+            violation_error_message=violation_error_message,
+        )
+
+    def _get_check_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str:
+        query = Query(model=model, alias_cols=False)
+        where = query.build_where(self.check)
+        compiler = query.get_compiler()
+        sql, params = where.as_sql(compiler, schema_editor.connection)
+        return sql % tuple(schema_editor.quote_value(p) for p in params)
+
+    def constraint_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str:
+        check = self._get_check_sql(model, schema_editor)
+        return schema_editor._check_sql(self.name, check)
+
+    def create_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> Statement | None:
+        check = self._get_check_sql(model, schema_editor)
+        return schema_editor._create_check_sql(model, self.name, check)
+
+    def remove_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> Statement | None:
+        return schema_editor._delete_constraint_sql(
+            schema_editor.sql_delete_check, model, self.name
+        )
+
+    def validate(
+        self, model: type[Model], instance: Model, exclude: set[str] | None = None
+    ) -> None:
+        against = instance._get_field_value_map(meta=model._model_meta, exclude=exclude)
+        try:
+            if not Q(self.check).check(against):
+                raise ValidationError(
+                    self.get_violation_error_message(), code=self.violation_error_code
+                )
+        except FieldError:
+            pass
+
+    def __repr__(self) -> str:
+        return "<{}: check={} name={}{}{}>".format(
+            self.__class__.__qualname__,
+            self.check,
+            repr(self.name),
+            (
+                ""
+                if self.violation_error_code is None
+                else f" violation_error_code={self.violation_error_code!r}"
+            ),
+            (
+                ""
+                if self.violation_error_message is None
+                or self.violation_error_message == self.default_violation_error_message
+                else f" violation_error_message={self.violation_error_message!r}"
+            ),
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, CheckConstraint):
+            return (
+                self.name == other.name
+                and self.check == other.check
+                and self.violation_error_code == other.violation_error_code
+                and self.violation_error_message == other.violation_error_message
+            )
+        return super().__eq__(other)
+
+    def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
+        path, args, kwargs = super().deconstruct()
+        kwargs["check"] = self.check
+        return path, args, kwargs
+
+
+class Deferrable(Enum):
+    DEFERRED = "deferred"
+    IMMEDIATE = "immediate"
+
+    # A similar format was proposed for Python 3.10.
+    def __repr__(self) -> str:
+        return f"{self.__class__.__qualname__}.{self._name_}"
+
+
+class UniqueConstraint(BaseConstraint):
+    expressions: tuple[ReplaceableExpression, ...]
+
+    def __init__(
+        self,
+        *expressions: str | ReplaceableExpression,
+        fields: tuple[str, ...] | list[str] = (),
+        name: str | None = None,
+        condition: Q | None = None,
+        deferrable: Deferrable | None = None,
+        include: tuple[str, ...] | list[str] | None = None,
+        opclasses: tuple[str, ...] | list[str] = (),
+        violation_error_code: str | None = None,
+        violation_error_message: str | None = None,
+    ) -> None:
+        if not name:
+            raise ValueError("A unique constraint must be named.")
+        if not expressions and not fields:
+            raise ValueError(
+                "At least one field or expression is required to define a "
+                "unique constraint."
+            )
+        if expressions and fields:
+            raise ValueError(
+                "UniqueConstraint.fields and expressions are mutually exclusive."
+            )
+        if not isinstance(condition, NoneType | Q):
+            raise ValueError("UniqueConstraint.condition must be a Q instance.")
+        if condition and deferrable:
+            raise ValueError("UniqueConstraint with conditions cannot be deferred.")
+        if include and deferrable:
+            raise ValueError("UniqueConstraint with include fields cannot be deferred.")
+        if opclasses and deferrable:
+            raise ValueError("UniqueConstraint with opclasses cannot be deferred.")
+        if expressions and deferrable:
+            raise ValueError("UniqueConstraint with expressions cannot be deferred.")
+        if expressions and opclasses:
+            raise ValueError(
+                "UniqueConstraint.opclasses cannot be used with expressions. "
+                "Use a custom OpClass() instead."
+            )
+        if not isinstance(deferrable, NoneType | Deferrable):
+            raise ValueError(
+                "UniqueConstraint.deferrable must be a Deferrable instance."
+            )
+        if not isinstance(include, NoneType | list | tuple):
+            raise ValueError("UniqueConstraint.include must be a list or tuple.")
+        if not isinstance(opclasses, list | tuple):
+            raise ValueError("UniqueConstraint.opclasses must be a list or tuple.")
+        if opclasses and len(fields) != len(opclasses):
+            raise ValueError(
+                "UniqueConstraint.fields and UniqueConstraint.opclasses must "
+                "have the same number of elements."
+            )
+        self.fields = tuple(fields)
+        self.condition = condition
+        self.deferrable = deferrable
+        self.include = tuple(include) if include else ()
+        self.opclasses = opclasses
+        self.expressions = tuple(
+            F(expression) if isinstance(expression, str) else expression
+            for expression in expressions
+        )
+        super().__init__(
+            name=name,
+            violation_error_code=violation_error_code,
+            violation_error_message=violation_error_message,
+        )
+
+    @property
+    def contains_expressions(self) -> bool:
+        return bool(self.expressions)
+
+    def _get_condition_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str | None:
+        if self.condition is None:
+            return None
+        query = Query(model=model, alias_cols=False)
+        where = query.build_where(self.condition)
+        compiler = query.get_compiler()
+        sql, params = where.as_sql(compiler, schema_editor.connection)
+        return sql % tuple(schema_editor.quote_value(p) for p in params)
+
+    def _get_index_expressions(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> Any:
+        if not self.expressions:
+            return None
+        index_expressions = []
+        for expression in self.expressions:
+            index_expression = IndexExpression(expression)
+            index_expressions.append(index_expression)
+        return ExpressionList(*index_expressions).resolve_expression(
+            Query(model, alias_cols=False),
+        )
+
+    def constraint_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> str | None:
+        fields = [
+            model._model_meta.get_forward_field(field_name)
+            for field_name in self.fields
+        ]
+        include = [
+            model._model_meta.get_forward_field(field_name).column
+            for field_name in self.include
+        ]
+        condition = self._get_condition_sql(model, schema_editor)
+        expressions = self._get_index_expressions(model, schema_editor)
+        return schema_editor._unique_sql(
+            model,
+            fields,
+            self.name,
+            condition=condition,
+            deferrable=self.deferrable,
+            include=include,
+            opclasses=tuple(self.opclasses) if self.opclasses else None,
+            expressions=expressions,
+        )
+
+    def create_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> Statement | None:
+        fields = [
+            model._model_meta.get_forward_field(field_name)
+            for field_name in self.fields
+        ]
+        include = [
+            model._model_meta.get_forward_field(field_name).column
+            for field_name in self.include
+        ]
+        condition = self._get_condition_sql(model, schema_editor)
+        expressions = self._get_index_expressions(model, schema_editor)
+        return schema_editor._create_unique_sql(
+            model,
+            fields,
+            self.name,
+            condition=condition,
+            deferrable=self.deferrable,
+            include=include,
+            opclasses=tuple(self.opclasses) if self.opclasses else None,
+            expressions=expressions,
+        )
+
+    def remove_sql(
+        self, model: type[Model], schema_editor: DatabaseSchemaEditor
+    ) -> Statement | None:
+        condition = self._get_condition_sql(model, schema_editor)
+        include = [
+            model._model_meta.get_forward_field(field_name).column
+            for field_name in self.include
+        ]
+        expressions = self._get_index_expressions(model, schema_editor)
+        return schema_editor._delete_unique_sql(
+            model,
+            self.name,
+            condition=condition,
+            deferrable=self.deferrable,
+            include=include,
+            opclasses=tuple(self.opclasses) if self.opclasses else None,
+            expressions=expressions,
+        )
+
+    def __repr__(self) -> str:
+        return "<{}:{}{}{}{}{}{}{}{}{}>".format(
+            self.__class__.__qualname__,
+            "" if not self.fields else f" fields={repr(self.fields)}",
+            "" if not self.expressions else f" expressions={repr(self.expressions)}",
+            f" name={repr(self.name)}",
+            "" if self.condition is None else f" condition={self.condition}",
+            "" if self.deferrable is None else f" deferrable={self.deferrable!r}",
+            "" if not self.include else f" include={repr(self.include)}",
+            "" if not self.opclasses else f" opclasses={repr(self.opclasses)}",
+            (
+                ""
+                if self.violation_error_code is None
+                else f" violation_error_code={self.violation_error_code!r}"
+            ),
+            (
+                ""
+                if self.violation_error_message is None
+                or self.violation_error_message == self.default_violation_error_message
+                else f" violation_error_message={self.violation_error_message!r}"
+            ),
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, UniqueConstraint):
+            return (
+                self.name == other.name
+                and self.fields == other.fields
+                and self.condition == other.condition
+                and self.deferrable == other.deferrable
+                and self.include == other.include
+                and self.opclasses == other.opclasses
+                and self.expressions == other.expressions
+                and self.violation_error_code == other.violation_error_code
+                and self.violation_error_message == other.violation_error_message
+            )
+        return super().__eq__(other)
+
+    def deconstruct(self) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
+        path, args, kwargs = super().deconstruct()
+        if self.fields:
+            kwargs["fields"] = self.fields
+        if self.condition:
+            kwargs["condition"] = self.condition
+        if self.deferrable:
+            kwargs["deferrable"] = self.deferrable
+        if self.include:
+            kwargs["include"] = self.include
+        if self.opclasses:
+            kwargs["opclasses"] = self.opclasses
+        return path, self.expressions, kwargs
+
+    def validate(
+        self, model: type[Model], instance: Model, exclude: set[str] | None = None
+    ) -> None:
+        queryset = model.query
+        if self.fields:
+            lookup_kwargs = {}
+            for field_name in self.fields:
+                if exclude and field_name in exclude:
+                    return
+                field = model._model_meta.get_forward_field(field_name)
+                lookup_value = getattr(instance, field.attname)
+                if lookup_value is None:
+                    # A composite constraint containing NULL value cannot cause
+                    # a violation since NULL != NULL in SQL.
+                    return
+                lookup_kwargs[field.name] = lookup_value
+            queryset = queryset.filter(**lookup_kwargs)
+        else:
+            # Ignore constraints with excluded fields.
+            if exclude:
+                for expression in self.expressions:
+                    if hasattr(expression, "flatten"):
+                        for expr in expression.flatten():  # type: ignore[operator]
+                            if isinstance(expr, F) and expr.name in exclude:
+                                return
+                    elif isinstance(expression, F) and expression.name in exclude:
+                        return
+            replacements: dict[Any, Any] = {
+                F(field): value
+                for field, value in instance._get_field_value_map(
+                    meta=model._model_meta, exclude=exclude
+                ).items()
+            }
+            expressions = []
+            for expr in self.expressions:
+                # Ignore ordering.
+                if isinstance(expr, OrderBy):
+                    expr = expr.expression
+                expressions.append(Exact(expr, expr.replace_expressions(replacements)))
+            queryset = queryset.filter(*expressions)
+        model_class_id = instance.id
+        if not instance._state.adding and model_class_id is not None:
+            queryset = queryset.exclude(id=model_class_id)
+        if not self.condition:
+            if queryset.exists():
+                if self.expressions:
+                    raise ValidationError(
+                        self.get_violation_error_message(),
+                        code=self.violation_error_code,
+                    )
+                # When fields are defined, use the unique_error_message() for
+                # backward compatibility.
+                for constraint_model, constraints in instance.get_constraints():
+                    for constraint in constraints:
+                        if constraint is self:
+                            raise ValidationError(
+                                instance.unique_error_message(
+                                    constraint_model,
+                                    self.fields,
+                                ),
+                            )
+        else:
+            against = instance._get_field_value_map(
+                meta=model._model_meta, exclude=exclude
+            )
+            try:
+                if (self.condition & Exists(queryset.filter(self.condition))).check(
+                    against
+                ):
+                    raise ValidationError(
+                        self.get_violation_error_message(),
+                        code=self.violation_error_code,
+                    )
+            except FieldError:
+                pass

plain/postgres/database_url.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+# Copyright (c) Kenneth Reitz & individual contributors
+# All rights reserved.
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#     1. Redistributions of source code must retain the above copyright notice,
+#        this list of conditions and the following disclaimer.
+#     2. Redistributions in binary form must reproduce the above copyright
+#        notice, this list of conditions and the following disclaimer in the
+#        documentation and/or other materials provided with the distribution.
+#     3. Neither the name of Plain nor the names of its contributors may be used
+#        to endorse or promote products derived from this software without
+#        specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+import urllib.parse as urlparse
+
+from .connections import DatabaseConfig
+
+SCHEMES = {"postgres", "postgresql", "pgsql"}
+
+# Register database schemes in URLs.
+for scheme in SCHEMES:
+    urlparse.uses_netloc.append(scheme)
+
+
+def parse_database_url(url: str) -> DatabaseConfig:
+    """Parses a database URL."""
+    spliturl = urlparse.urlsplit(url)
+
+    if spliturl.scheme not in SCHEMES:
+        raise ValueError(
+            f"No support for '{spliturl.scheme}'. We support: {', '.join(sorted(SCHEMES))}"
+        )
+
+    path = spliturl.path[1:]
+    query = urlparse.parse_qs(spliturl.query)
+
+    # Handle percent-encoded hostnames (e.g. socket paths).
+    hostname = spliturl.hostname or ""
+    if "%" in hostname:
+        # Use netloc to avoid lowercased paths, strip credentials if present.
+        hostname = spliturl.netloc
+        if "@" in hostname:
+            hostname = hostname.rsplit("@", 1)[1]
+        hostname = urlparse.unquote(hostname)
+
+    parsed_config: DatabaseConfig = {
+        "DATABASE": urlparse.unquote(path or ""),
+        "USER": urlparse.unquote(spliturl.username or ""),
+        "PASSWORD": urlparse.unquote(spliturl.password or ""),
+        "HOST": hostname,
+        "PORT": spliturl.port,
+    }
+
+    # Pass the query string into OPTIONS.
+    options = {key: values[-1] for key, values in query.items()}
+    if options:
+        parsed_config["OPTIONS"] = options
+
+    return parsed_config
+
+
+def build_database_url(config: DatabaseConfig) -> str:
+    """Build a database URL from a configuration dictionary."""
+    options = config.get("OPTIONS", {})
+    query = urlparse.urlencode(list(options.items()))
+
+    user = urlparse.quote(str(config.get("USER", "")))
+    password = urlparse.quote(str(config.get("PASSWORD", "")))
+    host = config.get("HOST", "")
+    port = config.get("PORT")
+    name = urlparse.quote(str(config.get("DATABASE", "")))
+
+    netloc = ""
+    if user or password:
+        netloc += user
+        if password:
+            netloc += f":{password}"
+        netloc += "@"
+    netloc += host
+    if port:
+        netloc += f":{port}"
+
+    return urlparse.urlunsplit(("postgresql", netloc, f"/{name}", query, ""))