plain.postgres 0.84.0__py3-none-any.whl

plain/postgres/sql/constants.py

@@ -0,0 +1,22 @@
+"""
+Constants specific to the SQL storage portion of the ORM.
+"""
+
+# Size of each "chunk" for get_iterator calls.
+# Larger values are slightly faster at the expense of more storage space.
+GET_ITERATOR_CHUNK_SIZE = 100
+
+# How many results to expect from a cursor.execute call
+MULTI = "multi"
+SINGLE = "single"
+CURSOR = "cursor"
+NO_RESULTS = "no results"
+
+ORDER_DIR = {
+    "ASC": ("ASC", "DESC"),
+    "DESC": ("DESC", "ASC"),
+}
+
+# SQL join types.
+INNER = "INNER JOIN"
+LOUTER = "LEFT OUTER JOIN"

plain/postgres/sql/datastructures.py

@@ -0,0 +1,222 @@
+"""
+Useful auxiliary data structures for query construction. Not useful outside
+the SQL domain.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from plain.postgres.dialect import quote_name
+from plain.postgres.exceptions import FullResultSet
+from plain.postgres.sql.constants import INNER, LOUTER
+
+if TYPE_CHECKING:
+    from plain.postgres.connection import DatabaseConnection
+    from plain.postgres.fields.related import ForeignKeyField
+    from plain.postgres.fields.reverse_related import ForeignObjectRel
+    from plain.postgres.sql.compiler import SQLCompiler
+
+
+class MultiJoin(Exception):
+    """
+    Used by join construction code to indicate the point at which a
+    multi-valued join was attempted (if the caller wants to treat that
+    exceptionally).
+    """
+
+    def __init__(
+        self, names_pos: int, path_with_names: list[tuple[str, list[Any]]]
+    ) -> None:
+        self.level = names_pos
+        # The path travelled, this includes the path to the multijoin.
+        self.names_with_path = path_with_names
+
+
+class Empty:
+    pass
+
+
+class Join:
+    """
+    Used by sql.Query and sql.SQLCompiler to generate JOIN clauses into the
+    FROM entry. For example, the SQL generated could be
+        LEFT OUTER JOIN "sometable" T1
+        ON ("othertable"."sometable_id" = "sometable"."id")
+
+    This class is primarily used in Query.alias_map. All entries in alias_map
+    must be Join compatible by providing the following attributes and methods:
+        - table_name (string)
+        - table_alias (possible alias for the table, can be None)
+        - join_type (can be None for those entries that aren't joined from
+          anything)
+        - parent_alias (which table is this join's parent, can be None similarly
+          to join_type)
+        - as_sql()
+        - relabeled_clone()
+    """
+
+    def __init__(
+        self,
+        table_name: str,
+        parent_alias: str,
+        table_alias: str,
+        join_type: str,
+        join_field: ForeignKeyField | ForeignObjectRel,
+        nullable: bool,
+        filtered_relation: Any = None,
+    ) -> None:
+        # Join table
+        self.table_name = table_name
+        self.parent_alias = parent_alias
+        # Note: table_alias is not necessarily known at instantiation time.
+        self.table_alias = table_alias
+        # LOUTER or INNER
+        self.join_type = join_type
+        # A list of 2-tuples to use in the ON clause of the JOIN.
+        # Each 2-tuple will create one join condition in the ON clause.
+        self.join_cols = join_field.get_joining_columns()
+        # Along which field (or ForeignObjectRel in the reverse join case)
+        self.join_field = join_field
+        # Is this join nullabled?
+        self.nullable = nullable
+        self.filtered_relation = filtered_relation
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        """
+        Generate the full
+           LEFT OUTER JOIN sometable ON sometable.somecol = othertable.othercol, params
+        clause for this join.
+        """
+        join_conditions = []
+        params = []
+        qn = compiler.quote_name_unless_alias
+        qn2 = quote_name
+
+        # Add a join condition for each pair of joining columns.
+        for lhs_col, rhs_col in self.join_cols:
+            join_conditions.append(
+                f"{qn(self.parent_alias)}.{qn2(lhs_col)} = {qn(self.table_alias)}.{qn2(rhs_col)}"
+            )
+
+        if self.filtered_relation:
+            try:
+                extra_sql, extra_params = compiler.compile(self.filtered_relation)
+            except FullResultSet:
+                pass
+            else:
+                join_conditions.append(f"({extra_sql})")
+                params.extend(extra_params)
+        if not join_conditions:
+            # This might be a rel on the other end of an actual declared field.
+            declared_field = getattr(self.join_field, "field", self.join_field)
+            raise ValueError(
+                f"Join generated an empty ON clause. {declared_field.__class__} did not yield either "
+                "joining columns or extra restrictions."
+            )
+        on_clause_sql = " AND ".join(join_conditions)
+        alias_str = (
+            "" if self.table_alias == self.table_name else (f" {self.table_alias}")
+        )
+        sql = f"{self.join_type} {qn(self.table_name)}{alias_str} ON ({on_clause_sql})"
+        return sql, params
+
+    def relabeled_clone(self, change_map: dict[str, str]) -> Join:
+        new_parent_alias = change_map.get(self.parent_alias, self.parent_alias)
+        new_table_alias = change_map.get(self.table_alias, self.table_alias)
+        if self.filtered_relation is not None:
+            filtered_relation = self.filtered_relation.clone()
+            filtered_relation.path = [
+                change_map.get(p, p) for p in self.filtered_relation.path
+            ]
+        else:
+            filtered_relation = None
+        return self.__class__(
+            self.table_name,
+            new_parent_alias,
+            new_table_alias,
+            self.join_type,
+            self.join_field,
+            self.nullable,
+            filtered_relation=filtered_relation,
+        )
+
+    @property
+    def identity(self) -> tuple[type[Join], str, str, Any, Any]:
+        return (
+            self.__class__,
+            self.table_name,
+            self.parent_alias,
+            self.join_field,
+            self.filtered_relation,
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Join):
+            return NotImplemented
+        return self.identity == other.identity
+
+    def __hash__(self) -> int:
+        return hash(self.identity)
+
+    def equals(self, other: Join) -> bool:
+        # Ignore filtered_relation in equality check.
+        return self.identity[:-1] == other.identity[:-1]
+
+    def demote(self) -> Join:
+        new = self.relabeled_clone({})
+        new.join_type = INNER
+        return new
+
+    def promote(self) -> Join:
+        new = self.relabeled_clone({})
+        new.join_type = LOUTER
+        return new
+
+
+class BaseTable:
+    """
+    The BaseTable class is used for base table references in FROM clause. For
+    example, the SQL "foo" in
+        SELECT * FROM "foo" WHERE somecond
+    could be generated by this class.
+    """
+
+    join_type = None
+    parent_alias = None
+    filtered_relation = None
+
+    def __init__(self, table_name: str, alias: str) -> None:
+        self.table_name = table_name
+        self.table_alias = alias
+
+    def as_sql(
+        self, compiler: SQLCompiler, connection: DatabaseConnection
+    ) -> tuple[str, list[Any]]:
+        alias_str = (
+            "" if self.table_alias == self.table_name else (f" {self.table_alias}")
+        )
+        base_sql = compiler.quote_name_unless_alias(self.table_name)
+        return base_sql + alias_str, []
+
+    def relabeled_clone(self, change_map: dict[str, str]) -> BaseTable:
+        return self.__class__(
+            self.table_name, change_map.get(self.table_alias, self.table_alias)
+        )
+
+    @property
+    def identity(self) -> tuple[type[BaseTable], str, str]:
+        return self.__class__, self.table_name, self.table_alias
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, BaseTable):
+            return NotImplemented
+        return self.identity == other.identity
+
+    def __hash__(self) -> int:
+        return hash(self.identity)
+
+    def equals(self, other: BaseTable) -> bool:
+        return self.identity == other.identity