morro

sqlalchemy/sql/__init__.py

@@ -0,0 +1,58 @@
+from sqlalchemy.sql.expression import (
+    Alias,
+    ClauseElement,
+    ColumnCollection,
+    ColumnElement,
+    CompoundSelect,
+    Delete,
+    FromClause,
+    Insert,
+    Join,
+    Select,
+    Selectable,
+    TableClause,
+    Update,
+    alias,
+    and_,
+    asc,
+    between,
+    bindparam,
+    case,
+    cast,
+    collate,
+    column,
+    delete,
+    desc,
+    distinct,
+    except_,
+    except_all,
+    exists,
+    extract,
+    func,
+    insert,
+    intersect,
+    intersect_all,
+    join,
+    label,
+    literal,
+    literal_column,
+    modifier,
+    not_,
+    null,
+    or_,
+    outerjoin,
+    outparam,
+    select,
+    subquery,
+    table,
+    text,
+    tuple_,
+    union,
+    union_all,
+    update,
+    )
+
+from sqlalchemy.sql.visitors import ClauseVisitor
+
+__tmp = locals().keys()
+__all__ = sorted([i for i in __tmp if not i.startswith('__')])

sqlalchemy/sql/functions.py

@@ -0,0 +1,104 @@
+from sqlalchemy import types as sqltypes
+from sqlalchemy.sql.expression import (
+    ClauseList, Function, _literal_as_binds, text, _type_from_args
+    )
+from sqlalchemy.sql import operators
+from sqlalchemy.sql.visitors import VisitableType
+
+class _GenericMeta(VisitableType):
+    def __call__(self, *args, **kwargs):
+        args = [_literal_as_binds(c) for c in args]
+        return type.__call__(self, *args, **kwargs)
+
+class GenericFunction(Function):
+    __metaclass__ = _GenericMeta
+
+    def __init__(self, type_=None, args=(), **kwargs):
+        self.packagenames = []
+        self.name = self.__class__.__name__
+        self._bind = kwargs.get('bind', None)
+        self.clause_expr = ClauseList(
+                operator=operators.comma_op,
+                group_contents=True, *args).self_group()
+        self.type = sqltypes.to_instance(
+            type_ or getattr(self, '__return_type__', None))
+
+class AnsiFunction(GenericFunction):
+    def __init__(self, **kwargs):
+        GenericFunction.__init__(self, **kwargs)
+
+class ReturnTypeFromArgs(GenericFunction):
+    """Define a function whose return type is the same as its arguments."""
+    
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('type_', _type_from_args(args))
+        GenericFunction.__init__(self, args=args, **kwargs)
+
+class coalesce(ReturnTypeFromArgs):
+    pass
+
+class max(ReturnTypeFromArgs):
+    pass
+
+class min(ReturnTypeFromArgs):
+    pass
+
+class sum(ReturnTypeFromArgs):
+    pass
+
+class now(GenericFunction):
+    __return_type__ = sqltypes.DateTime
+
+class concat(GenericFunction):
+    __return_type__ = sqltypes.String
+    def __init__(self, *args, **kwargs):
+        GenericFunction.__init__(self, args=args, **kwargs)
+
+class char_length(GenericFunction):
+    __return_type__ = sqltypes.Integer
+
+    def __init__(self, arg, **kwargs):
+        GenericFunction.__init__(self, args=[arg], **kwargs)
+
+class random(GenericFunction):
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault('type_', None)
+        GenericFunction.__init__(self, args=args, **kwargs)
+
+class count(GenericFunction):
+    """The ANSI COUNT aggregate function.  With no arguments, emits COUNT \*."""
+
+    __return_type__ = sqltypes.Integer
+
+    def __init__(self, expression=None, **kwargs):
+        if expression is None:
+            expression = text('*')
+        GenericFunction.__init__(self, args=(expression,), **kwargs)
+
+class current_date(AnsiFunction):
+    __return_type__ = sqltypes.Date
+
+class current_time(AnsiFunction):
+    __return_type__ = sqltypes.Time
+
+class current_timestamp(AnsiFunction):
+    __return_type__ = sqltypes.DateTime
+
+class current_user(AnsiFunction):
+    __return_type__ = sqltypes.String
+
+class localtime(AnsiFunction):
+    __return_type__ = sqltypes.DateTime
+
+class localtimestamp(AnsiFunction):
+    __return_type__ = sqltypes.DateTime
+
+class session_user(AnsiFunction):
+    __return_type__ = sqltypes.String
+
+class sysdate(AnsiFunction):
+    __return_type__ = sqltypes.DateTime
+
+class user(AnsiFunction):
+    __return_type__ = sqltypes.String
+

