SQLAlchemy 2.1.0b2__cp313-cp313t-win_arm64.whl

sqlalchemy/sql/__init__.py

@@ -0,0 +1,156 @@
+# sql/__init__.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+from typing import Any
+from typing import TYPE_CHECKING
+
+from ._typing import ColumnExpressionArgument as ColumnExpressionArgument
+from ._typing import NotNullable as NotNullable
+from ._typing import Nullable as Nullable
+from .base import Executable as Executable
+from .base import ExecutableStatement as ExecutableStatement
+from .base import SyntaxExtension as SyntaxExtension
+from .compiler import COLLECT_CARTESIAN_PRODUCTS as COLLECT_CARTESIAN_PRODUCTS
+from .compiler import FROM_LINTING as FROM_LINTING
+from .compiler import NO_LINTING as NO_LINTING
+from .compiler import WARN_LINTING as WARN_LINTING
+from .ddl import BaseDDLElement as BaseDDLElement
+from .ddl import CheckFirst as CheckFirst
+from .ddl import DDL as DDL
+from .ddl import DDLElement as DDLElement
+from .ddl import ExecutableDDLElement as ExecutableDDLElement
+from .expression import aggregate_order_by as aggregate_order_by
+from .expression import Alias as Alias
+from .expression import alias as alias
+from .expression import all_ as all_
+from .expression import and_ as and_
+from .expression import any_ as any_
+from .expression import asc as asc
+from .expression import between as between
+from .expression import bindparam as bindparam
+from .expression import case as case
+from .expression import cast as cast
+from .expression import ClauseElement as ClauseElement
+from .expression import collate as collate
+from .expression import column as column
+from .expression import ColumnCollection as ColumnCollection
+from .expression import ColumnElement as ColumnElement
+from .expression import CompoundSelect as CompoundSelect
+from .expression import cte as cte
+from .expression import Delete as Delete
+from .expression import delete as delete
+from .expression import desc as desc
+from .expression import distinct as distinct
+from .expression import except_ as except_
+from .expression import except_all as except_all
+from .expression import exists as exists
+from .expression import extract as extract
+from .expression import false as false
+from .expression import False_ as False_
+from .expression import from_dml_column as from_dml_column
+from .expression import FromClause as FromClause
+from .expression import func as func
+from .expression import funcfilter as funcfilter
+from .expression import Insert as Insert
+from .expression import insert as insert
+from .expression import intersect as intersect
+from .expression import intersect_all as intersect_all
+from .expression import Join as Join
+from .expression import join as join
+from .expression import label as label
+from .expression import LABEL_STYLE_DEFAULT as LABEL_STYLE_DEFAULT
+from .expression import (
+    LABEL_STYLE_DISAMBIGUATE_ONLY as LABEL_STYLE_DISAMBIGUATE_ONLY,
+)
+from .expression import LABEL_STYLE_NONE as LABEL_STYLE_NONE
+from .expression import (
+    LABEL_STYLE_TABLENAME_PLUS_COL as LABEL_STYLE_TABLENAME_PLUS_COL,
+)
+from .expression import lambda_stmt as lambda_stmt
+from .expression import LambdaElement as LambdaElement
+from .expression import lateral as lateral
+from .expression import literal as literal
+from .expression import literal_column as literal_column
+from .expression import modifier as modifier
+from .expression import not_ as not_
+from .expression import null as null
+from .expression import nulls_first as nulls_first
+from .expression import nulls_last as nulls_last
+from .expression import nullsfirst as nullsfirst
+from .expression import nullslast as nullslast
+from .expression import or_ as or_
+from .expression import outerjoin as outerjoin
+from .expression import outparam as outparam
+from .expression import over as over
+from .expression import quoted_name as quoted_name
+from .expression import Select as Select
+from .expression import select as select
+from .expression import Selectable as Selectable
+from .expression import SelectLabelStyle as SelectLabelStyle
+from .expression import SQLColumnExpression as SQLColumnExpression
+from .expression import StatementLambdaElement as StatementLambdaElement
+from .expression import Subquery as Subquery
+from .expression import table as table
+from .expression import TableClause as TableClause
+from .expression import TableSample as TableSample
+from .expression import tablesample as tablesample
+from .expression import TableValuedAlias as TableValuedAlias
+from .expression import TableValuedColumn as TableValuedColumn
+from .expression import text as text
+from .expression import TextClause as TextClause
+from .expression import true as true
+from .expression import True_ as True_
+from .expression import try_cast as try_cast
+from .expression import TString as TString
+from .expression import tstring as tstring
+from .expression import tuple_ as tuple_
+from .expression import type_coerce as type_coerce
+from .expression import union as union
+from .expression import union_all as union_all
+from .expression import Update as Update
+from .expression import update as update
+from .expression import Values as Values
+from .expression import values as values
+from .expression import within_group as within_group
+from .expression import WriteableColumnCollection as WriteableColumnCollection
+from .visitors import ClauseVisitor as ClauseVisitor
+
+
+def __go(lcls: Any) -> None:
+    from .. import util as _sa_util
+
+    from . import base
+    from . import coercions
+    from . import elements
+    from . import lambdas
+    from . import selectable
+    from . import schema
+    from . import traversals
+    from . import type_api
+
+    if not TYPE_CHECKING:
+        base.coercions = elements.coercions = coercions
+        base.elements = elements
+        base.type_api = type_api
+        coercions.elements = elements
+        coercions.lambdas = lambdas
+        coercions.schema = schema
+        coercions.selectable = selectable
+
+    from .annotation import _prepare_annotations
+    from .annotation import Annotated
+    from .elements import AnnotatedColumnElement
+    from .elements import ClauseList
+    from .selectable import AnnotatedFromClause
+
+    _prepare_annotations(ColumnElement, AnnotatedColumnElement)
+    _prepare_annotations(FromClause, AnnotatedFromClause)
+    _prepare_annotations(ClauseList, Annotated)
+
+    _sa_util.preloaded.import_prefix("sqlalchemy.sql")
+
+
+__go(locals())

