Edit - selectable.py

Edit: selectable.py

# sql/selectable.py
# Copyright (C) 2005-2021 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php

"""The :class:`_expression.FromClause` class of SQL expression elements,
representing
SQL tables and derived rowsets.

"""

import collections
import itertools
import operator
from operator import attrgetter

from sqlalchemy.sql.visitors import Visitable
from . import operators
from . import type_api
from .annotation import Annotated
from .base import _from_objects
from .base import _generative
from .base import ColumnCollection
from .base import ColumnSet
from .base import Executable
from .base import Generative
from .base import Immutable
from .elements import _anonymous_label
from .elements import _clause_element_as_expr
from .elements import _clone
from .elements import _cloned_difference
from .elements import _cloned_intersection
from .elements import _document_text_coercion
from .elements import _expand_cloned
from .elements import _interpret_as_column_or_from
from .elements import _literal_and_labels_as_label_reference
from .elements import _literal_as_label_reference
from .elements import _literal_as_text
from .elements import _no_text_coercion
from .elements import _select_iterables
from .elements import and_
from .elements import BindParameter
from .elements import ClauseElement
from .elements import ClauseList
from .elements import Grouping
from .elements import literal_column
from .elements import True_
from .elements import UnaryExpression
from .. import exc
from .. import inspection
from .. import util

def _interpret_as_from(element):
    insp = inspection.inspect(element, raiseerr=False)
    if insp is None:
        if isinstance(element, util.string_types):
            _no_text_coercion(element)
    try:
        return insp.selectable
    except AttributeError as err:
        util.raise_(
            exc.ArgumentError("FROM expression expected"), replace_context=err
        )

def _interpret_as_select(element):
    element = _interpret_as_from(element)
    if isinstance(element, Alias):
        element = element.original
    if not isinstance(element, SelectBase):
        element = element.select()
    return element

class _OffsetLimitParam(BindParameter):
    @property
    def _limit_offset_value(self):
        return self.effective_value

def _offset_or_limit_clause(element, name=None, type_=None):
    """Convert the given value to an "offset or limit" clause.

This handles incoming integers and converts to an expression; if
    an expression is already given, it is passed through.

"""
    if element is None:
        return None
    elif hasattr(element, "__clause_element__"):
        return element.__clause_element__()
    elif isinstance(element, Visitable):
        return element
    else:
        value = util.asint(element)
        return _OffsetLimitParam(name, value, type_=type_, unique=True)

def _offset_or_limit_clause_asint(clause, attrname):
    """Convert the "offset or limit" clause of a select construct to an
    integer.

This is only possible if the value is stored as a simple bound parameter.
    Otherwise, a compilation error is raised.

"""
    if clause is None:
        return None
    try:
        value = clause._limit_offset_value
    except AttributeError as err:
        util.raise_(
            exc.CompileError(
                "This SELECT structure does not use a simple "
                "integer value for %s" % attrname
            ),
            replace_context=err,
        )
    else:
        return util.asint(value)

def subquery(alias, *args, **kwargs):
    r"""Return an :class:`_expression.Alias` object derived
    from a :class:`_expression.Select`.

:param alias: the alias name

:param \*args, \**kwargs:  all other arguments are delivered to the
     :func:`_expression.select` function.

"""
    return Select(*args, **kwargs).alias(alias)

class Selectable(ClauseElement):
    """Mark a class as being selectable."""

__visit_name__ = "selectable"

is_selectable = True

@property
    def selectable(self):
        return self

class HasPrefixes(object):
    _prefixes = ()

@_generative
    @_document_text_coercion(
        "expr",
        ":meth:`_expression.HasPrefixes.prefix_with`",
        ":paramref:`.HasPrefixes.prefix_with.*expr`",
    )
    def prefix_with(self, *expr, **kw):
        r"""Add one or more expressions following the statement keyword, i.e.
        SELECT, INSERT, UPDATE, or DELETE. Generative.

This is used to support backend-specific prefix keywords such as those
        provided by MySQL.

E.g.::

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

# MySQL 5.7 optimizer hints
            stmt = select([table]).prefix_with(
                "/*+ BKA(t1) */", dialect="mysql")

Multiple prefixes can be specified by multiple calls
        to :meth:`_expression.HasPrefixes.prefix_with`.

:param \*expr: textual or :class:`_expression.ClauseElement`
         construct which
         will be rendered following the INSERT, UPDATE, or DELETE
         keyword.
        :param \**kw: A single keyword 'dialect' is accepted.  This is an
         optional string dialect name which will
         limit rendering of this prefix to only that dialect.

"""
        dialect = kw.pop("dialect", None)
        if kw:
            raise exc.ArgumentError(
                "Unsupported argument(s): %s" % ",".join(kw)
            )
        self._setup_prefixes(expr, dialect)

def _setup_prefixes(self, prefixes, dialect=None):
        self._prefixes = self._prefixes + tuple(
            [
                (_literal_as_text(p, allow_coercion_to_text=True), dialect)
                for p in prefixes
            ]
        )

class HasSuffixes(object):
    _suffixes = ()

@_generative
    @_document_text_coercion(
        "expr",
        ":meth:`_expression.HasSuffixes.suffix_with`",
        ":paramref:`.HasSuffixes.suffix_with.*expr`",
    )
    def suffix_with(self, *expr, **kw):
        r"""Add one or more expressions following the statement as a whole.

This is used to support backend-specific suffix keywords on
        certain constructs.

E.g.::

stmt = select([col1, col2]).cte().suffix_with(
                "cycle empno set y_cycle to 1 default 0", dialect="oracle")

Multiple suffixes can be specified by multiple calls
        to :meth:`_expression.HasSuffixes.suffix_with`.

:param \*expr: textual or :class:`_expression.ClauseElement`
         construct which
         will be rendered following the target clause.
        :param \**kw: A single keyword 'dialect' is accepted.  This is an
         optional string dialect name which will
         limit rendering of this suffix to only that dialect.

"""
        dialect = kw.pop("dialect", None)
        if kw:
            raise exc.ArgumentError(
                "Unsupported argument(s): %s" % ",".join(kw)
            )
        self._setup_suffixes(expr, dialect)

def _setup_suffixes(self, suffixes, dialect=None):
        self._suffixes = self._suffixes + tuple(
            [
                (_literal_as_text(p, allow_coercion_to_text=True), dialect)
                for p in suffixes
            ]
        )

class FromClause(Selectable):
    """Represent an element that can be used within the ``FROM``
    clause of a ``SELECT`` statement.

The most common forms of :class:`_expression.FromClause` are the
    :class:`_schema.Table` and the :func:`_expression.select` constructs.  Key
    features common to all :class:`_expression.FromClause` objects include:

* a :attr:`.c` collection, which provides per-name access to a collection
      of :class:`_expression.ColumnElement` objects.
    * a :attr:`.primary_key` attribute, which is a collection of all those
      :class:`_expression.ColumnElement`
      objects that indicate the ``primary_key`` flag.
    * Methods to generate various derivations of a "from" clause, including
      :meth:`_expression.FromClause.alias`,
      :meth:`_expression.FromClause.join`,
      :meth:`_expression.FromClause.select`.

"""

__visit_name__ = "fromclause"
    named_with_column = False
    _hide_froms = []

_is_join = False
    _is_select = False
    _is_from_container = False

_is_lateral = False

_textual = False
    """A marker that allows us to easily distinguish a :class:`.TextAsFrom`
    or similar object from other kinds of :class:`_expression.FromClause`
    objects."""

schema = None
    """Define the 'schema' attribute for this :class:`_expression.FromClause`.

This is typically ``None`` for most objects except that of
    :class:`_schema.Table`, where it is taken as the value of the
    :paramref:`_schema.Table.schema` argument.

"""

def _translate_schema(self, effective_schema, map_):
        return effective_schema

_memoized_property = util.group_expirable_memoized_property(["_columns"])

@util.deprecated(
        "1.1",
        message="The :meth:`.FromClause.count` method is deprecated, "
        "and will be removed in a future release.   Please use the "
        ":class:`_functions.count` function available from the "
        ":attr:`.func` namespace.",
    )
    @util.dependencies("sqlalchemy.sql.functions")
    def count(self, functions, whereclause=None, **params):
        """Return a SELECT COUNT generated against this
        :class:`_expression.FromClause`.

.. seealso::

:class:`_functions.count`

"""

if self.primary_key:
            col = list(self.primary_key)[0]
        else:
            col = list(self.columns)[0]
        return Select(
            [functions.func.count(col).label("tbl_row_count")],
            whereclause,
            from_obj=[self],
            **params
        )