sqlalchemy/sql/operators.py

@@ -0,0 +1,135 @@
+# This module is part of SQLAlchemy and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+"""Defines operators used in SQL expressions."""
+
+from operator import (
+    and_, or_, inv, add, mul, sub, mod, truediv, lt, le, ne, gt, ge, eq, neg
+    )
+    
+# Py2K
+from operator import (div,)
+# end Py2K
+
+from sqlalchemy.util import symbol
+
+
+def from_():
+    raise NotImplementedError()
+
+def as_():
+    raise NotImplementedError()
+
+def exists():
+    raise NotImplementedError()
+
+def is_():
+    raise NotImplementedError()
+
+def isnot():
+    raise NotImplementedError()
+
+def collate():
+    raise NotImplementedError()
+
+def op(a, opstring, b):
+    return a.op(opstring)(b)
+
+def like_op(a, b, escape=None):
+    return a.like(b, escape=escape)
+
+def notlike_op(a, b, escape=None):
+    raise NotImplementedError()
+
+def ilike_op(a, b, escape=None):
+    return a.ilike(b, escape=escape)
+
+def notilike_op(a, b, escape=None):
+    raise NotImplementedError()
+
+def between_op(a, b, c):
+    return a.between(b, c)
+
+def in_op(a, b):
+    return a.in_(b)
+
+def notin_op(a, b):
+    raise NotImplementedError()
+
+def distinct_op(a):
+    return a.distinct()
+
+def startswith_op(a, b, escape=None):
+    return a.startswith(b, escape=escape)
+
+def endswith_op(a, b, escape=None):
+    return a.endswith(b, escape=escape)
+
+def contains_op(a, b, escape=None):
+    return a.contains(b, escape=escape)
+
+def match_op(a, b):
+    return a.match(b)
+
+def comma_op(a, b):
+    raise NotImplementedError()
+
+def concat_op(a, b):
+    return a.concat(b)
+
+def desc_op(a):
+    return a.desc()
+
+def asc_op(a):
+    return a.asc()
+
+_commutative = set([eq, ne, add, mul])
+def is_commutative(op):
+    return op in _commutative
+
+_smallest = symbol('_smallest')
+_largest = symbol('_largest')
+
+_PRECEDENCE = {
+    from_: 15,
+    mul: 7,
+    truediv: 7,
+    # Py2K
+    div: 7,
+    # end Py2K
+    mod: 7,
+    neg: 7,
+    add: 6,
+    sub: 6,
+    concat_op: 6,
+    match_op: 6,
+    ilike_op: 5,
+    notilike_op: 5,
+    like_op: 5,
+    notlike_op: 5,
+    in_op: 5,
+    notin_op: 5,
+    is_: 5,
+    isnot: 5,
+    eq: 5,
+    ne: 5,
+    gt: 5,
+    lt: 5,
+    ge: 5,
+    le: 5,
+    between_op: 5,
+    distinct_op: 5,
+    inv: 5,
+    and_: 3,
+    or_: 2,
+    comma_op: -1,
+    collate: 7,
+    as_: -1,
+    exists: 0,
+    _smallest: -1000,
+    _largest: 1000
+}
+
+def is_precedent(operator, against):
+    return (_PRECEDENCE.get(operator, _PRECEDENCE[_smallest]) <=
+            _PRECEDENCE.get(against, _PRECEDENCE[_largest]))

sqlalchemy/sql/util.py

