Gecko [ biogenelab.eu ]

Name	Size	Permission
__init__.py	1.68 KB	-rw-r--r--
__init__.pyc	2.56 KB	-rw-r--r--
annotation.py	5.97 KB	-rw-r--r--
annotation.pyc	6.39 KB	-rw-r--r--
base.py	20.97 KB	-rw-r--r--
base.pyc	26.95 KB	-rw-r--r--
compiler.py	106.86 KB	-rw-r--r--
compiler.pyc	94.95 KB	-rw-r--r--
ddl.py	28.02 KB	-rw-r--r--
ddl.pyc	31.76 KB	-rw-r--r--
default_comparator.py	12.82 KB	-rw-r--r--
default_comparator.pyc	10.57 KB	-rw-r--r--
dml.py	29.35 KB	-rw-r--r--
dml.pyc	29.88 KB	-rw-r--r--
elements.py	119.21 KB	-rw-r--r--
elements.pyc	135.15 KB	-rw-r--r--
expression.py	5.54 KB	-rw-r--r--
expression.pyc	5.74 KB	-rw-r--r--
functions.py	17.46 KB	-rw-r--r--
functions.pyc	20.95 KB	-rw-r--r--
naming.py	4.48 KB	-rw-r--r--
naming.pyc	5.3 KB	-rw-r--r--
operators.py	21.98 KB	-rw-r--r--
operators.pyc	31.5 KB	-rw-r--r--
schema.py	131.69 KB	-rw-r--r--
schema.pyc	130.05 KB	-rw-r--r--
selectable.py	108.96 KB	-rw-r--r--
selectable.pyc	114.6 KB	-rw-r--r--
sqltypes.py	53.35 KB	-rw-r--r--
sqltypes.pyc	61.85 KB	-rw-r--r--
type_api.py	36.81 KB	-rw-r--r--
type_api.pyc	38.79 KB	-rw-r--r--
util.py	19.04 KB	-rw-r--r--
util.pyc	19.91 KB	-rw-r--r--
visitors.py	9.71 KB	-rw-r--r--
visitors.pyc	11.73 KB	-rw-r--r--

Code Editor : selectable.py

# sql/selectable.py
# Copyright (C) 2005-2014 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:`.FromClause` class of SQL expression elements, representing
SQL tables and derived rowsets.

"""

from .elements import ClauseElement, TextClause, ClauseList, \
    and_, Grouping, UnaryExpression, literal_column
from .elements import _clone, \
    _literal_as_text, _interpret_as_column_or_from, _expand_cloned,\
    _select_iterables, _anonymous_label, _clause_element_as_expr,\
    _cloned_intersection, _cloned_difference, True_, _only_column_elements,\
    TRUE
from .base import Immutable, Executable, _generative, \
    ColumnCollection, ColumnSet, _from_objects, Generative
from . import type_api
from .. import inspection
from .. import util
from .. import exc
from operator import attrgetter
from . import operators
import operator
import collections
from .annotation import Annotated
import itertools

def _interpret_as_from(element):
    insp = inspection.inspect(element, raiseerr=False)
    if insp is None:
        if isinstance(element, util.string_types):
            return TextClause(util.text_type(element))
    elif hasattr(insp, "selectable"):
        return insp.selectable
    raise exc.ArgumentError("FROM expression expected")

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

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

name
      alias name

\*args, \**kwargs

all other arguments are delivered to the
      :func:`select` function.

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

def alias(selectable, name=None, flat=False):
    """Return an :class:`.Alias` object.

An :class:`.Alias` represents any :class:`.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:`~.FromClause.alias` method
    available on all :class:`.FromClause` subclasses.

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

For :func:`.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:`.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:`.Join` - see :meth:`.Join.alias`
     for details.

.. versionadded:: 0.9.0

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

class Selectable(ClauseElement):

"""mark a class as being selectable"""
    __visit_name__ = 'selectable'

is_selectable = True

@property
    def selectable(self):
        return self

class FromClause(Selectable):

"""Represent an element that can be used within the ``FROM``
    clause of a ``SELECT`` statement.

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

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

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

_is_join = False
    _is_select = False
    _is_from_container = False

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

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

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

"""

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

@util.dependencies("sqlalchemy.sql.functions")
    def count(self, functions, whereclause=None, **params):
        """return a SELECT COUNT generated against this
        :class:`.FromClause`."""

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:`.FromClause`.

.. seealso::

:func:`~.sql.expression.select` - general purpose
            method which allows for arbitrary column lists.

"""

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

def join(self, right, onclause=None, isouter=False):
        """Return a :class:`.Join` from this :class:`.FromClause`
        to another :class:`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:`.FromClause` object such as a :class:`.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:`.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.