def select(self, whereclause=None, **params):
        """Return a SELECT of this :class:`_expression.FromClause`.

.. seealso::

:func:`_expression.select` - general purpose
            method which allows for arbitrary column lists.

"""

return Select([self], whereclause, **params)

def join(self, right, onclause=None, isouter=False, full=False):
        """Return a :class:`_expression.Join` from this
        :class:`_expression.FromClause` to another
        :class:`_expression.FromClause`.

E.g.::

from sqlalchemy import join

j = user_table.join(address_table,
                            user_table.c.id == address_table.c.user_id)
            stmt = select([user_table]).select_from(j)

would emit SQL along the lines of::

SELECT user.id, user.name FROM user
            JOIN address ON user.id = address.user_id

:param right: the right side of the join; this is any
         :class:`_expression.FromClause` object such as a
         :class:`_schema.Table` object, and
         may also be a selectable-compatible object such as an ORM-mapped
         class.

:param onclause: a SQL expression representing the ON clause of the
         join.  If left at ``None``, :meth:`_expression.FromClause.join`
         will attempt to
         join the two tables based on a foreign key relationship.

:param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.

:param full: if True, render a FULL OUTER JOIN, instead of LEFT OUTER
         JOIN.  Implies :paramref:`.FromClause.join.isouter`.

.. versionadded:: 1.1

.. seealso::

:func:`_expression.join` - standalone function

:class:`_expression.Join` - the type of object produced

"""

return Join(self, right, onclause, isouter, full)

def outerjoin(self, right, onclause=None, full=False):
        """Return a :class:`_expression.Join` from this
        :class:`_expression.FromClause`
        to another :class:`FromClause`, with the "isouter" flag set to
        True.

E.g.::

from sqlalchemy import outerjoin

j = user_table.outerjoin(address_table,
                            user_table.c.id == address_table.c.user_id)

The above is equivalent to::

j = user_table.join(
                address_table,
                user_table.c.id == address_table.c.user_id,
                isouter=True)

:param full: if True, render a FULL OUTER JOIN, instead of
         LEFT OUTER JOIN.

.. versionadded:: 1.1

.. seealso::

:meth:`_expression.FromClause.join`

:class:`_expression.Join`

"""

return Join(self, right, onclause, True, full)

def alias(self, name=None, flat=False):
        """Return an alias of this :class:`_expression.FromClause`.

E.g.::

a2 = some_table.alias('a2')

The above code creates an :class:`_expression.Alias`
        object which can be used
        as a FROM clause in any SELECT statement.

.. seealso::

:ref:`core_tutorial_aliases`

:func:`_expression.alias`

"""

return Alias._construct(self, name)

def lateral(self, name=None):
        """Return a LATERAL alias of this :class:`_expression.FromClause`.

The return value is the :class:`_expression.Lateral` construct also
        provided by the top-level :func:`_expression.lateral` function.

.. versionadded:: 1.1

.. seealso::

:ref:`lateral_selects` -  overview of usage.

"""
        return Lateral._construct(self, name)

def tablesample(self, sampling, name=None, seed=None):
        """Return a TABLESAMPLE alias of this :class:`_expression.FromClause`.

The return value is the :class:`_expression.TableSample`
        construct also
        provided by the top-level :func:`_expression.tablesample` function.

.. versionadded:: 1.1

.. seealso::

:func:`_expression.tablesample` - usage guidelines and parameters

"""
        return TableSample._construct(self, sampling, name, seed)

def is_derived_from(self, fromclause):
        """Return ``True`` if this :class:`_expression.FromClause` is
        'derived' from the given ``FromClause``.

An example would be an Alias of a Table is derived from that Table.

"""
        # this is essentially an "identity" check in the base class.
        # Other constructs override this to traverse through
        # contained elements.
        return fromclause in self._cloned_set

def _is_lexical_equivalent(self, other):
        """Return ``True`` if this :class:`_expression.FromClause` and
        the other represent the same lexical identity.

This tests if either one is a copy of the other, or
        if they are the same via annotation identity.

"""
        return self._cloned_set.intersection(other._cloned_set)

@util.dependencies("sqlalchemy.sql.util")
    def replace_selectable(self, sqlutil, old, alias):
        """Replace all occurrences of FromClause 'old' with the given Alias
        object, returning a copy of this :class:`_expression.FromClause`.

"""

return sqlutil.ClauseAdapter(alias).traverse(self)

def correspond_on_equivalents(self, column, equivalents):
        """Return corresponding_column for the given column, or if None
        search for a match in the given dictionary.

"""
        col = self.corresponding_column(column, require_embedded=True)
        if col is None and col in equivalents:
            for equiv in equivalents[col]:
                nc = self.corresponding_column(equiv, require_embedded=True)
                if nc:
                    return nc
        return col

def corresponding_column(self, column, require_embedded=False):
        """Given a :class:`_expression.ColumnElement`, return the exported
        :class:`_expression.ColumnElement` object from this
        :class:`expression.Selectable`
        which corresponds to that original
        :class:`~sqlalchemy.schema.Column` via a common ancestor
        column.

:param column: the target :class:`_expression.ColumnElement`
                      to be matched

:param require_embedded: only return corresponding columns for
         the given :class:`_expression.ColumnElement`, if the given
         :class:`_expression.ColumnElement`
         is actually present within a sub-element
         of this :class:`_expression.FromClause`.
         Normally the column will match if
         it merely shares a common ancestor with one of the exported
         columns of this :class:`_expression.FromClause`.

"""

def embedded(expanded_proxy_set, target_set):
            for t in target_set.difference(expanded_proxy_set):
                if not set(_expand_cloned([t])).intersection(
                    expanded_proxy_set
                ):
                    return False
            return True

# don't dig around if the column is locally present
        if self.c.contains_column(column):
            return column
        col, intersect = None, None
        target_set = column.proxy_set
        cols = self.c._all_columns
        for c in cols:
            expanded_proxy_set = set(_expand_cloned(c.proxy_set))
            i = target_set.intersection(expanded_proxy_set)
            if i and (
                not require_embedded
                or embedded(expanded_proxy_set, target_set)
            ):
                if col is None:

# no corresponding column yet, pick this one.

col, intersect = c, i
                elif len(i) > len(intersect):

# 'c' has a larger field of correspondence than
                    # 'col'. i.e. selectable.c.a1_x->a1.c.x->table.c.x
                    # matches a1.c.x->table.c.x better than
                    # selectable.c.x->table.c.x does.

col, intersect = c, i
                elif i == intersect:

# they have the same field of correspondence. see
                    # which proxy_set has fewer columns in it, which
                    # indicates a closer relationship with the root
                    # column. Also take into account the "weight"
                    # attribute which CompoundSelect() uses to give
                    # higher precedence to columns based on vertical
                    # position in the compound statement, and discard
                    # columns that have no reference to the target
                    # column (also occurs with CompoundSelect)

col_distance = util.reduce(
                        operator.add,
                        [
                            sc._annotations.get("weight", 1)
                            for sc in col._uncached_proxy_set()
                            if sc.shares_lineage(column)
                        ],
                    )
                    c_distance = util.reduce(
                        operator.add,
                        [
                            sc._annotations.get("weight", 1)
                            for sc in c._uncached_proxy_set()
                            if sc.shares_lineage(column)
                        ],
                    )
                    if c_distance < col_distance:
                        col, intersect = c, i
        return col

@property
    def description(self):
        """A brief description of this :class:`_expression.FromClause`.

Used primarily for error message formatting.

"""
        return getattr(self, "name", self.__class__.__name__ + " object")

def _reset_exported(self):
        """Delete memoized collections when a FromClause is cloned."""

self._memoized_property.expire_instance(self)

@_memoized_property
    def columns(self):
        """A named-based collection of :class:`_expression.ColumnElement`
        objects
        maintained by this :class:`_expression.FromClause`.

The :attr:`.columns`, or :attr:`.c` collection, is the gateway
        to the construction of SQL expressions using table-bound or
        other selectable-bound columns::

select([mytable]).where(mytable.c.somecolumn == 5)

"""

if "_columns" not in self.__dict__:
            self._init_collections()
            self._populate_column_collection()
        return self._columns.as_immutable()

@_memoized_property
    def primary_key(self):
        """Return the collection of :class:`_schema.Column` objects
        which comprise the primary key of this FromClause.

"""
        self._init_collections()
        self._populate_column_collection()
        return self.primary_key

@_memoized_property
    def foreign_keys(self):
        """Return the collection of :class:`_schema.ForeignKey` objects
        which this FromClause references.

"""
        self._init_collections()
        self._populate_column_collection()
        return self.foreign_keys

c = property(
        attrgetter("columns"),
        doc="An alias for the :attr:`.columns` attribute.",
    )
    _select_iterable = property(attrgetter("columns"))