sqlalchemy/sql/_annotated_cols.py

@@ -0,0 +1,397 @@
+# sql/_annotated_cols.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+from __future__ import annotations
+
+from typing import Any
+from typing import Generic
+from typing import Literal
+from typing import NoReturn
+from typing import overload
+from typing import Protocol
+from typing import TYPE_CHECKING
+
+from . import sqltypes
+from ._typing import _T
+from ._typing import _Ts
+from .base import _NoArg
+from .base import ReadOnlyColumnCollection
+from .. import util
+from ..exc import ArgumentError
+from ..exc import InvalidRequestError
+from ..util import typing as sa_typing
+from ..util.langhelpers import dunders_re
+from ..util.typing import Never
+from ..util.typing import Self
+from ..util.typing import TypeVar
+from ..util.typing import Unpack
+
+if TYPE_CHECKING:
+    from .elements import ColumnClause  # noqa (for zimports)
+    from .elements import KeyedColumnElement  # noqa (for zimports)
+    from .schema import Column
+    from .type_api import TypeEngine
+    from ..util.typing import _AnnotationScanType
+
+
+class Named(Generic[_T]):
+    """A named descriptor that is interpreted by SQLAlchemy in various ways.
+
+    .. seealso::
+
+        :class:`_schema.TypedColumns` Define table columns using this
+        descriptor.
+
+    .. versionadded:: 2.1.0b2
+    """
+
+    __slots__ = ()
+
+    key: str
+    if TYPE_CHECKING:
+
+        # NOTE: this overload prevents users from using the a TypedColumns
+        # class like if it were an orm mapped class
+        @overload
+        def __get__(self, instance: None, owner: Any) -> Never: ...
+
+        @overload
+        def __get__(
+            self, instance: TypedColumns, owner: Any
+        ) -> Column[_T]: ...
+        @overload
+        def __get__(self, instance: Any, owner: Any) -> Self: ...
+
+        def __get__(self, instance: object | None, owner: Any) -> Any: ...
+
+
+# NOTE: TypedColumns subclasses are ignored by the ORM mapping process
+class TypedColumns(ReadOnlyColumnCollection[str, "Column[Any]"]):
+    """Class that generally represent the typed columns of a :class:`.Table`,
+    but can be used with most :class:`_sql.FromClause` subclasses with the
+    :meth:`_sql.FromClause.with_cols` method.
+
+    This is a "typing only" class that is never instantiated at runtime: the
+    type checker will think that this class is exposed as the ``table.c``
+    attribute, but in reality a normal :class:`_schema.ColumnCollection` is
+    used at runtime.
+
+    Subclasses should just list the columns as class attributes, without
+    specifying method or other non column members.
+
+    To resolve the columns, a simplified version of the ORM logic is used,
+    in particular, columns can be declared by:
+
+    * directly instantiating them, to declare constraint, custom SQL types and
+      additional column options;
+    * using only a :class:`.Named` or :class:`_schema.Column` type annotation,
+      where nullability and SQL type will be inferred by the python type
+      provided.
+      Type inference is available for a common subset of python types.
+    * a mix of both, where the instance can be used to declare
+      constraints and other column options while the annotation will be used
+      to set the SQL type and nullability if not provided by the instance.
+
+    In all cases the name is inferred from the attribute name, unless
+    explicitly provided.
+
+    .. note::
+
+        The generated table will create a copy of any column instance assigned
+        as attributes of this class, so columns should be accessed only via
+        the ``table.c`` collection, not using this class directly.
+
+    Example of the inference behavior::
+
+        from sqlalchemy import Column, Integer, Named, String, TypedColumns
+
+
+        class tbl_cols(TypedColumns):
+            # the name will be set to ``id``, type is inferred as Column[int]
+            id = Column(Integer, primary_key=True)
+
+            # not null String column is generated
+            name: Named[str]
+
+            # nullable Double column is generated
+            weight: Named[float | None]
+
+            # nullable Integer column, with sql name 'user_age'
+            age: Named[int | None] = Column("user_age")
+
+            # not null column with type String(42)
+            middle_name: Named[str] = Column(String(42))
+
+    Mixins and subclasses are also supported::
+
+        class with_id(TypedColumns):
+            id = Column(Integer, primary_key=True)
+
+
+        class named_cols(TypedColumns):
+            name: Named[str]
+            description: Named[str | None]
+
+
+        class product_cols(named_cols, with_id):
+            ean: Named[str] = Column(unique=True)
+
+
+        product = Table("product", metadata, product_cols)
+
+
+        class office_cols(named_cols, with_id):
+            address: Named[str]
+
+
+        office = Table("office", metadata, office_cols)
+
+    The positional types returned when selecting the table can
+    be optionally declared by specifying a :attr:`.HasRowPos.__row_pos__`
+    annotation::
+
+        from sqlalchemy import select
+
+
+        class some_cols(TypedColumns):
+            id = Column(Integer, primary_key=True)
+            name: Named[str]
+            weight: Named[float | None]
+
+            __row_pos__: tuple[int, str, float | None]
+
+
+        some_table = Table("st", metadata, some_cols)
+
+        # both will be typed as Select[int, str, float | None]
+        stmt1 = some_table.select()
+        stmt2 = select(some_table)
+
+    .. seealso::
+
+        :class:`.Table` for usage details on how to use this class to
+        create a table instance.
+
+        :meth:`_sql.FromClause.with_cols` to apply a :class:`.TypedColumns`
+        to a from clause.
+
+    .. versionadded:: 2.1.0b2
+    """  # noqa
+
+    __slots__ = ()
+
+    if not TYPE_CHECKING:
+
+        def __new__(cls, *args: Any, **kwargs: Any) -> NoReturn:
+            raise InvalidRequestError(
+                "Cannot instantiate a TypedColumns object."
+            )
+
+    def __init_subclass__(cls) -> None:
+        methods = {
+            name
+            for name, value in cls.__dict__.items()
+            if not dunders_re.match(name) and callable(value)
+        }
+        if methods:
+            raise InvalidRequestError(
+                "TypedColumns subclasses may not define methods. "
+                f"Found {sorted(methods)}"
+            )
+
+
+_KeyColCC_co = TypeVar(
+    "_KeyColCC_co",
+    bound=ReadOnlyColumnCollection[str, "KeyedColumnElement[Any]"],
+    covariant=True,
+    default=ReadOnlyColumnCollection[str, "KeyedColumnElement[Any]"],
+)
+_ColClauseCC_co = TypeVar(
+    "_ColClauseCC_co",
+    bound=ReadOnlyColumnCollection[str, "ColumnClause[Any]"],
+    covariant=True,
+    default=ReadOnlyColumnCollection[str, "ColumnClause[Any]"],
+)
+_ColCC_co = TypeVar(
+    "_ColCC_co",
+    bound=ReadOnlyColumnCollection[str, "Column[Any]"],
+    covariant=True,
+    default=ReadOnlyColumnCollection[str, "Column[Any]"],
+)
+
+_TC = TypeVar("_TC", bound=TypedColumns)
+_TC_co = TypeVar("_TC_co", bound=TypedColumns, covariant=True)
+
+
+class HasRowPos(Protocol[Unpack[_Ts]]):
+    """Protocol for a :class:`_schema.TypedColumns` used to indicate the
+    positional types will be returned when selecting the table.
+
+    .. versionadded:: 2.1.0b2
+    """
+
+    __row_pos__: tuple[Unpack[_Ts]]
+    """A tuple that represents the types that will be returned when
+    selecting from the table.
+    """
+
+
+@util.preload_module("sqlalchemy.sql.schema")
+def _extract_columns_from_class(
+    table_columns_cls: type[TypedColumns],
+) -> list[Column[Any]]:
+    columns: dict[str, Column[Any]] = {}
+
+    Column = util.preloaded.sql_schema.Column
+    NULL_UNSPECIFIED = util.preloaded.sql_schema.NULL_UNSPECIFIED
+
+    for base in table_columns_cls.__mro__[::-1]:
+        if base in TypedColumns.__mro__:
+            continue
+
+        # _ClassScanAbstractConfig._cls_attr_resolver
+        cls_annotations = util.get_annotations(base)
+        cls_vars = vars(base)
+        items = [
+            (n, cls_vars.get(n), cls_annotations.get(n))
+            for n in util.merge_lists_w_ordering(
+                list(cls_vars), list(cls_annotations)
+            )
+            if not dunders_re.match(n)
+        ]
+        # --
+        for name, obj, annotation in items:
+            if obj is None:
+                assert annotation is not None
+                # no attribute, just annotation
+                extracted_type = _collect_annotation(
+                    table_columns_cls, name, base.__module__, annotation
+                )
+                if extracted_type is _NoArg.NO_ARG:
+                    raise ArgumentError(
+                        "No type information could be extracted from "
+                        f"annotation {annotation} for attribute "
+                        f"'{base.__name__}.{name}'"
+                    )
+                sqltype = _get_sqltype(extracted_type)
+                if sqltype is None:
+                    raise ArgumentError(
+                        f"Could not find a SQL type for type {extracted_type} "
+                        f"obtained from annotation {annotation} in "
+                        f"attribute '{base.__name__}.{name}'"
+                    )
+                columns[name] = Column(
+                    name,
+                    sqltype,
+                    nullable=sa_typing.includes_none(extracted_type),
+                )
+            elif isinstance(obj, Column):
+                # has attribute attribute
+                # _DeclarativeMapperConfig._produce_column_copies
+                # as with orm this case is not supported
+                for fk in obj.foreign_keys:
+                    if (
+                        fk._table_column is not None
+                        and fk._table_column.table is None
+                    ):
+                        raise InvalidRequestError(
+                            f"Column '{base.__name__}.{name}' with foreign "
+                            "key to non-table-bound columns is not supported "
+                            "when using a TypedColumns. If possible use the "
+                            "qualified string name the column"
+                        )
+
+                col = obj._copy()
+                # MapptedColumn.declarative_scan
+                if col.key == col.name and col.key != name:
+                    col.key = name
+                if col.name is None:
+                    col.name = name
+
+                sqltype = col.type
+                anno_sqltype = None
+                nullable: Literal[_NoArg.NO_ARG] | bool = _NoArg.NO_ARG
+                if annotation is not None:
+                    # there is an annotation, extract the type
+                    extracted_type = _collect_annotation(
+                        table_columns_cls, name, base.__module__, annotation
+                    )
+                    if extracted_type is not _NoArg.NO_ARG:
+                        anno_sqltype = _get_sqltype(extracted_type)
+                        nullable = sa_typing.includes_none(extracted_type)
+
+                if sqltype._isnull:
+                    if anno_sqltype is None and not col.foreign_keys:
+                        raise ArgumentError(
+                            "Python typing annotation is required for "
+                            f"attribute '{base.__name__}.{name}' when "
+                            "primary argument(s) for Column construct are "
+                            "None or not present"
+                        )
+                    elif anno_sqltype is not None:
+                        col._set_type(anno_sqltype)
+
+                if (
+                    nullable is not _NoArg.NO_ARG
+                    and col._user_defined_nullable is NULL_UNSPECIFIED
+                    and not col.primary_key
+                ):
+                    col.nullable = nullable
+                columns[name] = col
+            else:
+                raise ArgumentError(
+                    f"Unexpected value for attribute '{base.__name__}.{name}'"
+                    f". Expected a Column, not: {type(obj)}"
+                )
+
+    # Return columns as a list
+    return list(columns.values())
+
+
+@util.preload_module("sqlalchemy.sql.schema")
+def _collect_annotation(
+    cls: type[Any], name: str, module: str, raw_annotation: _AnnotationScanType
+) -> _AnnotationScanType | Literal[_NoArg.NO_ARG]:
+    Column = util.preloaded.sql_schema.Column
+
+    _locals = {"Column": Column, "Named": Named}
+    # _ClassScanAbstractConfig._collect_annotation & _extract_mapped_subtype
+    try:
+        annotation = sa_typing.de_stringify_annotation(
+            cls, raw_annotation, module, _locals
+        )
+    except Exception as e:
+        raise ArgumentError(
+            f"Could not interpret annotation {raw_annotation} for "
+            f"attribute '{cls.__name__}.{name}'"
+        ) from e
+
+    if (
+        not sa_typing.is_generic(annotation)
+        and isinstance(annotation, type)
+        and issubclass(annotation, (Column, Named))
+    ):
+        # no generic information, ignore
+        return _NoArg.NO_ARG
+    elif not sa_typing.is_origin_of_cls(annotation, (Column, Named)):
+        raise ArgumentError(
+            f"Annotation {raw_annotation} for attribute "
+            f"'{cls.__name__}.{name}' is not of type Named/Column[...]"
+        )
+    else:
+        assert len(annotation.__args__) == 1  # Column[int, int] raises
+        return annotation.__args__[0]  # type: ignore[no-any-return]
+
+
+def _get_sqltype(annotation: _AnnotationScanType) -> TypeEngine[Any] | None:
+    our_type = sa_typing.de_optionalize_union_types(annotation)
+    # simplified version of registry._resolve_type given no customizable
+    # type map
+    sql_type = sqltypes._type_map_get(our_type)  # type: ignore[arg-type]
+    if sql_type is not None and not sql_type._isnull:
+        return sqltypes.to_instance(sql_type)
+    else:
+        return None