.. seealso::

:func:`.join` - standalone function

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

"""

return Join(self, right, onclause, isouter)

def outerjoin(self, right, onclause=None):
        """Return a :class:`.Join` from this :class:`.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)

.. seealso::

:meth:`.FromClause.join`

:class:`.Join`

"""

return Join(self, right, onclause, True)

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

This is shorthand for calling::

from sqlalchemy import alias
            a = alias(self, name=name)

See :func:`~.expression.alias` for details.

"""

return Alias(self, name)

def is_derived_from(self, fromclause):
        """Return True if this 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 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:`.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:`.ColumnElement`, return the exported
        :class:`.ColumnElement` object from this :class:`.Selectable`
        which corresponds to that original
        :class:`~sqlalchemy.schema.Column` via a common ancestor
        column.

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

:param require_embedded: only return corresponding columns for
         the given :class:`.ColumnElement`, if the given
         :class:`.ColumnElement` is actually present within a sub-element
         of this :class:`.FromClause`.  Normally the column will match if
         it merely shares a common ancestor with one of the exported
         columns of this :class:`.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.proxy_set if sc.shares_lineage(column)])
                    c_distance = util.reduce(
                        operator.add,
                        [sc._annotations.get('weight', 1) for sc in
                         c.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 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:`.ColumnElement` objects
        maintained by this :class:`.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 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 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:`.FromClause`
    elements.

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

.. seealso::

:func:`.join`

:meth:`.FromClause.join`

"""
    __visit_name__ = 'join'

_is_join = True

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

The usual entrypoint here is the :func:`~.expression.join`
        function or the :meth:`.FromClause.join` method of any
        :class:`.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

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

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

Similar functionality is also available via the
        :meth:`~.FromClause.outerjoin()` method on any
        :class:`.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:`.FromClause.join` or
        :meth:`.FromClause.outerjoin` methods on the resulting
        :class:`.Join` object.

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

@classmethod
    def _create_join(cls, left, right, onclause=None, isouter=False):
        """Produce a :class:`.Join` object, given two :class:`.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:`.FromClause` object (e.g. such as a :class:`.Table`) using
        the :meth:`.FromClause.join` method.

:param left: The left side of the join.

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

.. seealso::

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

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

"""

return cls(left, right, onclause, isouter)

@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.add(col)
                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
    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:  Deprecated - this
        flag is no longer used.  Only resolution errors regarding
        the two given tables are propagated.

: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 = 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:
                    if nrte.table_name == left.name:
                        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:
                        if nrte.table_name == b.name:
                            raise
                        else:
                            # this is totally covered.  can't get
                            # coverage to mark it.
                            continue

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

if len(constraints) > 1:
            # 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))

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)

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

The equivalent long-hand form, given a :class:`.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):
        """return an alias of this :class:`.Join`.

The default behavior here is to first produce a SELECT
        construct from this :class:`.Join`, then to produce a
        :class:`.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:`.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:`.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:`.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:`.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:`.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:`.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:`.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::

: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)
        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:`.FromClause.alias` method available
    on all :class:`.FromClause` subclasses.

"""

__visit_name__ = 'alias'
    named_with_column = True

_is_from_container = True

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

@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:
            raise AttributeError("Element %s does not support "
                                 "'as_scalar()'" % self.element)

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 CTE(Alias):

"""Represent a Common Table Expression.

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

.. versionadded:: 0.7.6

"""
    __visit_name__ = 'cte'

def __init__(self, selectable,
                 name=None,
                 recursive=False,
                 _cte_alias=None,
                 _restates=frozenset()):
        self.recursive = recursive
        self._cte_alias = _cte_alias
        self._restates = _restates
        super(CTE, self).__init__(selectable, name=name)