def _init_collections(self):
        assert "_columns" not in self.__dict__
        assert "primary_key" not in self.__dict__
        assert "foreign_keys" not in self.__dict__

self._columns = ColumnCollection()
        self.primary_key = ColumnSet()
        self.foreign_keys = set()

@property
    def _cols_populated(self):
        return "_columns" in self.__dict__

def _populate_column_collection(self):
        """Called on subclasses to establish the .c collection.

Each implementation has a different way of establishing
        this collection.

"""

def _refresh_for_new_column(self, column):
        """Given a column added to the .c collection of an underlying
        selectable, produce the local version of that column, assuming this
        selectable ultimately should proxy this column.

this is used to "ping" a derived selectable to add a new column
        to its .c. collection when a Column has been added to one of the
        Table objects it ultimtely derives from.

If the given selectable hasn't populated its .c. collection yet,
        it should at least pass on the message to the contained selectables,
        but it will return None.

This method is currently used by Declarative to allow Table
        columns to be added to a partially constructed inheritance
        mapping that may have already produced joins.  The method
        isn't public right now, as the full span of implications
        and/or caveats aren't yet clear.

It's also possible that this functionality could be invoked by
        default via an event, which would require that
        selectables maintain a weak referencing collection of all
        derivations.

"""
        if not self._cols_populated:
            return None
        elif column.key in self.columns and self.columns[column.key] is column:
            return column
        else:
            return None

class Join(FromClause):
    """Represent a ``JOIN`` construct between two
    :class:`_expression.FromClause` elements.

The public constructor function for :class:`_expression.Join`
    is the module-level
    :func:`_expression.join()` function, as well as the
    :meth:`_expression.FromClause.join` method
    of any :class:`_expression.FromClause` (e.g. such as
    :class:`_schema.Table`).

.. seealso::

:func:`_expression.join`

:meth:`_expression.FromClause.join`

"""

__visit_name__ = "join"

_is_join = True

def __init__(self, left, right, onclause=None, isouter=False, full=False):
        """Construct a new :class:`_expression.Join`.

The usual entrypoint here is the :func:`_expression.join`
        function or the :meth:`_expression.FromClause.join` method of any
        :class:`_expression.FromClause` object.

"""
        self.left = _interpret_as_from(left)
        self.right = _interpret_as_from(right).self_group()

if onclause is None:
            self.onclause = self._match_primaries(self.left, self.right)
        else:
            self.onclause = onclause

self.isouter = isouter
        self.full = full

@classmethod
    def _create_outerjoin(cls, left, right, onclause=None, full=False):
        """Return an ``OUTER JOIN`` clause element.

The returned object is an instance of :class:`_expression.Join`.

Similar functionality is also available via the
        :meth:`_expression.FromClause.outerjoin` method on any
        :class:`_expression.FromClause`.

:param left: The left side of the join.

:param right: The right side of the join.

:param onclause:  Optional criterion for the ``ON`` clause, is
          derived from foreign key relationships established between
          left and right otherwise.

To chain joins together, use the :meth:`_expression.FromClause.join`
        or
        :meth:`_expression.FromClause.outerjoin` methods on the resulting
        :class:`_expression.Join` object.

"""
        return cls(left, right, onclause, isouter=True, full=full)

@classmethod
    def _create_join(
        cls, left, right, onclause=None, isouter=False, full=False
    ):
        """Produce a :class:`_expression.Join` object, given two
        :class:`_expression.FromClause`
        expressions.

E.g.::

j = join(user_table, address_table,
                     user_table.c.id == address_table.c.user_id)
            stmt = select([user_table]).select_from(j)

would emit SQL along the lines of::

SELECT user.id, user.name FROM user
            JOIN address ON user.id = address.user_id

Similar functionality is available given any
        :class:`_expression.FromClause` object (e.g. such as a
        :class:`_schema.Table`) using
        the :meth:`_expression.FromClause.join` method.

:param left: The left side of the join.

:param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.

:param full: if True, render a FULL OUTER JOIN, instead of JOIN.

.. versionadded:: 1.1

.. seealso::

:meth:`_expression.FromClause.join` - method form,
            based on a given left side.

:class:`_expression.Join` - the type of object produced.

"""

return cls(left, right, onclause, isouter, full)

@property
    def description(self):
        return "Join object on %s(%d) and %s(%d)" % (
            self.left.description,
            id(self.left),
            self.right.description,
            id(self.right),
        )

def is_derived_from(self, fromclause):
        return (
            fromclause is self
            or self.left.is_derived_from(fromclause)
            or self.right.is_derived_from(fromclause)
        )

def self_group(self, against=None):
        return FromGrouping(self)

@util.dependencies("sqlalchemy.sql.util")
    def _populate_column_collection(self, sqlutil):
        columns = [c for c in self.left.columns] + [
            c for c in self.right.columns
        ]

self.primary_key.extend(
            sqlutil.reduce_columns(
                (c for c in columns if c.primary_key), self.onclause
            )
        )
        self._columns.update((col._label, col) for col in columns)
        self.foreign_keys.update(
            itertools.chain(*[col.foreign_keys for col in columns])
        )

def _refresh_for_new_column(self, column):
        col = self.left._refresh_for_new_column(column)
        if col is None:
            col = self.right._refresh_for_new_column(column)
        if col is not None:
            if self._cols_populated:
                self._columns[col._label] = col
                self.foreign_keys.update(col.foreign_keys)
                if col.primary_key:
                    self.primary_key.add(col)
                return col
        return None

def _copy_internals(self, clone=_clone, **kw):
        self._reset_exported()
        self.left = clone(self.left, **kw)
        self.right = clone(self.right, **kw)
        self.onclause = clone(self.onclause, **kw)

def get_children(self, **kwargs):
        return self.left, self.right, self.onclause

def _match_primaries(self, left, right):
        if isinstance(left, Join):
            left_right = left.right
        else:
            left_right = None
        return self._join_condition(left, right, a_subset=left_right)

@classmethod
    @util.deprecated_params(
        ignore_nonexistent_tables=(
            "0.9",
            "The :paramref:`.join_condition.ignore_nonexistent_tables` "
            "parameter is deprecated and will be removed in a future "
            "release.  Tables outside of the two tables being handled "
            "are no longer considered.",
        )
    )
    def _join_condition(
        cls,
        a,
        b,
        ignore_nonexistent_tables=False,
        a_subset=None,
        consider_as_foreign_keys=None,
    ):
        """Create a join condition between two tables or selectables.

e.g.::

join_condition(tablea, tableb)

would produce an expression along the lines of::

tablea.c.id==tableb.c.tablea_id

The join is determined based on the foreign key relationships
        between the two selectables.   If there are multiple ways
        to join, or no way to join, an error is raised.

:param ignore_nonexistent_tables: unused - tables outside of the
         two tables being handled are not considered.

:param a_subset: An optional expression that is a sub-component
         of ``a``.  An attempt will be made to join to just this sub-component
         first before looking at the full ``a`` construct, and if found
         will be successful even if there are other ways to join to ``a``.
         This allows the "right side" of a join to be passed thereby
         providing a "natural join".

"""
        constraints = cls._joincond_scan_left_right(
            a, a_subset, b, consider_as_foreign_keys
        )

if len(constraints) > 1:
            cls._joincond_trim_constraints(
                a, b, constraints, consider_as_foreign_keys
            )

if len(constraints) == 0:
            if isinstance(b, FromGrouping):
                hint = (
                    " Perhaps you meant to convert the right side to a "
                    "subquery using alias()?"
                )
            else:
                hint = ""
            raise exc.NoForeignKeysError(
                "Can't find any foreign key relationships "
                "between '%s' and '%s'.%s"
                % (a.description, b.description, hint)
            )

crit = [(x == y) for x, y in list(constraints.values())[0]]
        if len(crit) == 1:
            return crit[0]
        else:
            return and_(*crit)

@classmethod
    def _can_join(cls, left, right, consider_as_foreign_keys=None):
        if isinstance(left, Join):
            left_right = left.right
        else:
            left_right = None

constraints = cls._joincond_scan_left_right(
            a=left,
            b=right,
            a_subset=left_right,
            consider_as_foreign_keys=consider_as_foreign_keys,
        )

return bool(constraints)

@classmethod
    @util.dependencies("sqlalchemy.sql.util")
    def _joincond_scan_left_right(
        cls, sql_util, a, a_subset, b, consider_as_foreign_keys
    ):
        constraints = collections.defaultdict(list)