sqlalchemy/sql/_dml_constructors.py

@@ -0,0 +1,132 @@
+# sql/_dml_constructors.py
+# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
+# <see AUTHORS file>
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: https://www.opensource.org/licenses/mit-license.php
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .dml import Delete
+from .dml import Insert
+from .dml import Update
+
+if TYPE_CHECKING:
+    from ._typing import _DMLTableArgument
+
+
+def insert(table: _DMLTableArgument) -> Insert:
+    """Construct an :class:`_expression.Insert` object.
+
+    E.g.::
+
+        from sqlalchemy import insert
+
+        stmt = insert(user_table).values(name="username", fullname="Full Username")
+
+    Similar functionality is available via the
+    :meth:`_expression.TableClause.insert` method on
+    :class:`_schema.Table`.
+
+    .. seealso::
+
+        :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
+
+
+    :param table: :class:`_expression.TableClause`
+     which is the subject of the
+     insert.
+
+    :param values: collection of values to be inserted; see
+     :meth:`_expression.Insert.values`
+     for a description of allowed formats here.
+     Can be omitted entirely; a :class:`_expression.Insert` construct
+     will also dynamically render the VALUES clause at execution time
+     based on the parameters passed to :meth:`_engine.Connection.execute`.
+
+    :param inline: if True, no attempt will be made to retrieve the
+     SQL-generated default values to be provided within the statement;
+     in particular,
+     this allows SQL expressions to be rendered 'inline' within the
+     statement without the need to pre-execute them beforehand; for
+     backends that support "returning", this turns off the "implicit
+     returning" feature for the statement.
+
+    If both :paramref:`_expression.insert.values` and compile-time bind
+    parameters are present, the compile-time bind parameters override the
+    information specified within :paramref:`_expression.insert.values` on a
+    per-key basis.
+
+    The keys within :paramref:`_expression.Insert.values` can be either
+    :class:`~sqlalchemy.schema.Column` objects or their string
+    identifiers. Each key may reference one of:
+
+    * a literal data value (i.e. string, number, etc.);
+    * a Column object;
+    * a SELECT statement.
+
+    If a ``SELECT`` statement is specified which references this
+    ``INSERT`` statement's table, the statement will be correlated
+    against the ``INSERT`` statement.
+
+    .. seealso::
+
+        :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
+
+    """  # noqa: E501
+    return Insert(table)
+
+
+def update(table: _DMLTableArgument) -> Update:
+    r"""Construct an :class:`_expression.Update` object.
+
+    E.g.::
+
+        from sqlalchemy import update
+
+        stmt = (
+            update(user_table).where(user_table.c.id == 5).values(name="user #5")
+        )
+
+    Similar functionality is available via the
+    :meth:`_expression.TableClause.update` method on
+    :class:`_schema.Table`.
+
+    :param table: A :class:`_schema.Table`
+     object representing the database
+     table to be updated.
+
+
+    .. seealso::
+
+        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
+
+
+    """  # noqa: E501
+    return Update(table)
+
+
+def delete(table: _DMLTableArgument) -> Delete:
+    r"""Construct :class:`_expression.Delete` object.
+
+    E.g.::
+
+        from sqlalchemy import delete
+
+        stmt = delete(user_table).where(user_table.c.id == 5)
+
+    Similar functionality is available via the
+    :meth:`_expression.TableClause.delete` method on
+    :class:`_schema.Table`.
+
+    :param table: The table to delete rows from.
+
+    .. seealso::
+
+        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
+
+
+    """
+    return Delete(table)