def alias(self, name=None, flat=False):
        return CTE(
            self.original,
            name=name,
            recursive=self.recursive,
            _cte_alias=self,
        )

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

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

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 and a
    collection of columns, which are typically produced
    by the :func:`.expression.column` function::

from sqlalchemy.sql import table, column

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

The :class:`.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:`.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:`.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):
        """Produce a new :class:`.TableClause`.

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

Note that the :func:`.expression.table` function is not part of
        the ``sqlalchemy`` namespace.  It must be imported from the
        ``sql`` package::

from sqlalchemy.sql import table, column

:param name: Name of the table.

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

"""

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)

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):
        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.functions")
    def count(self, functions, whereclause=None, **params):
        """return a SELECT COUNT generated against this
        :class:`.TableClause`."""

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

E.g.::

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

See :func:`.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:`.update` construct against this
        :class:`.TableClause`.

E.g.::

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

See :func:`.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:`.delete` construct against this
        :class:`.TableClause`.

E.g.::

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

See :func:`.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 arugment of :func:`.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 _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):
        """Represents arguments specified to :meth:`.Select.for_update`.

.. versionadded:: 0.9.0
        """

self.nowait = nowait
        self.read = read
        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(Executable, FromClause):

"""Base class for SELECT statements.

This includes :class:`.Select`, :class:`.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:`~.SelectBase.as_scalar`.

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

def cte(self, name=None, recursive=False):
        """Return a new :class:`.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.

SQLAlchemy detects :class:`.CTE` objects, which are treated
        similarly to :class:`.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.

.. versionadded:: 0.7.6

:param name: name given to the common table expression.  Like
         :meth:`._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 illustrate two examples from
        Postgresql's documentation at
        http://www.postgresql.org/docs/8.4/static/queries-with.html.

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()

.. seealso::

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

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

@_generative
    @util.deprecated('0.6',
                     message="``autocommit()`` is deprecated. Use "
                     ":meth:`.Executable.execution_options` with the "
                     "'autocommit' flag.")
    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:`.Select` and :class:`.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:`.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:`.GenerativeSelect` was added to
       provide functionality specific to :class:`.Select` and
       :class:`.CompoundSelect` while allowing :class:`.SelectBase` to be
       used for other SELECT-like objects, e.g. :class:`.TextAsFrom`.

"""
    _order_by_clause = ClauseList()
    _group_by_clause = ClauseList()
    _limit = None
    _offset = 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('autocommit on select() is '
                                 'deprecated.  Use .execution_options(a'
                                 'utocommit=True)')
            self._execution_options = \
                self._execution_options.union(
                    {'autocommit': autocommit})
        if limit is not None:
            self._limit = util.asint(limit)
        if offset is not None:
            self._offset = util.asint(offset)
        self._bind = bind

if order_by is not None:
            self._order_by_clause = ClauseList(
                *util.to_list(order_by), allow_coercion_to_text=False)
        if group_by is not None:
            self._group_by_clause = ClauseList(
                *util.to_list(group_by), allow_coercion_to_text=False)

@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):
        """Specify a ``FOR UPDATE`` clause for this :class:`.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:`.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.

.. versionadded:: 0.9.0

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

@_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

@_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.

:param limit: an integer LIMIT parameter.

"""

self._limit = util.asint(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.

:param offset: an integer OFFSET parameter.

"""

self._offset = util.asint(offset)

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

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

"""

self.append_order_by(*clauses)

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

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

"""

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:`~.GenerativeSelect.order_by` method is preferred, as it
        provides standard :term:`method chaining`.

"""
        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, allow_coercion_to_text=False)

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:`~.GenerativeSelect.group_by` method is preferred, as it
        provides standard :term:`method chaining`.

"""
        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, allow_coercion_to_text=False)

class CompoundSelect(GenerativeSelect):

"""Forms the basis of ``UNION``, ``UNION ALL``, and other
        SELECT-based set operations.

.. seealso::

:func:`.union`

:func:`.union_all`

:func:`.intersect`

:func:`.intersect_all`

:func:`.except`

:func:`.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(self))

GenerativeSelect.__init__(self, **kwargs)

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