for left in (a_subset, a):
            if left is None:
                continue
            for fk in sorted(
                b.foreign_keys, key=lambda fk: fk.parent._creation_order
            ):
                if (
                    consider_as_foreign_keys is not None
                    and fk.parent not in consider_as_foreign_keys
                ):
                    continue
                try:
                    col = fk.get_referent(left)
                except exc.NoReferenceError as nrte:
                    table_names = {t.name for t in sql_util.find_tables(left)}
                    if nrte.table_name in table_names:
                        raise
                    else:
                        continue

if col is not None:
                    constraints[fk.constraint].append((col, fk.parent))
            if left is not b:
                for fk in sorted(
                    left.foreign_keys, key=lambda fk: fk.parent._creation_order
                ):
                    if (
                        consider_as_foreign_keys is not None
                        and fk.parent not in consider_as_foreign_keys
                    ):
                        continue
                    try:
                        col = fk.get_referent(b)
                    except exc.NoReferenceError as nrte:
                        table_names = {t.name for t in sql_util.find_tables(b)}
                        if nrte.table_name in table_names:
                            raise
                        else:
                            continue

if col is not None:
                        constraints[fk.constraint].append((col, fk.parent))
            if constraints:
                break
        return constraints

@classmethod
    def _joincond_trim_constraints(
        cls, a, b, constraints, consider_as_foreign_keys
    ):
        # more than one constraint matched.  narrow down the list
        # to include just those FKCs that match exactly to
        # "consider_as_foreign_keys".
        if consider_as_foreign_keys:
            for const in list(constraints):
                if set(f.parent for f in const.elements) != set(
                    consider_as_foreign_keys
                ):
                    del constraints[const]

# if still multiple constraints, but
        # they all refer to the exact same end result, use it.
        if len(constraints) > 1:
            dedupe = set(tuple(crit) for crit in constraints.values())
            if len(dedupe) == 1:
                key = list(constraints)[0]
                constraints = {key: constraints[key]}

if len(constraints) != 1:
            raise exc.AmbiguousForeignKeysError(
                "Can't determine join between '%s' and '%s'; "
                "tables have more than one foreign key "
                "constraint relationship between them. "
                "Please specify the 'onclause' of this "
                "join explicitly." % (a.description, b.description)
            )

def select(self, whereclause=None, **kwargs):
        r"""Create a :class:`_expression.Select` from this
        :class:`_expression.Join`.

The equivalent long-hand form, given a :class:`_expression.Join`
        object
        ``j``, is::

from sqlalchemy import select
            j = select([j.left, j.right], **kw).\
                        where(whereclause).\
                        select_from(j)

:param whereclause: the WHERE criterion that will be sent to
          the :func:`select()` function

:param \**kwargs: all other kwargs are sent to the
          underlying :func:`select()` function.

"""
        collist = [self.left, self.right]

return Select(collist, whereclause, from_obj=[self], **kwargs)

@property
    def bind(self):
        return self.left.bind or self.right.bind

@util.dependencies("sqlalchemy.sql.util")
    def alias(self, sqlutil, name=None, flat=False):
        r"""Return an alias of this :class:`_expression.Join`.

The default behavior here is to first produce a SELECT
        construct from this :class:`_expression.Join`, then to produce an
        :class:`_expression.Alias` from that.  So given a join of the form::

j = table_a.join(table_b, table_a.c.id == table_b.c.a_id)

The JOIN by itself would look like::

table_a JOIN table_b ON table_a.id = table_b.a_id

Whereas the alias of the above, ``j.alias()``, would in a
        SELECT context look like::

(SELECT table_a.id AS table_a_id, table_b.id AS table_b_id,
                table_b.a_id AS table_b_a_id
                FROM table_a
                JOIN table_b ON table_a.id = table_b.a_id) AS anon_1

The equivalent long-hand form, given a :class:`_expression.Join`
        object
        ``j``, is::

from sqlalchemy import select, alias
            j = alias(
                select([j.left, j.right]).\
                    select_from(j).\
                    with_labels(True).\
                    correlate(False),
                name=name
            )

The selectable produced by :meth:`_expression.Join.alias`
        features the same
        columns as that of the two individual selectables presented under
        a single name - the individual columns are "auto-labeled", meaning
        the ``.c.`` collection of the resulting :class:`_expression.Alias`
        represents
        the names of the individual columns using a
        ``<tablename>_<columname>`` scheme::

j.c.table_a_id
            j.c.table_b_a_id

:meth:`_expression.Join.alias` also features an alternate
        option for aliasing joins which produces no enclosing SELECT and
        does not normally apply labels to the column names.  The
        ``flat=True`` option will call :meth:`_expression.FromClause.alias`
        against the left and right sides individually.
        Using this option, no new ``SELECT`` is produced;
        we instead, from a construct as below::

j = table_a.join(table_b, table_a.c.id == table_b.c.a_id)
            j = j.alias(flat=True)

we get a result like this::

table_a AS table_a_1 JOIN table_b AS table_b_1 ON
            table_a_1.id = table_b_1.a_id

The ``flat=True`` argument is also propagated to the contained
        selectables, so that a composite join such as::

j = table_a.join(
                    table_b.join(table_c,
                            table_b.c.id == table_c.c.b_id),
                    table_b.c.a_id == table_a.c.id
                ).alias(flat=True)

Will produce an expression like::

table_a AS table_a_1 JOIN (
                    table_b AS table_b_1 JOIN table_c AS table_c_1
                    ON table_b_1.id = table_c_1.b_id
            ) ON table_a_1.id = table_b_1.a_id

The standalone :func:`_expression.alias` function as well as the
        base :meth:`_expression.FromClause.alias`
        method also support the ``flat=True``
        argument as a no-op, so that the argument can be passed to the
        ``alias()`` method of any selectable.

.. versionadded:: 0.9.0 Added the ``flat=True`` option to create
          "aliases" of joins without enclosing inside of a SELECT
          subquery.

:param name: name given to the alias.

:param flat: if True, produce an alias of the left and right
         sides of this :class:`_expression.Join` and return the join of those
         two selectables.   This produces join expression that does not
         include an enclosing SELECT.

.. versionadded:: 0.9.0

.. seealso::

:ref:`core_tutorial_aliases`

:func:`_expression.alias`

"""
        if flat:
            assert name is None, "Can't send name argument with flat"
            left_a, right_a = (
                self.left.alias(flat=True),
                self.right.alias(flat=True),
            )
            adapter = sqlutil.ClauseAdapter(left_a).chain(
                sqlutil.ClauseAdapter(right_a)
            )

return left_a.join(
                right_a,
                adapter.traverse(self.onclause),
                isouter=self.isouter,
                full=self.full,
            )
        else:
            return self.select(use_labels=True, correlate=False).alias(name)

@property
    def _hide_froms(self):
        return itertools.chain(
            *[_from_objects(x.left, x.right) for x in self._cloned_set]
        )

@property
    def _from_objects(self):
        return (
            [self]
            + self.onclause._from_objects
            + self.left._from_objects
            + self.right._from_objects
        )

class Alias(FromClause):
    """Represents an table or selectable alias (AS).

Represents an alias, as typically applied to any table or
    sub-select within a SQL statement using the ``AS`` keyword (or
    without the keyword on certain databases such as Oracle).

This object is constructed from the :func:`_expression.alias` module
    level function as well as the :meth:`_expression.FromClause.alias`
    method available
    on all :class:`_expression.FromClause` subclasses.

"""

__visit_name__ = "alias"
    named_with_column = True

_is_from_container = True

def __init__(self, *arg, **kw):
        raise NotImplementedError(
            "The %s class is not intended to be constructed "
            "directly.  Please use the %s() standalone "
            "function or the %s() method available from appropriate "
            "selectable objects."
            % (
                self.__class__.__name__,
                self.__class__.__name__.lower(),
                self.__class__.__name__.lower(),
            )
        )

@classmethod
    def _construct(cls, *arg, **kw):
        obj = cls.__new__(cls)
        obj._init(*arg, **kw)
        return obj