@@ -0,0 +1,651 @@
+from sqlalchemy import exc, schema, topological, util, sql, types as sqltypes
+from sqlalchemy.sql import expression, operators, visitors
+from itertools import chain
+
+"""Utility functions that build upon SQL and Schema constructs."""
+
+def sort_tables(tables):
+    """sort a collection of Table objects in order of their foreign-key dependency."""
+    
+    tables = list(tables)
+    tuples = []
+    def visit_foreign_key(fkey):
+        if fkey.use_alter:
+            return
+        parent_table = fkey.column.table
+        if parent_table in tables:
+            child_table = fkey.parent.table
+            tuples.append( ( parent_table, child_table ) )
+
+    for table in tables:
+        visitors.traverse(table, {'schema_visitor':True}, {'foreign_key':visit_foreign_key})    
+    return topological.sort(tuples, tables)
+
+def find_join_source(clauses, join_to):
+    """Given a list of FROM clauses and a selectable, 
+    return the first index and element from the list of 
+    clauses which can be joined against the selectable.  returns 
+    None, None if no match is found.
+    
+    e.g.::
+    
+        clause1 = table1.join(table2)
+        clause2 = table4.join(table5)
+        
+        join_to = table2.join(table3)
+        
+        find_join_source([clause1, clause2], join_to) == clause1
+    
+    """
+    
+    selectables = list(expression._from_objects(join_to))
+    for i, f in enumerate(clauses):
+        for s in selectables:
+            if f.is_derived_from(s):
+                return i, f
+    else:
+        return None, None
+
+    
+    
+def find_tables(clause, check_columns=False, 
+                include_aliases=False, include_joins=False, 
+                include_selects=False, include_crud=False):
+    """locate Table objects within the given expression."""
+    
+    tables = []
+    _visitors = {}
+    
+    if include_selects:
+        _visitors['select'] = _visitors['compound_select'] = tables.append
+    
+    if include_joins:
+        _visitors['join'] = tables.append
+        
+    if include_aliases:
+        _visitors['alias']  = tables.append
+    
+    if include_crud:
+        _visitors['insert'] = _visitors['update'] = \
+                    _visitors['delete'] = lambda ent: tables.append(ent.table)
+        
+    if check_columns:
+        def visit_column(column):
+            tables.append(column.table)
+        _visitors['column'] = visit_column
+
+    _visitors['table'] = tables.append
+
+    visitors.traverse(clause, {'column_collections':False}, _visitors)
+    return tables
+
+def find_columns(clause):
+    """locate Column objects within the given expression."""
+    
+    cols = util.column_set()
+    visitors.traverse(clause, {}, {'column':cols.add})
+    return cols
+
+def _quote_ddl_expr(element):
+    if isinstance(element, basestring):
+        element = element.replace("'", "''")
+        return "'%s'" % element
+    else:
+        return repr(element)
+    
+def expression_as_ddl(clause):
+    """Given a SQL expression, convert for usage in DDL, such as 
+     CREATE INDEX and CHECK CONSTRAINT.
+     
+     Converts bind params into quoted literals, column identifiers
+     into detached column constructs so that the parent table
+     identifier is not included.
+    
+    """
+    def repl(element):
+        if isinstance(element, expression._BindParamClause):
+            return expression.literal_column(_quote_ddl_expr(element.value))
+        elif isinstance(element, expression.ColumnClause) and \
+                element.table is not None:
+            return expression.column(element.name)
+        else:
+            return None
+        
+    return visitors.replacement_traverse(clause, {}, repl)
+    
+def adapt_criterion_to_null(crit, nulls):
+    """given criterion containing bind params, convert selected elements to IS NULL."""
+
+    def visit_binary(binary):
+        if isinstance(binary.left, expression._BindParamClause) and binary.left.key in nulls:
+            # reverse order if the NULL is on the left side
+            binary.left = binary.right
+            binary.right = expression.null()
+            binary.operator = operators.is_
+            binary.negate = operators.isnot
+        elif isinstance(binary.right, expression._BindParamClause) and binary.right.key in nulls:
+            binary.right = expression.null()
+            binary.operator = operators.is_
+            binary.negate = operators.isnot
+
+    return visitors.cloned_traverse(crit, {}, {'binary':visit_binary})
+    
+    
+def join_condition(a, b, ignore_nonexistent_tables=False, a_subset=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: This flag will cause the
+    function to silently skip over foreign key resolution errors
+    due to nonexistent tables - the assumption is that these
+    tables have not yet been defined within an initialization process
+    and are not significant to the operation.
+
+    :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".
+    
+    """
+    crit = []
+    constraints = set()
+    
+    for left in (a_subset, a):
+        if left is None:
+            continue
+        for fk in b.foreign_keys:
+            try:
+                col = fk.get_referent(left)
+            except exc.NoReferencedTableError:
+                if ignore_nonexistent_tables:
+                    continue
+                else:
+                    raise
+                
+            if col is not None:
+                crit.append(col == fk.parent)
+                constraints.add(fk.constraint)
+        if left is not b:
+            for fk in left.foreign_keys:
+                try:
+                    col = fk.get_referent(b)
+                except exc.NoReferencedTableError:
+                    if ignore_nonexistent_tables:
+                        continue
+                    else:
+                        raise
+
+                if col is not None:
+                    crit.append(col == fk.parent)
+                    constraints.add(fk.constraint)
+        if crit:
+            break
+            
+    if len(crit) == 0:
+        if isinstance(b, expression._FromGrouping):
+            hint = " Perhaps you meant to convert the right side to a subquery using alias()?"
+        else:
+            hint = ""
+        raise exc.ArgumentError(
+            "Can't find any foreign key relationships "
+            "between '%s' and '%s'.%s" % (a.description, b.description, hint))
+    elif len(constraints) > 1:
+        raise exc.ArgumentError(
+            "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))
+    elif len(crit) == 1:
+        return (crit[0])
+    else:
+        return sql.and_(*crit)
+
+
+class Annotated(object):
+    """clones a ClauseElement and applies an 'annotations' dictionary.
+    
+    Unlike regular clones, this clone also mimics __hash__() and 
+    __cmp__() of the original element so that it takes its place
+    in hashed collections.
+    
+    A reference to the original element is maintained, for the important
+    reason of keeping its hash value current.  When GC'ed, the 
+    hash value may be reused, causing conflicts.
+
+    """
+    
+    def __new__(cls, *args):
+        if not args:
+            # clone constructor
+            return object.__new__(cls)
+        else:
+            element, values = args
+            # pull appropriate subclass from registry of annotated
+            # classes
+            try:
+                cls = annotated_classes[element.__class__]
+            except KeyError:
+                cls = annotated_classes[element.__class__] = type.__new__(type, 
+                        "Annotated%s" % element.__class__.__name__, 
+                        (Annotated, element.__class__), {})
+            return object.__new__(cls)
+
+    def __init__(self, element, values):
+        # force FromClause to generate their internal 
+        # collections into __dict__
+        if isinstance(element, expression.FromClause):
+            element.c
+        
+        self.__dict__ = element.__dict__.copy()
+        self.__element = element
+        self._annotations = values
+
+    def _annotate(self, values):
+        _values = self._annotations.copy()
+        _values.update(values)
+        clone = self.__class__.__new__(self.__class__)
+        clone.__dict__ = self.__dict__.copy()
+        clone._annotations = _values
+        return clone
+    
+    def _deannotate(self):
+        return self.__element
+        
+    def _clone(self):
+        clone = self.__element._clone()
+        if clone is self.__element:
+            # detect immutable, don't change anything
+            return self
+        else:
+            # update the clone with any changes that have occured
+            # to this object's __dict__.
+            clone.__dict__.update(self.__dict__)
+            return Annotated(clone, self._annotations)
+    
+    def __hash__(self):
+        return hash(self.__element)
+
+    def __cmp__(self, other):
+        return cmp(hash(self.__element), hash(other))
+
+# hard-generate Annotated subclasses.  this technique
+# is used instead of on-the-fly types (i.e. type.__new__())
+# so that the resulting objects are pickleable.
+annotated_classes = {}
+
+from sqlalchemy.sql import expression
+for cls in expression.__dict__.values() + [schema.Column, schema.Table]:
+    if isinstance(cls, type) and issubclass(cls, expression.ClauseElement):
+        exec "class Annotated%s(Annotated, cls):\n" \
+             "    __visit_name__ = cls.__visit_name__\n"\
+             "    pass" % (cls.__name__, ) in locals()
+        exec "annotated_classes[cls] = Annotated%s" % (cls.__name__)
+
+def _deep_annotate(element, annotations, exclude=None):
+    """Deep copy the given ClauseElement, annotating each element with the given annotations dictionary.
+
+    Elements within the exclude collection will be cloned but not annotated.
+
+    """
+    def clone(elem):
+        # check if element is present in the exclude list.
+        # take into account proxying relationships.
+        if exclude and \
+                    hasattr(elem, 'proxy_set') and \
+                    elem.proxy_set.intersection(exclude):
+            elem = elem._clone()
+        elif annotations != elem._annotations:
+            elem = elem._annotate(annotations.copy())
+        elem._copy_internals(clone=clone)
+        return elem
+
+    if element is not None:
+        element = clone(element)
+    return element
+
+def _deep_deannotate(element):
+    """Deep copy the given element, removing all annotations."""
+
+    def clone(elem):
+        elem = elem._deannotate()
+        elem._copy_internals(clone=clone)
+        return elem
+
+    if element is not None:
+        element = clone(element)
+    return element
+
+
+def splice_joins(left, right, stop_on=None):
+    if left is None:
+        return right
+        
+    stack = [(right, None)]
+
+    adapter = ClauseAdapter(left)
+    ret = None
+    while stack:
+        (right, prevright) = stack.pop()
+        if isinstance(right, expression.Join) and right is not stop_on:
+            right = right._clone()
+            right._reset_exported()
+            right.onclause = adapter.traverse(right.onclause)
+            stack.append((right.left, right))
+        else:
+            right = adapter.traverse(right)
+        if prevright is not None:
+            prevright.left = right
+        if ret is None:
+            ret = right
+
+    return ret
+    
+def reduce_columns(columns, *clauses, **kw):
+    """given a list of columns, return a 'reduced' set based on natural equivalents.
+
+    the set is reduced to the smallest list of columns which have no natural
+    equivalent present in the list.  A "natural equivalent" means that two columns
+    will ultimately represent the same value because they are related by a foreign key.
+
+    \*clauses is an optional list of join clauses which will be traversed
+    to further identify columns that are "equivalent".
+
+    \**kw may specify 'ignore_nonexistent_tables' to ignore foreign keys
+    whose tables are not yet configured.
+    
+    This function is primarily used to determine the most minimal "primary key"
+    from a selectable, by reducing the set of primary key columns present
+    in the the selectable to just those that are not repeated.
+
+    """
+    ignore_nonexistent_tables = kw.pop('ignore_nonexistent_tables', False)
+    
+    columns = util.ordered_column_set(columns)
+
+    omit = util.column_set()
+    for col in columns:
+        for fk in chain(*[c.foreign_keys for c in col.proxy_set]):
+            for c in columns:
+                if c is col:
+                    continue
+                try:
+                    fk_col = fk.column
+                except exc.NoReferencedTableError:
+                    if ignore_nonexistent_tables:
+                        continue
+                    else:
+                        raise
+                if fk_col.shares_lineage(c):
+                    omit.add(col)
+                    break
+
+    if clauses:
+        def visit_binary(binary):
+            if binary.operator == operators.eq:
+                cols = util.column_set(chain(*[c.proxy_set for c in columns.difference(omit)]))
+                if binary.left in cols and binary.right in cols:
+                    for c in columns:
+                        if c.shares_lineage(binary.right):
+                            omit.add(c)
+                            break
+        for clause in clauses:
+            visitors.traverse(clause, {}, {'binary':visit_binary})
+
+    return expression.ColumnSet(columns.difference(omit))
+
+def criterion_as_pairs(expression, consider_as_foreign_keys=None, 
+                        consider_as_referenced_keys=None, any_operator=False):
+    """traverse an expression and locate binary criterion pairs."""
+    
+    if consider_as_foreign_keys and consider_as_referenced_keys:
+        raise exc.ArgumentError("Can only specify one of "
+                                "'consider_as_foreign_keys' or "
+                                "'consider_as_referenced_keys'")
+        
+    def visit_binary(binary):
+        if not any_operator and binary.operator is not operators.eq:
+            return
+        if not isinstance(binary.left, sql.ColumnElement) or \
+                    not isinstance(binary.right, sql.ColumnElement):
+            return
+
+        if consider_as_foreign_keys:
+            if binary.left in consider_as_foreign_keys and \
+                        (binary.right is binary.left or 
+                        binary.right not in consider_as_foreign_keys):
+                pairs.append((binary.right, binary.left))
+            elif binary.right in consider_as_foreign_keys and \
+                        (binary.left is binary.right or 
+                        binary.left not in consider_as_foreign_keys):
+                pairs.append((binary.left, binary.right))
+        elif consider_as_referenced_keys:
+            if binary.left in consider_as_referenced_keys and \
+                        (binary.right is binary.left or 
+                        binary.right not in consider_as_referenced_keys):
+                pairs.append((binary.left, binary.right))
+            elif binary.right in consider_as_referenced_keys and \
+                        (binary.left is binary.right or 
+                        binary.left not in consider_as_referenced_keys):
+                pairs.append((binary.right, binary.left))
+        else:
+            if isinstance(binary.left, schema.Column) and \
+                        isinstance(binary.right, schema.Column):
+                if binary.left.references(binary.right):
+                    pairs.append((binary.right, binary.left))
+                elif binary.right.references(binary.left):
+                    pairs.append((binary.left, binary.right))
+    pairs = []
+    visitors.traverse(expression, {}, {'binary':visit_binary})
+    return pairs
+
+def folded_equivalents(join, equivs=None):
+    """Return a list of uniquely named columns.
+    
+    The column list of the given Join will be narrowed 
+    down to a list of all equivalently-named,
+    equated columns folded into one column, where 'equated' means they are
+    equated to each other in the ON clause of this join.
+
+    This function is used by Join.select(fold_equivalents=True).
+    
+    Deprecated.   This function is used for a certain kind of 
+    "polymorphic_union" which is designed to achieve joined
+    table inheritance where the base table has no "discriminator"
+    column; [ticket:1131] will provide a better way to 
+    achieve this.
+
+    """
+    if equivs is None:
+        equivs = set()
+    def visit_binary(binary):
+        if binary.operator == operators.eq and binary.left.name == binary.right.name:
+            equivs.add(binary.right)
+            equivs.add(binary.left)
+    visitors.traverse(join.onclause, {}, {'binary':visit_binary})
+    collist = []
+    if isinstance(join.left, expression.Join):
+        left = folded_equivalents(join.left, equivs)
+    else:
+        left = list(join.left.columns)
+    if isinstance(join.right, expression.Join):
+        right = folded_equivalents(join.right, equivs)
+    else:
+        right = list(join.right.columns)
+    used = set()
+    for c in left + right:
+        if c in equivs:
+            if c.name not in used:
+                collist.append(c)
+                used.add(c.name)
+        else:
+            collist.append(c)
+    return collist
+
+class AliasedRow(object):
+    """Wrap a RowProxy with a translation map.
+    
+    This object allows a set of keys to be translated
+    to those present in a RowProxy.
+    
+    """
+    def __init__(self, row, map):
+        # AliasedRow objects don't nest, so un-nest
+        # if another AliasedRow was passed
+        if isinstance(row, AliasedRow):
+            self.row = row.row
+        else:
+            self.row = row
+        self.map = map
+        
+    def __contains__(self, key):
+        return self.map[key] in self.row
+
+    def has_key(self, key):
+        return key in self
+
+    def __getitem__(self, key):
+        return self.row[self.map[key]]
+
+    def keys(self):
+        return self.row.keys()
+
+
+class ClauseAdapter(visitors.ReplacingCloningVisitor):
+    """Clones and modifies clauses based on column correspondence.
+    
+    E.g.::
+
+      table1 = Table('sometable', metadata,
+          Column('col1', Integer),
+          Column('col2', Integer)
+          )
+      table2 = Table('someothertable', metadata,
+          Column('col1', Integer),
+          Column('col2', Integer)
+          )
+
+      condition = table1.c.col1 == table2.c.col1
+
+    make an alias of table1::
+
+      s = table1.alias('foo')
+
+    calling ``ClauseAdapter(s).traverse(condition)`` converts
+    condition to read::
+
+      s.c.col1 == table2.c.col1
+
+    """
+    def __init__(self, selectable, equivalents=None, include=None, exclude=None):
+        self.__traverse_options__ = {'column_collections':False, 'stop_on':[selectable]}
+        self.selectable = selectable
+        self.include = include
+        self.exclude = exclude
+        self.equivalents = util.column_dict(equivalents or {})
+        
+    def _corresponding_column(self, col, require_embedded, _seen=util.EMPTY_SET):
+        newcol = self.selectable.corresponding_column(col, require_embedded=require_embedded)
+
+        if newcol is None and col in self.equivalents and col not in _seen:
+            for equiv in self.equivalents[col]:
+                newcol = self._corresponding_column(equiv, require_embedded=require_embedded, _seen=_seen.union([col]))
+                if newcol is not None:
+                    return newcol
+        return newcol
+
+    def replace(self, col):
+        if isinstance(col, expression.FromClause):
+            if self.selectable.is_derived_from(col):
+                return self.selectable
+
+        if not isinstance(col, expression.ColumnElement):
+            return None
+
+        if self.include and col not in self.include:
+            return None
+        elif self.exclude and col in self.exclude:
+            return None
+        
+        return self._corresponding_column(col, True)
+
+class ColumnAdapter(ClauseAdapter):
+    """Extends ClauseAdapter with extra utility functions.
+    
+    Provides the ability to "wrap" this ClauseAdapter 
+    around another, a columns dictionary which returns
+    adapted elements given an original, and an 
+    adapted_row() factory.
+    
+    """
+    def __init__(self, selectable, equivalents=None, 
+                        chain_to=None, include=None, 
+                        exclude=None, adapt_required=False):
+        ClauseAdapter.__init__(self, selectable, equivalents, include, exclude)
+        if chain_to:
+            self.chain(chain_to)
+        self.columns = util.populate_column_dict(self._locate_col)
+        self.adapt_required = adapt_required
+
+    def wrap(self, adapter):
+        ac = self.__class__.__new__(self.__class__)
+        ac.__dict__ = self.__dict__.copy()
+        ac._locate_col = ac._wrap(ac._locate_col, adapter._locate_col)
+        ac.adapt_clause = ac._wrap(ac.adapt_clause, adapter.adapt_clause)
+        ac.adapt_list = ac._wrap(ac.adapt_list, adapter.adapt_list)
+        ac.columns = util.populate_column_dict(ac._locate_col)
+        return ac
+
+    adapt_clause = ClauseAdapter.traverse
+    adapt_list = ClauseAdapter.copy_and_process
+
+    def _wrap(self, local, wrapped):
+        def locate(col):
+            col = local(col)
+            return wrapped(col)
+        return locate
+
+    def _locate_col(self, col):
+        c = self._corresponding_column(col, True)
+        if c is None:
+            c = self.adapt_clause(col)
+            
+            # anonymize labels in case they have a hardcoded name
+            if isinstance(c, expression._Label):
+                c = c.label(None)
+                
+        # adapt_required indicates that if we got the same column
+        # back which we put in (i.e. it passed through), 
+        # it's not correct.  this is used by eagerloading which
+        # knows that all columns and expressions need to be adapted
+        # to a result row, and a "passthrough" is definitely targeting
+        # the wrong column.
+        if self.adapt_required and c is col:
+            return None
+            
+        return c    
+
+    def adapted_row(self, row):
+        return AliasedRow(row, self.columns)
+    
+    def __getstate__(self):
+        d = self.__dict__.copy()
+        del d['columns']
+        return d
+        
+    def __setstate__(self, state):
+        self.__dict__.update(state)
+        self.columns = util.PopulateDict(self._locate_col)

sqlalchemy/sql/visitors.py

@@ -0,0 +1,256 @@
+"""Visitor/traversal interface and library functions.
+
+SQLAlchemy schema and expression constructs rely on a Python-centric
+version of the classic "visitor" pattern as the primary way in which
+they apply functionality.  The most common use of this pattern 
+is statement compilation, where individual expression classes match 
+up to rendering methods that produce a string result.   Beyond this, 
+the visitor system is also used to inspect expressions for various 
+information and patterns, as well as for usage in 
+some kinds of expression transformation.  Other kinds of transformation
+use a non-visitor traversal system.
+
+For many examples of how the visit system is used, see the 
+sqlalchemy.sql.util and the sqlalchemy.sql.compiler modules.
+For an introduction to clause adaption, see
+http://techspot.zzzeek.org/?p=19 .
+
+"""
+
+from collections import deque
+import re
+from sqlalchemy import util
+import operator
+
+__all__ = ['VisitableType', 'Visitable', 'ClauseVisitor', 
+    'CloningVisitor', 'ReplacingCloningVisitor', 'iterate', 
+    'iterate_depthfirst', 'traverse_using', 'traverse',
+    'cloned_traverse', 'replacement_traverse']
+    
+class VisitableType(type):
+    """Metaclass which checks for a `__visit_name__` attribute and
+    applies `_compiler_dispatch` method to classes.
+    
+    """
+    
+    def __init__(cls, clsname, bases, clsdict):
+        if cls.__name__ == 'Visitable' or not hasattr(cls, '__visit_name__'):
+            super(VisitableType, cls).__init__(clsname, bases, clsdict)
+            return
+        
+        # set up an optimized visit dispatch function
+        # for use by the compiler
+        visit_name = cls.__visit_name__
+        if isinstance(visit_name, str):
+            getter = operator.attrgetter("visit_%s" % visit_name)
+            def _compiler_dispatch(self, visitor, **kw):
+                return getter(visitor)(self, **kw)
+        else:
+            def _compiler_dispatch(self, visitor, **kw):
+                return getattr(visitor, 'visit_%s' % self.__visit_name__)(self, **kw)
+    
+        cls._compiler_dispatch = _compiler_dispatch
+        
+        super(VisitableType, cls).__init__(clsname, bases, clsdict)
+
+class Visitable(object):
+    """Base class for visitable objects, applies the
+    ``VisitableType`` metaclass.
+    
+    """
+
+    __metaclass__ = VisitableType
+
+class ClauseVisitor(object):
+    """Base class for visitor objects which can traverse using 
+    the traverse() function.
+    
+    """
+    
+    __traverse_options__ = {}
+    
+    def traverse_single(self, obj):
+        for v in self._visitor_iterator:
+            meth = getattr(v, "visit_%s" % obj.__visit_name__, None)
+            if meth:
+                return meth(obj)
+    
+    def iterate(self, obj):
+        """traverse the given expression structure, returning an iterator of all elements."""
+
+        return iterate(obj, self.__traverse_options__)
+        
+    def traverse(self, obj):
+        """traverse and visit the given expression structure."""
+
+        return traverse(obj, self.__traverse_options__, self._visitor_dict)
+    
+    @util.memoized_property
+    def _visitor_dict(self):
+        visitors = {}
+
+        for name in dir(self):
+            if name.startswith('visit_'):
+                visitors[name[6:]] = getattr(self, name)
+        return visitors
+        
+    @property
+    def _visitor_iterator(self):
+        """iterate through this visitor and each 'chained' visitor."""
+        
+        v = self
+        while v:
+            yield v
+            v = getattr(v, '_next', None)
+
+    def chain(self, visitor):
+        """'chain' an additional ClauseVisitor onto this ClauseVisitor.
+        
+        the chained visitor will receive all visit events after this one.
+        
+        """
+        tail = list(self._visitor_iterator)[-1]
+        tail._next = visitor
+        return self
+
+class CloningVisitor(ClauseVisitor):
+    """Base class for visitor objects which can traverse using 
+    the cloned_traverse() function.
+    
+    """
+
+    def copy_and_process(self, list_):
+        """Apply cloned traversal to the given list of elements, and return the new list."""
+
+        return [self.traverse(x) for x in list_]
+
+    def traverse(self, obj):
+        """traverse and visit the given expression structure."""
+
+        return cloned_traverse(obj, self.__traverse_options__, self._visitor_dict)
+
+class ReplacingCloningVisitor(CloningVisitor):
+    """Base class for visitor objects which can traverse using 
+    the replacement_traverse() function.
+    
+    """
+
+    def replace(self, elem):
+        """receive pre-copied elements during a cloning traversal.
+        
+        If the method returns a new element, the element is used 
+        instead of creating a simple copy of the element.  Traversal 
+        will halt on the newly returned element if it is re-encountered.
+        """
+        return None
+
+    def traverse(self, obj):
+        """traverse and visit the given expression structure."""
+
+        def replace(elem):
+            for v in self._visitor_iterator:
+                e = v.replace(elem)
+                if e is not None:
+                    return e
+        return replacement_traverse(obj, self.__traverse_options__, replace)
+
+def iterate(obj, opts):
+    """traverse the given expression structure, returning an iterator.
+    
+    traversal is configured to be breadth-first.
+    
+    """
+    stack = deque([obj])
+    while stack:
+        t = stack.popleft()
+        yield t
+        for c in t.get_children(**opts):
+            stack.append(c)
+
+def iterate_depthfirst(obj, opts):
+    """traverse the given expression structure, returning an iterator.
+    
+    traversal is configured to be depth-first.
+    
+    """
+    stack = deque([obj])
+    traversal = deque()
+    while stack:
+        t = stack.pop()
+        traversal.appendleft(t)
+        for c in t.get_children(**opts):
+            stack.append(c)
+    return iter(traversal)
+
+def traverse_using(iterator, obj, visitors):
+    """visit the given expression structure using the given iterator of objects."""
+
+    for target in iterator:
+        meth = visitors.get(target.__visit_name__, None)
+        if meth:
+            meth(target)
+    return obj
+    
+def traverse(obj, opts, visitors):
+    """traverse and visit the given expression structure using the default iterator."""
+
+    return traverse_using(iterate(obj, opts), obj, visitors)
+
+def traverse_depthfirst(obj, opts, visitors):
+    """traverse and visit the given expression structure using the depth-first iterator."""
+
+    return traverse_using(iterate_depthfirst(obj, opts), obj, visitors)
+
+def cloned_traverse(obj, opts, visitors):
+    """clone the given expression structure, allowing modifications by visitors."""
+    
+    cloned = util.column_dict()
+
+    def clone(element):
+        if element not in cloned:
+            cloned[element] = element._clone()
+        return cloned[element]
+
+    obj = clone(obj)
+    stack = [obj]
+
+    while stack:
+        t = stack.pop()
+        if t in cloned:
+            continue
+        t._copy_internals(clone=clone)
+
+        meth = visitors.get(t.__visit_name__, None)
+        if meth:
+            meth(t)
+
+        for c in t.get_children(**opts):
+            stack.append(c)
+    return obj
+
+def replacement_traverse(obj, opts, replace):
+    """clone the given expression structure, allowing element replacement by a given replacement function."""
+    
+    cloned = util.column_dict()
+    stop_on = util.column_set(opts.get('stop_on', []))
+
+    def clone(element):
+        newelem = replace(element)
+        if newelem is not None:
+            stop_on.add(newelem)
+            return newelem
+
+        if element not in cloned:
+            cloned[element] = element._clone()
+        return cloned[element]
+
+    obj = clone(obj)
+    stack = [obj]
+    while stack:
+        t = stack.pop()
+        if t in stop_on:
+            continue
+        t._copy_internals(clone=clone)
+        for c in t.get_children(**opts):
+            stack.append(c)
+    return obj