@classmethod
    def _factory(cls, selectable, name=None, flat=False):
        """Return an :class:`_expression.Alias` object.

An :class:`_expression.Alias` represents any
        :class:`_expression.FromClause`
        with an alternate name assigned within SQL, typically using the ``AS``
        clause when generated, e.g. ``SELECT * FROM table AS aliasname``.

Similar functionality is available via the
        :meth:`_expression.FromClause.alias`
        method available on all :class:`_expression.FromClause` subclasses.
        In terms of
        a SELECT object as generated from the :func:`_expression.select`
        function, the :meth:`_expression.SelectBase.alias` method returns an
        :class:`_expression.Alias` or similar object which represents a named,
        parenthesized subquery.

When an :class:`_expression.Alias` is created from a
        :class:`_schema.Table` object,
        this has the effect of the table being rendered
        as ``tablename AS aliasname`` in a SELECT statement.

For :func:`_expression.select` objects, the effect is that of
        creating a named subquery, i.e. ``(select ...) AS aliasname``.

The ``name`` parameter is optional, and provides the name
        to use in the rendered SQL.  If blank, an "anonymous" name
        will be deterministically generated at compile time.
        Deterministic means the name is guaranteed to be unique against
        other constructs used in the same statement, and will also be the
        same name for each successive compilation of the same statement
        object.

:param selectable: any :class:`_expression.FromClause` subclass,
            such as a table, select statement, etc.

:param name: string name to be assigned as the alias.
            If ``None``, a name will be deterministically generated
            at compile time.

:param flat: Will be passed through to if the given selectable
         is an instance of :class:`_expression.Join` - see
         :meth:`_expression.Join.alias`
         for details.

.. versionadded:: 0.9.0

"""
        return _interpret_as_from(selectable).alias(name=name, flat=flat)

def _init(self, selectable, name=None):
        baseselectable = selectable
        while isinstance(baseselectable, Alias):
            baseselectable = baseselectable.element
        self.original = baseselectable
        self.supports_execution = baseselectable.supports_execution
        if self.supports_execution:
            self._execution_options = baseselectable._execution_options
        self.element = selectable
        if name is None:
            if self.original.named_with_column:
                name = getattr(self.original, "name", None)
            name = _anonymous_label("%%(%d %s)s" % (id(self), name or "anon"))
        self.name = name

def self_group(self, against=None):
        if (
            isinstance(against, CompoundSelect)
            and isinstance(self.original, Select)
            and self.original._needs_parens_for_grouping()
        ):
            return FromGrouping(self)

return super(Alias, self).self_group(against=against)

@property
    def description(self):
        if util.py3k:
            return self.name
        else:
            return self.name.encode("ascii", "backslashreplace")

def as_scalar(self):
        try:
            return self.element.as_scalar()
        except AttributeError as err:
            util.raise_(
                AttributeError(
                    "Element %s does not support "
                    "'as_scalar()'" % self.element
                ),
                replace_context=err,
            )

def is_derived_from(self, fromclause):
        if fromclause in self._cloned_set:
            return True
        return self.element.is_derived_from(fromclause)

def _populate_column_collection(self):
        for col in self.element.columns._all_columns:
            col._make_proxy(self)

def _refresh_for_new_column(self, column):
        col = self.element._refresh_for_new_column(column)
        if col is not None:
            if not self._cols_populated:
                return None
            else:
                return col._make_proxy(self)
        else:
            return None

def _copy_internals(self, clone=_clone, **kw):
        # don't apply anything to an aliased Table
        # for now.   May want to drive this from
        # the given **kw.
        if isinstance(self.element, TableClause):
            return
        self._reset_exported()
        self.element = clone(self.element, **kw)
        baseselectable = self.element
        while isinstance(baseselectable, Alias):
            baseselectable = baseselectable.element
        self.original = baseselectable

def get_children(self, column_collections=True, **kw):
        if column_collections:
            for c in self.c:
                yield c
        yield self.element

@property
    def _from_objects(self):
        return [self]

@property
    def bind(self):
        return self.element.bind

class Lateral(Alias):
    """Represent a LATERAL subquery.

This object is constructed from the :func:`_expression.lateral` module
    level function as well as the :meth:`_expression.FromClause.lateral`
    method available
    on all :class:`_expression.FromClause` subclasses.

While LATERAL is part of the SQL standard, currently only more recent
    PostgreSQL versions provide support for this keyword.

.. versionadded:: 1.1

.. seealso::

:ref:`lateral_selects` -  overview of usage.

"""

__visit_name__ = "lateral"
    _is_lateral = True

@classmethod
    def _factory(cls, selectable, name=None):
        """Return a :class:`_expression.Lateral` object.

:class:`_expression.Lateral` is an :class:`_expression.Alias`
        subclass that represents
        a subquery with the LATERAL keyword applied to it.

The special behavior of a LATERAL subquery is that it appears in the
        FROM clause of an enclosing SELECT, but may correlate to other
        FROM clauses of that SELECT.   It is a special case of subquery
        only supported by a small number of backends, currently more recent
        PostgreSQL versions.

.. versionadded:: 1.1

.. seealso::

:ref:`lateral_selects` -  overview of usage.

"""
        return _interpret_as_from(selectable).lateral(name=name)

class TableSample(Alias):
    """Represent a TABLESAMPLE clause.

This object is constructed from the :func:`_expression.tablesample` module
    level function as well as the :meth:`_expression.FromClause.tablesample`
    method
    available on all :class:`_expression.FromClause` subclasses.

.. versionadded:: 1.1

.. seealso::

:func:`_expression.tablesample`

"""

__visit_name__ = "tablesample"

@classmethod
    def _factory(cls, selectable, sampling, name=None, seed=None):
        """Return a :class:`_expression.TableSample` object.

:class:`_expression.TableSample` is an :class:`_expression.Alias`
        subclass that represents
        a table with the TABLESAMPLE clause applied to it.
        :func:`_expression.tablesample`
        is also available from the :class:`_expression.FromClause`
        class via the
        :meth:`_expression.FromClause.tablesample` method.

The TABLESAMPLE clause allows selecting a randomly selected approximate
        percentage of rows from a table. It supports multiple sampling methods,
        most commonly BERNOULLI and SYSTEM.

e.g.::

from sqlalchemy import func

selectable = people.tablesample(
                        func.bernoulli(1),
                        name='alias',
                        seed=func.random())
            stmt = select([selectable.c.people_id])

Assuming ``people`` with a column ``people_id``, the above
        statement would render as::

SELECT alias.people_id FROM
            people AS alias TABLESAMPLE bernoulli(:bernoulli_1)
            REPEATABLE (random())

.. versionadded:: 1.1

:param sampling: a ``float`` percentage between 0 and 100 or
            :class:`_functions.Function`.

:param name: optional alias name

:param seed: any real-valued SQL expression.  When specified, the
         REPEATABLE sub-clause is also rendered.

"""
        return _interpret_as_from(selectable).tablesample(
            sampling, name=name, seed=seed
        )

def _init(self, selectable, sampling, name=None, seed=None):
        self.sampling = sampling
        self.seed = seed
        super(TableSample, self)._init(selectable, name=name)

@util.dependencies("sqlalchemy.sql.functions")
    def _get_method(self, functions):
        if isinstance(self.sampling, functions.Function):
            return self.sampling
        else:
            return functions.func.system(self.sampling)

class CTE(Generative, HasPrefixes, HasSuffixes, Alias):
    """Represent a Common Table Expression.

The :class:`_expression.CTE` object is obtained using the
    :meth:`_expression.SelectBase.cte` method from any selectable.
    See that method for complete examples.

"""

__visit_name__ = "cte"

@classmethod
    def _factory(cls, selectable, name=None, recursive=False):
        r"""Return a new :class:`_expression.CTE`,
        or Common Table Expression instance.

Please see :meth:`_expression.HasCTE.cte` for detail on CTE usage.

"""
        return _interpret_as_from(selectable).cte(
            name=name, recursive=recursive
        )

def _init(
        self,
        selectable,
        name=None,
        recursive=False,
        _cte_alias=None,
        _restates=frozenset(),
        _prefixes=None,
        _suffixes=None,
    ):
        self.recursive = recursive
        self._cte_alias = _cte_alias
        self._restates = _restates
        if _prefixes:
            self._prefixes = _prefixes
        if _suffixes:
            self._suffixes = _suffixes
        super(CTE, self)._init(selectable, name=name)

def _copy_internals(self, clone=_clone, **kw):
        super(CTE, self)._copy_internals(clone, **kw)
        if self._cte_alias is not None:
            self._cte_alias = clone(self._cte_alias, **kw)
        self._restates = frozenset(
            [clone(elem, **kw) for elem in self._restates]
        )

@util.dependencies("sqlalchemy.sql.dml")
    def _populate_column_collection(self, dml):
        if isinstance(self.element, dml.UpdateBase):
            for col in self.element._returning:
                col._make_proxy(self)
        else:
            for col in self.element.columns._all_columns:
                col._make_proxy(self)

def alias(self, name=None, flat=False):
        """Return an :class:`_expression.Alias` of this
        :class:`_expression.CTE`.

This method is a CTE-specific specialization of the
        :meth:`_expression.FromClause.alias` method.

.. seealso::

:ref:`core_tutorial_aliases`

:func:`_expression.alias`

"""
        return CTE._construct(
            self.original,
            name=name,
            recursive=self.recursive,
            _cte_alias=self,
            _prefixes=self._prefixes,
            _suffixes=self._suffixes,
        )

def union(self, other):
        return CTE._construct(
            self.original.union(other),
            name=self.name,
            recursive=self.recursive,
            _restates=self._restates.union([self]),
            _prefixes=self._prefixes,
            _suffixes=self._suffixes,
        )

def union_all(self, other):
        return CTE._construct(
            self.original.union_all(other),
            name=self.name,
            recursive=self.recursive,
            _restates=self._restates.union([self]),
            _prefixes=self._prefixes,
            _suffixes=self._suffixes,
        )

class HasCTE(object):
    """Mixin that declares a class to include CTE support.

.. versionadded:: 1.1

"""

def cte(self, name=None, recursive=False):
        r"""Return a new :class:`_expression.CTE`,
        or Common Table Expression instance.

Common table expressions are a SQL standard whereby SELECT
        statements can draw upon secondary statements specified along
        with the primary statement, using a clause called "WITH".
        Special semantics regarding UNION can also be employed to
        allow "recursive" queries, where a SELECT statement can draw
        upon the set of rows that have previously been selected.

CTEs can also be applied to DML constructs UPDATE, INSERT
        and DELETE on some databases, both as a source of CTE rows
        when combined with RETURNING, as well as a consumer of
        CTE rows.

.. versionchanged:: 1.1 Added support for UPDATE/INSERT/DELETE as
           CTE, CTEs added to UPDATE/INSERT/DELETE.

SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
        similarly to :class:`_expression.Alias` objects, as special elements
        to be delivered to the FROM clause of the statement as well
        as to a WITH clause at the top of the statement.

For special prefixes such as PostgreSQL "MATERIALIZED" and
        "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
        method may be
        used to establish these.

.. versionchanged:: 1.3.13 Added support for prefixes.
           In particular - MATERIALIZED and NOT MATERIALIZED.

:param name: name given to the common table expression.  Like
         :meth:`_expression.FromClause.alias`, the name can be left as
         ``None`` in which case an anonymous symbol will be used at query
         compile time.
        :param recursive: if ``True``, will render ``WITH RECURSIVE``.
         A recursive common table expression is intended to be used in
         conjunction with UNION ALL in order to derive rows
         from those already selected.

The following examples include two from PostgreSQL's documentation at
        http://www.postgresql.org/docs/current/static/queries-with.html,
        as well as additional examples.

Example 1, non recursive::

from sqlalchemy import (Table, Column, String, Integer,
                                    MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
                Column('region', String),
                Column('amount', Integer),
                Column('product', String),
                Column('quantity', Integer)
            )

regional_sales = select([
                                orders.c.region,
                                func.sum(orders.c.amount).label('total_sales')
                            ]).group_by(orders.c.region).cte("regional_sales")

top_regions = select([regional_sales.c.region]).\
                    where(
                        regional_sales.c.total_sales >
                        select([
                            func.sum(regional_sales.c.total_sales)/10
                        ])
                    ).cte("top_regions")

statement = select([
                        orders.c.region,
                        orders.c.product,
                        func.sum(orders.c.quantity).label("product_units"),
                        func.sum(orders.c.amount).label("product_sales")
                ]).where(orders.c.region.in_(
                    select([top_regions.c.region])
                )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

Example 2, WITH RECURSIVE::

from sqlalchemy import (Table, Column, String, Integer,
                                    MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
                Column('part', String),
                Column('sub_part', String),
                Column('quantity', Integer),
            )

included_parts = select([
                                parts.c.sub_part,
                                parts.c.part,
                                parts.c.quantity]).\
                                where(parts.c.part=='our part').\
                                cte(recursive=True)

incl_alias = included_parts.alias()
            parts_alias = parts.alias()
            included_parts = included_parts.union_all(
                select([
                    parts_alias.c.sub_part,
                    parts_alias.c.part,
                    parts_alias.c.quantity
                ]).
                    where(parts_alias.c.part==incl_alias.c.sub_part)
            )

statement = select([
                        included_parts.c.sub_part,
                        func.sum(included_parts.c.quantity).
                          label('total_quantity')
                    ]).\
                    group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

Example 3, an upsert using UPDATE and INSERT with CTEs::

from datetime import date
            from sqlalchemy import (MetaData, Table, Column, Integer,
                                    Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
                Column('product_id', Integer, primary_key=True),
                Column('date', Date, primary_key=True),
                Column('count', Integer),
            )

# add 5 visitors for the product_id == 1
            product_id = 1
            day = date.today()
            count = 5

update_cte = (
                visitors.update()
                .where(and_(visitors.c.product_id == product_id,
                            visitors.c.date == day))
                .values(count=visitors.c.count + count)
                .returning(literal(1))
                .cte('update_cte')
            )

upsert = visitors.insert().from_select(
                [visitors.c.product_id, visitors.c.date, visitors.c.count],
                select([literal(product_id), literal(day), literal(count)])
                    .where(~exists(update_cte.select()))
            )

connection.execute(upsert)

.. seealso::

:meth:`.orm.query.Query.cte` - ORM version of
            :meth:`_expression.HasCTE.cte`.

"""
        return CTE._construct(self, name=name, recursive=recursive)

class FromGrouping(FromClause):
    """Represent a grouping of a FROM clause"""

__visit_name__ = "grouping"

def __init__(self, element):
        self.element = element

def _init_collections(self):
        pass

@property
    def columns(self):
        return self.element.columns

@property
    def primary_key(self):
        return self.element.primary_key

@property
    def foreign_keys(self):
        return self.element.foreign_keys

def is_derived_from(self, element):
        return self.element.is_derived_from(element)

def alias(self, **kw):
        return FromGrouping(self.element.alias(**kw))

@property
    def _hide_froms(self):
        return self.element._hide_froms

def get_children(self, **kwargs):
        return (self.element,)

def _copy_internals(self, clone=_clone, **kw):
        self.element = clone(self.element, **kw)

@property
    def _from_objects(self):
        return self.element._from_objects

def __getattr__(self, attr):
        return getattr(self.element, attr)

def __getstate__(self):
        return {"element": self.element}

def __setstate__(self, state):
        self.element = state["element"]

class TableClause(Immutable, FromClause):
    """Represents a minimal "table" construct.

This is a lightweight table object that has only a name, a
    collection of columns, which are typically produced
    by the :func:`_expression.column` function, and a schema::

from sqlalchemy import table, column

user = table("user",
                column("id"),
                column("name"),
                column("description"),
        )

The :class:`_expression.TableClause` construct serves as the base for
    the more commonly used :class:`_schema.Table` object, providing
    the usual set of :class:`_expression.FromClause` services including
    the ``.c.`` collection and statement generation methods.

It does **not** provide all the additional schema-level services
    of :class:`_schema.Table`, including constraints, references to other
    tables, or support for :class:`_schema.MetaData`-level services.
    It's useful
    on its own as an ad-hoc construct used to generate quick SQL
    statements when a more fully fledged :class:`_schema.Table`
    is not on hand.

"""

__visit_name__ = "table"

named_with_column = True

implicit_returning = False
    """:class:`_expression.TableClause`
    doesn't support having a primary key or column
    -level defaults, so implicit returning doesn't apply."""

_autoincrement_column = None
    """No PK or default support so no autoincrement column."""

def __init__(self, name, *columns, **kw):
        """Produce a new :class:`_expression.TableClause`.

The object returned is an instance of
        :class:`_expression.TableClause`, which
        represents the "syntactical" portion of the schema-level
        :class:`_schema.Table` object.
        It may be used to construct lightweight table constructs.

.. versionchanged:: 1.0.0 :func:`_expression.table` can now
           be imported from the plain ``sqlalchemy`` namespace like any
           other SQL element.

:param name: Name of the table.

:param columns: A collection of :func:`_expression.column` constructs.

:param schema: The schema name for this table.

.. versionadded:: 1.3.18 :func:`_expression.table` can now
               accept a ``schema`` argument.
        """

super(TableClause, self).__init__()
        self.name = self.fullname = name
        self._columns = ColumnCollection()
        self.primary_key = ColumnSet()
        self.foreign_keys = set()
        for c in columns:
            self.append_column(c)

schema = kw.pop("schema", None)
        if schema is not None:
            self.schema = schema
        if kw:
            raise exc.ArgumentError("Unsupported argument(s): %s" % list(kw))

def _init_collections(self):
        pass

@util.memoized_property
    def description(self):
        if util.py3k:
            return self.name
        else:
            return self.name.encode("ascii", "backslashreplace")

def append_column(self, c):
        existing = c.table
        if existing is not None and existing is not self:
            raise exc.ArgumentError(
                "column object '%s' already assigned to table %r"
                % (c.key, getattr(existing, "description", existing))
            )

self._columns[c.key] = c
        c.table = self

def get_children(self, column_collections=True, **kwargs):
        if column_collections:
            return [c for c in self.c]
        else:
            return []

@util.dependencies("sqlalchemy.sql.dml")
    def insert(self, dml, values=None, inline=False, **kwargs):
        """Generate an :func:`_expression.insert` construct against this
        :class:`_expression.TableClause`.

E.g.::

table.insert().values(name='foo')

See :func:`_expression.insert` for argument and usage information.

"""

return dml.Insert(self, values=values, inline=inline, **kwargs)

@util.dependencies("sqlalchemy.sql.dml")
    def update(
        self, dml, whereclause=None, values=None, inline=False, **kwargs
    ):
        """Generate an :func:`_expression.update` construct against this
        :class:`_expression.TableClause`.

E.g.::

table.update().where(table.c.id==7).values(name='foo')

See :func:`_expression.update` for argument and usage information.

"""

return dml.Update(
            self,
            whereclause=whereclause,
            values=values,
            inline=inline,
            **kwargs
        )

@util.dependencies("sqlalchemy.sql.dml")
    def delete(self, dml, whereclause=None, **kwargs):
        """Generate a :func:`_expression.delete` construct against this
        :class:`_expression.TableClause`.

E.g.::

table.delete().where(table.c.id==7)

See :func:`_expression.delete` for argument and usage information.

"""

return dml.Delete(self, whereclause, **kwargs)

@property
    def _from_objects(self):
        return [self]

class ForUpdateArg(ClauseElement):
    @classmethod
    def parse_legacy_select(self, arg):
        """Parse the for_update argument of :func:`_expression.select`.

:param mode: Defines the lockmode to use.

``None`` - translates to no lockmode

``'update'`` - translates to ``FOR UPDATE``
            (standard SQL, supported by most dialects)

``'nowait'`` - translates to ``FOR UPDATE NOWAIT``
            (supported by Oracle, PostgreSQL 8.1 upwards)

``'read'`` - translates to ``LOCK IN SHARE MODE`` (for MySQL),
            and ``FOR SHARE`` (for PostgreSQL)

``'read_nowait'`` - translates to ``FOR SHARE NOWAIT``
            (supported by PostgreSQL). ``FOR SHARE`` and
            ``FOR SHARE NOWAIT`` (PostgreSQL).

"""
        if arg in (None, False):
            return None

nowait = read = False
        if arg == "nowait":
            nowait = True
        elif arg == "read":
            read = True
        elif arg == "read_nowait":
            read = nowait = True
        elif arg is not True:
            raise exc.ArgumentError("Unknown for_update argument: %r" % arg)

return ForUpdateArg(read=read, nowait=nowait)

@property
    def legacy_for_update_value(self):
        if self.read and not self.nowait:
            return "read"
        elif self.read and self.nowait:
            return "read_nowait"
        elif self.nowait:
            return "nowait"
        else:
            return True

def __eq__(self, other):
        return (
            isinstance(other, ForUpdateArg)
            and other.nowait == self.nowait
            and other.read == self.read
            and other.skip_locked == self.skip_locked
            and other.key_share == self.key_share
            and other.of is self.of
        )

def __hash__(self):
        return id(self)

def _copy_internals(self, clone=_clone, **kw):
        if self.of is not None:
            self.of = [clone(col, **kw) for col in self.of]

def __init__(
        self,
        nowait=False,
        read=False,
        of=None,
        skip_locked=False,
        key_share=False,
    ):
        """Represents arguments specified to
        :meth:`_expression.Select.for_update`.

.. versionadded:: 0.9.0

"""

self.nowait = nowait
        self.read = read
        self.skip_locked = skip_locked
        self.key_share = key_share
        if of is not None:
            self.of = [
                _interpret_as_column_or_from(elem) for elem in util.to_list(of)
            ]
        else:
            self.of = None

class SelectBase(HasCTE, Executable, FromClause):
    """Base class for SELECT statements.

This includes :class:`_expression.Select`,
    :class:`_selectable.CompoundSelect` and
    :class:`.TextAsFrom`.

"""

def as_scalar(self):
        """Return a 'scalar' representation of this selectable, which can be
        used as a column expression.

Typically, a select statement which has only one column in its columns
        clause is eligible to be used as a scalar expression.

The returned object is an instance of
        :class:`ScalarSelect`.

"""
        return ScalarSelect(self)

def label(self, name):
        """Return a 'scalar' representation of this selectable, embedded as a
        subquery with a label.

.. seealso::

:meth:`_expression.SelectBase.as_scalar`.

"""
        return self.as_scalar().label(name)

@_generative
    @util.deprecated(
        "0.6",
        message="The :meth:`.SelectBase.autocommit` method is deprecated, "
        "and will be removed in a future release.   Please use the "
        "the :paramref:`.Connection.execution_options.autocommit` "
        "parameter in conjunction with the "
        ":meth:`.Executable.execution_options` method.",
    )
    def autocommit(self):
        """Return a new selectable with the 'autocommit' flag set to
        True.

"""

self._execution_options = self._execution_options.union(
            {"autocommit": True}
        )

def _generate(self):
        """Override the default _generate() method to also clear out
        exported collections."""

s = self.__class__.__new__(self.__class__)
        s.__dict__ = self.__dict__.copy()
        s._reset_exported()
        return s

@property
    def _from_objects(self):
        return [self]

class GenerativeSelect(SelectBase):
    """Base class for SELECT statements where additional elements can be
    added.

This serves as the base for :class:`_expression.Select` and
    :class:`_selectable.CompoundSelect`
    where elements such as ORDER BY, GROUP BY can be added and column
    rendering can be controlled.  Compare to :class:`.TextAsFrom`, which,
    while it subclasses :class:`_expression.SelectBase`
    and is also a SELECT construct,
    represents a fixed textual string which cannot be altered at this level,
    only wrapped as a subquery.

.. versionadded:: 0.9.0 :class:`_expression.GenerativeSelect` was added to
       provide functionality specific to :class:`_expression.Select` and
       :class:`_selectable.CompoundSelect` while allowing
       :class:`_expression.SelectBase` to be
       used for other SELECT-like objects, e.g. :class:`.TextAsFrom`.

"""

_order_by_clause = ClauseList()
    _group_by_clause = ClauseList()
    _limit_clause = None
    _offset_clause = None
    _for_update_arg = None

def __init__(
        self,
        use_labels=False,
        for_update=False,
        limit=None,
        offset=None,
        order_by=None,
        group_by=None,
        bind=None,
        autocommit=None,
    ):
        self.use_labels = use_labels

if for_update is not False:
            self._for_update_arg = ForUpdateArg.parse_legacy_select(for_update)

if autocommit is not None:
            util.warn_deprecated(
                "The select.autocommit parameter is deprecated and will be "
                "removed in a future release.  Please refer to the "
                "Select.execution_options.autocommit` parameter."
            )
            self._execution_options = self._execution_options.union(
                {"autocommit": autocommit}
            )
        if limit is not None:
            self._limit_clause = _offset_or_limit_clause(limit)
        if offset is not None:
            self._offset_clause = _offset_or_limit_clause(offset)
        self._bind = bind

if order_by is not None:
            self._order_by_clause = ClauseList(
                *util.to_list(order_by),
                _literal_as_text=_literal_and_labels_as_label_reference
            )
        if group_by is not None:
            self._group_by_clause = ClauseList(
                *util.to_list(group_by),
                _literal_as_text=_literal_as_label_reference
            )

@property
    def for_update(self):
        """Provide legacy dialect support for the ``for_update`` attribute."""
        if self._for_update_arg is not None:
            return self._for_update_arg.legacy_for_update_value
        else:
            return None

@for_update.setter
    def for_update(self, value):
        self._for_update_arg = ForUpdateArg.parse_legacy_select(value)

@_generative
    def with_for_update(
        self,
        nowait=False,
        read=False,
        of=None,
        skip_locked=False,
        key_share=False,
    ):
        """Specify a ``FOR UPDATE`` clause for this
        :class:`_expression.GenerativeSelect`.

E.g.::

stmt = select([table]).with_for_update(nowait=True)

On a database like PostgreSQL or Oracle, the above would render a
        statement like::

SELECT table.a, table.b FROM table FOR UPDATE NOWAIT

on other backends, the ``nowait`` option is ignored and instead
        would produce::

SELECT table.a, table.b FROM table FOR UPDATE

When called with no arguments, the statement will render with
        the suffix ``FOR UPDATE``.   Additional arguments can then be
        provided which allow for common database-specific
        variants.

:param nowait: boolean; will render ``FOR UPDATE NOWAIT`` on Oracle
         and PostgreSQL dialects.

:param read: boolean; will render ``LOCK IN SHARE MODE`` on MySQL,
         ``FOR SHARE`` on PostgreSQL.  On PostgreSQL, when combined with
         ``nowait``, will render ``FOR SHARE NOWAIT``.

:param of: SQL expression or list of SQL expression elements
         (typically :class:`_schema.Column`
         objects or a compatible expression) which
         will render into a ``FOR UPDATE OF`` clause; supported by PostgreSQL
         and Oracle.  May render as a table or as a column depending on
         backend.

:param skip_locked: boolean, will render ``FOR UPDATE SKIP LOCKED``
         on Oracle and PostgreSQL dialects or ``FOR SHARE SKIP LOCKED`` if
         ``read=True`` is also specified.

.. versionadded:: 1.1.0

:param key_share: boolean, will render ``FOR NO KEY UPDATE``,
         or if combined with ``read=True`` will render ``FOR KEY SHARE``,
         on the PostgreSQL dialect.

.. versionadded:: 1.1.0

"""
        self._for_update_arg = ForUpdateArg(
            nowait=nowait,
            read=read,
            of=of,
            skip_locked=skip_locked,
            key_share=key_share,
        )

@_generative
    def apply_labels(self):
        """Return a new selectable with the 'use_labels' flag set to True.

This will result in column expressions being generated using labels
        against their table name, such as "SELECT somecolumn AS
        tablename_somecolumn". This allows selectables which contain multiple
        FROM clauses to produce a unique set of column names regardless of
        name conflicts among the individual FROM clauses.

"""
        self.use_labels = True

@property
    def _limit(self):
        """Get an integer value for the limit.  This should only be used
        by code that cannot support a limit as a BindParameter or
        other custom clause as it will throw an exception if the limit
        isn't currently set to an integer.

"""
        return _offset_or_limit_clause_asint(self._limit_clause, "limit")

@property
    def _simple_int_limit(self):
        """True if the LIMIT clause is a simple integer, False
        if it is not present or is a SQL expression.
        """
        return isinstance(self._limit_clause, _OffsetLimitParam)

@property
    def _simple_int_offset(self):
        """True if the OFFSET clause is a simple integer, False
        if it is not present or is a SQL expression.
        """
        return isinstance(self._offset_clause, _OffsetLimitParam)

@property
    def _offset(self):
        """Get an integer value for the offset.  This should only be used
        by code that cannot support an offset as a BindParameter or
        other custom clause as it will throw an exception if the
        offset isn't currently set to an integer.

"""
        return _offset_or_limit_clause_asint(self._offset_clause, "offset")

@_generative
    def limit(self, limit):
        """Return a new selectable with the given LIMIT criterion
        applied.

This is a numerical value which usually renders as a ``LIMIT``
        expression in the resulting select.  Backends that don't
        support ``LIMIT`` will attempt to provide similar
        functionality.

.. versionchanged:: 1.0.0 - :meth:`_expression.Select.limit` can now
           accept arbitrary SQL expressions as well as integer values.

:param limit: an integer LIMIT parameter, or a SQL expression
         that provides an integer result.

"""

self._limit_clause = _offset_or_limit_clause(limit)

@_generative
    def offset(self, offset):
        """Return a new selectable with the given OFFSET criterion
        applied.

This is a numeric value which usually renders as an ``OFFSET``
        expression in the resulting select.  Backends that don't
        support ``OFFSET`` will attempt to provide similar
        functionality.

.. versionchanged:: 1.0.0 - :meth:`_expression.Select.offset` can now
           accept arbitrary SQL expressions as well as integer values.

:param offset: an integer OFFSET parameter, or a SQL expression
         that provides an integer result.

"""

self._offset_clause = _offset_or_limit_clause(offset)

@_generative
    def order_by(self, *clauses):
        r"""Return a new selectable with the given list of ORDER BY
        criterion applied.

e.g.::

stmt = select([table]).order_by(table.c.id, table.c.name)

:param \*clauses: a series of :class:`_expression.ColumnElement`
         constructs
         which will be used to generate an ORDER BY clause.

.. seealso::

:ref:`core_tutorial_ordering`

"""

self.append_order_by(*clauses)

@_generative
    def group_by(self, *clauses):
        r"""Return a new selectable with the given list of GROUP BY
        criterion applied.

e.g.::

stmt = select([table.c.name, func.max(table.c.stat)]).\
            group_by(table.c.name)

:param \*clauses: a series of :class:`_expression.ColumnElement`
         constructs
         which will be used to generate an GROUP BY clause.

.. seealso::

:ref:`core_tutorial_ordering`

"""

self.append_group_by(*clauses)

def append_order_by(self, *clauses):
        """Append the given ORDER BY criterion applied to this selectable.

The criterion will be appended to any pre-existing ORDER BY criterion.

This is an **in-place** mutation method; the
        :meth:`_expression.GenerativeSelect.order_by` method is preferred,
        as it
        provides standard :term:`method chaining`.

.. seealso::

:meth:`_expression.GenerativeSelect.order_by`

"""
        if len(clauses) == 1 and clauses[0] is None:
            self._order_by_clause = ClauseList()
        else:
            if getattr(self, "_order_by_clause", None) is not None:
                clauses = list(self._order_by_clause) + list(clauses)
            self._order_by_clause = ClauseList(
                *clauses,
                _literal_as_text=_literal_and_labels_as_label_reference
            )

def append_group_by(self, *clauses):
        """Append the given GROUP BY criterion applied to this selectable.

The criterion will be appended to any pre-existing GROUP BY criterion.

This is an **in-place** mutation method; the
        :meth:`_expression.GenerativeSelect.group_by` method is preferred,
        as it provides standard :term:`method chaining`.

.. seealso::

:meth:`_expression.GenerativeSelect.group_by`

"""
        if len(clauses) == 1 and clauses[0] is None:
            self._group_by_clause = ClauseList()
        else:
            if getattr(self, "_group_by_clause", None) is not None:
                clauses = list(self._group_by_clause) + list(clauses)
            self._group_by_clause = ClauseList(
                *clauses, _literal_as_text=_literal_as_label_reference
            )

@property
    def _label_resolve_dict(self):
        raise NotImplementedError()

def _copy_internals(self, clone=_clone, **kw):
        if self._limit_clause is not None:
            self._limit_clause = clone(self._limit_clause, **kw)
        if self._offset_clause is not None:
            self._offset_clause = clone(self._offset_clause, **kw)

class CompoundSelect(GenerativeSelect):
    """Forms the basis of ``UNION``, ``UNION ALL``, and other
    SELECT-based set operations.

.. seealso::

:func:`_expression.union`

:func:`_expression.union_all`

:func:`_expression.intersect`

:func:`_expression.intersect_all`

:func:`_expression.except`

:func:`_expression.except_all`

"""

__visit_name__ = "compound_select"

UNION = util.symbol("UNION")
    UNION_ALL = util.symbol("UNION ALL")
    EXCEPT = util.symbol("EXCEPT")
    EXCEPT_ALL = util.symbol("EXCEPT ALL")
    INTERSECT = util.symbol("INTERSECT")
    INTERSECT_ALL = util.symbol("INTERSECT ALL")

_is_from_container = True

def __init__(self, keyword, *selects, **kwargs):
        self._auto_correlate = kwargs.pop("correlate", False)
        self.keyword = keyword
        self.selects = []

numcols = None

# some DBs do not like ORDER BY in the inner queries of a UNION, etc.
        for n, s in enumerate(selects):
            s = _clause_element_as_expr(s)

if not numcols:
                numcols = len(s.c._all_columns)
            elif len(s.c._all_columns) != numcols:
                raise exc.ArgumentError(
                    "All selectables passed to "
                    "CompoundSelect must have identical numbers of "
                    "columns; select #%d has %d columns, select "
                    "#%d has %d"
                    % (
                        1,
                        len(self.selects[0].c._all_columns),
                        n + 1,
                        len(s.c._all_columns),
                    )
                )

self.selects.append(s.self_group(against=self))

GenerativeSelect.__init__(self, **kwargs)

@property
    def _label_resolve_dict(self):
        d = dict((c.key, c) for c in self.c)
        return d, d, d

@classmethod
    def _create_union(cls, *selects, **kwargs):
        r"""Return a ``UNION`` of multiple selectables.

The returned object is an instance of
        :class:`_selectable.CompoundSelect`.

A similar :func:`union()` method is available on all
        :class:`_expression.FromClause` subclasses.

:param \*selects:
          a list of :class:`_expression.Select` instances.