- The official name for the relation() function is now

relationship(), to eliminate confusion over the relational
algebra term.  relation() however will remain available
in equal capacity for the foreseeable future.  [ticket:1740]

23 files changed, 81 insertions, 81 deletions

diff --git a/examples/adjacency_list/adjacency_list.py b/examples/adjacency_list/adjacency_list.py
index cc539c054..494ae1c27 100644
--- a/examples/adjacency_list/adjacency_list.py
+++ b/examples/adjacency_list/adjacency_list.py
@@ -1,7 +1,7 @@
 from sqlalchemy import MetaData, Table, Column, Sequence, ForeignKey,\
                         Integer, String, create_engine
                         
-from sqlalchemy.orm import sessionmaker, mapper, relation, backref,\
+from sqlalchemy.orm import sessionmaker, mapper, relationship, backref,\
                                 eagerload_all
                                 
 from sqlalchemy.orm.collections import attribute_mapped_collection
@@ -40,7 +40,7 @@ def dump_tree(node, indent=0):
                     
 
 mapper(TreeNode, tree_table, properties={
-    'children': relation(TreeNode, 
+    'children': relationship(TreeNode, 
 
                         # cascade deletions
                         cascade="all",
diff --git a/examples/association/basic_association.py b/examples/association/basic_association.py
index a56d2383e..83f53e000 100644
--- a/examples/association/basic_association.py
+++ b/examples/association/basic_association.py
@@ -14,7 +14,7 @@ from datetime import datetime
 
 from sqlalchemy import (create_engine, MetaData, Table, Column, Integer,
     String, DateTime, Numeric, ForeignKey, and_)
-from sqlalchemy.orm import mapper, relation, create_session
+from sqlalchemy.orm import mapper, relationship, create_session
 
 # Uncomment these to watch database activity.
 #import logging
@@ -62,12 +62,12 @@ class OrderItem(object):
         self.price = price or item.price
         
 mapper(Order, orders, properties={
-    'order_items': relation(OrderItem, cascade="all, delete-orphan",
+    'order_items': relationship(OrderItem, cascade="all, delete-orphan",
                             backref='order')
 })
 mapper(Item, items)
 mapper(OrderItem, orderitems, properties={
-    'item': relation(Item, lazy=False)
+    'item': relationship(Item, lazy=False)
 })
 
 session = create_session()
diff --git a/examples/association/proxied_association.py b/examples/association/proxied_association.py
index 3a78e3adf..68f8450a5 100644
--- a/examples/association/proxied_association.py
+++ b/examples/association/proxied_association.py
@@ -4,7 +4,7 @@ the usage of the associationproxy extension."""
 from datetime import datetime
 from sqlalchemy import (create_engine, MetaData, Table, Column, Integer,
     String, DateTime, Float, ForeignKey, and_)
-from sqlalchemy.orm import mapper, relation, create_session
+from sqlalchemy.orm import mapper, relationship, create_session
 from sqlalchemy.ext.associationproxy import AssociationProxy
 
 engine = create_engine('sqlite://')
@@ -48,11 +48,11 @@ class Item(object):
 
 
 mapper(Order, orders, properties={
-    'itemassociations':relation(OrderItem, cascade="all, delete-orphan", lazy=False)
+    'itemassociations':relationship(OrderItem, cascade="all, delete-orphan", lazy=False)
 })
 mapper(Item, items)
 mapper(OrderItem, orderitems, properties={
-    'item':relation(Item, lazy=False)
+    'item':relationship(Item, lazy=False)
 })
 
 session = create_session()
diff --git a/examples/beaker_caching/__init__.py b/examples/beaker_caching/__init__.py
index 9c5fcc8fd..a4e8ec1f1 100644
--- a/examples/beaker_caching/__init__.py
+++ b/examples/beaker_caching/__init__.py
@@ -22,7 +22,7 @@ E.g.::
     
     # specify that each Person's "addresses" collection comes from
     # cache too
-    q = q.options(RelationCache("default", "by_person", Person.addresses))
+    q = q.options(RelationshipCache("default", "by_person", Person.addresses))
     
     # query
     print q.all()
@@ -39,7 +39,7 @@ The demo scripts themselves, in order of complexity, are run as follows::
 
    python examples/beaker_caching/helloworld.py
 
-   python examples/beaker_caching/relation_caching.py
+   python examples/beaker_caching/relationship_caching.py
 
    python examples/beaker_caching/advanced.py
 
@@ -63,8 +63,8 @@ Listing of files:
 
     helloworld.py - the basic idea.
 
-    relation_caching.py - Illustrates how to add cache options on
-    relation endpoints, so that lazyloads load from cache.
+    relationship_caching.py - Illustrates how to add cache options on
+    relationship endpoints, so that lazyloads load from cache.
 
     advanced.py - Further examples of how to use FromCache.  Combines
     techniques from the first two scripts.
diff --git a/examples/beaker_caching/meta.py b/examples/beaker_caching/meta.py
index 57654b9c8..a4e43caf1 100644
--- a/examples/beaker_caching/meta.py
+++ b/examples/beaker_caching/meta.py
@@ -9,7 +9,7 @@ The three new concepts introduced here are:
    retrieves results in/from Beaker.
  * FromCache - a query option that establishes caching
    parameters on a Query
- * RelationCache - a variant of FromCache which is specific
+ * RelationshipCache - a variant of FromCache which is specific
    to a query invoked during a lazy load.
  * _params_from_query - extracts value parameters from 
    a Query.
@@ -52,10 +52,10 @@ class CachingQuery(Query):
     session using Session.merge(load=False), which is a fast performing
     method to ensure state is present.
 
-    The FromCache and RelationCache mapper options below represent
+    The FromCache and RelationshipCache mapper options below represent
     the "public" method of 
     configuring the "cache_region" and "cache_namespace" attributes.
-    RelationCache has the ability to be invoked upon lazy loaders embedded
+    RelationshipCache has the ability to be invoked upon lazy loaders embedded
     in an object graph.
     
     """
@@ -158,14 +158,14 @@ class FromCache(MapperOption):
         
         _set_cache_parameters(query, self.region, self.namespace, self.cache_key)
 
-class RelationCache(MapperOption):
+class RelationshipCache(MapperOption):
     """Specifies that a Query as called within a "lazy load" 
        should load results from a cache."""
 
     propagate_to_loaders = True
 
     def __init__(self, region, namespace, attribute):
-        """Construct a new RelationCache.
+        """Construct a new RelationshipCache.
         
         :param region: the cache region.  Should be a
         region configured in the Beaker CacheManager.
@@ -175,13 +175,13 @@ class RelationCache(MapperOption):
         lexical structure.
         
         :param attribute: A Class.attribute which
-        indicates a particular class relation() whose
+        indicates a particular class relationship() whose
         lazy loader should be pulled from the cache.
         
         """
         self.region = region
         self.namespace = namespace
-        self._relation_options = {
+        self._relationship_options = {
             ( attribute.property.parent.class_, attribute.property.key ) : self
         }
 
@@ -196,23 +196,23 @@ class RelationCache(MapperOption):
             mapper, key = query._current_path[-2:]
 
             for cls in mapper.class_.__mro__:
-                if (cls, key) in self._relation_options:
-                    relation_option = self._relation_options[(cls, key)]
+                if (cls, key) in self._relationship_options:
+                    relationship_option = self._relationship_options[(cls, key)]
                     _set_cache_parameters(
                             query, 
-                            relation_option.region, 
-                            relation_option.namespace, 
+                            relationship_option.region, 
+                            relationship_option.namespace, 
                             None)
 
     def and_(self, option):
-        """Chain another RelationCache option to this one.
+        """Chain another RelationshipCache option to this one.
         
-        While many RelationCache objects can be specified on a single
+        While many RelationshipCache objects can be specified on a single
         Query separately, chaining them together allows for a more efficient
         lookup during load.
         
         """
-        self._relation_options.update(option._relation_options)
+        self._relationship_options.update(option._relationship_options)
         return self
 
 
diff --git a/examples/beaker_caching/model.py b/examples/beaker_caching/model.py
index daae0d512..6ea5e7904 100644
--- a/examples/beaker_caching/model.py
+++ b/examples/beaker_caching/model.py
@@ -9,8 +9,8 @@ City --(has a)--> Country
 
 """
 from sqlalchemy import Column, Integer, String, ForeignKey
-from sqlalchemy.orm import relation
-from meta import Base, FromCache, Session, RelationCache
+from sqlalchemy.orm import relationship
+from meta import Base, FromCache, Session, RelationshipCache
 
 class Country(Base):
     __tablename__ = 'country'
@@ -27,7 +27,7 @@ class City(Base):
     id = Column(Integer, primary_key=True)
     name = Column(String(100), nullable=False)
     country_id = Column(Integer, ForeignKey('country.id'), nullable=False)
-    country = relation(Country)
+    country = relationship(Country)
 
     def __init__(self, name, country):
         self.name = name
@@ -39,7 +39,7 @@ class PostalCode(Base):
     id = Column(Integer, primary_key=True)
     code = Column(String(10), nullable=False)
     city_id = Column(Integer, ForeignKey('city.id'), nullable=False)
-    city = relation(City)
+    city = relationship(City)
     
     @property
     def country(self):
@@ -56,7 +56,7 @@ class Address(Base):
     person_id = Column(Integer, ForeignKey('person.id'), nullable=False)
     street = Column(String(200), nullable=False)
     postal_code_id = Column(Integer, ForeignKey('postal_code.id'))
-    postal_code = relation(PostalCode)
+    postal_code = relationship(PostalCode)
     
     @property
     def city(self):
@@ -77,7 +77,7 @@ class Person(Base):
 
     id = Column(Integer, primary_key=True)
     name = Column(String(100), nullable=False)
-    addresses = relation(Address, collection_class=set)
+    addresses = relationship(Address, collection_class=set)
 
     def __init__(self, name, *addresses):
         self.name = name
@@ -92,13 +92,13 @@ class Person(Base):
     def format_full(self):
         return "\t".join([str(x) for x in [self] + list(self.addresses)])
         
-# Caching options.   A set of three RelationCache options
+# Caching options.   A set of three RelationshipCache options
 # which can be applied to Query(), causing the "lazy load"
 # of these attributes to be loaded from cache.
-cache_address_bits = RelationCache("default", "byid", PostalCode.city).\
+cache_address_bits = RelationshipCache("default", "byid", PostalCode.city).\
                 and_(
-                    RelationCache("default", "byid", City.country)
+                    RelationshipCache("default", "byid", City.country)
                 ).and_(
-                    RelationCache("default", "byid", Address.postal_code)
+                    RelationshipCache("default", "byid", Address.postal_code)
                 )
 
diff --git a/examples/beaker_caching/relation_caching.py b/examples/beaker_caching/relation_caching.py
index 2aeb87bc0..f5f0fad69 100644
--- a/examples/beaker_caching/relation_caching.py
+++ b/examples/beaker_caching/relation_caching.py
@@ -1,4 +1,4 @@
-"""relation_caching.py
+"""relationship_caching.py
 
 Load a set of Person and Address objects, specifying that 
 related PostalCode, City, Country objects should be pulled from long 
@@ -15,7 +15,7 @@ for p in Session.query(Person).options(eagerload(Person.addresses), cache_addres
     print p.format_full()
 
 
-print "\n\nIf this was the first run of relation_caching.py, SQL was likely emitted to "\
+print "\n\nIf this was the first run of relationship_caching.py, SQL was likely emitted to "\
         "load postal codes, cities, countries.\n"\
         "If run a second time, only a single SQL statement will run - all "\
         "related data is pulled from cache.\n"\
diff --git a/examples/custom_attributes/custom_management.py b/examples/custom_attributes/custom_management.py
index 3c80183e2..0ffd0db4b 100644
--- a/examples/custom_attributes/custom_management.py
+++ b/examples/custom_attributes/custom_management.py
@@ -11,7 +11,7 @@ with a custom attribute system as well.
 """
 from sqlalchemy import (create_engine, MetaData, Table, Column, Integer, Text,
     ForeignKey)
-from sqlalchemy.orm import (mapper, relation, create_session,
+from sqlalchemy.orm import (mapper, relationship, create_session,
     InstrumentationManager)
 
 from sqlalchemy.orm.attributes import set_attribute, get_attribute, del_attribute, is_instrumented
@@ -161,7 +161,7 @@ if __name__ == '__main__':
         pass
 
     mapper(A, table1, properties={
-        'bs':relation(B)
+        'bs':relationship(B)
     })
 
     mapper(B, table2)
diff --git a/examples/custom_attributes/listen_for_events.py b/examples/custom_attributes/listen_for_events.py
index 3264b0246..0ae4d8fed 100644
--- a/examples/custom_attributes/listen_for_events.py
+++ b/examples/custom_attributes/listen_for_events.py
@@ -40,7 +40,7 @@ class AttributeListener(AttributeExtension):
 if __name__ == '__main__':
 
     from sqlalchemy import Column, Integer, String, ForeignKey
-    from sqlalchemy.orm import relation
+    from sqlalchemy.orm import relationship
     from sqlalchemy.ext.declarative import declarative_base
 
     class Base(object):
@@ -61,7 +61,7 @@ if __name__ == '__main__':
         id = Column(Integer, primary_key=True)
         data = Column(String(50))
         related_id = Column(Integer, ForeignKey("related.id"))
-        related = relation("Related", backref="mapped")
+        related = relationship("Related", backref="mapped")
 
         def __str__(self):
             return "MyMappedClass(data=%r)" % self.data
diff --git a/examples/dynamic_dict/dynamic_dict.py b/examples/dynamic_dict/dynamic_dict.py
index d94c2426a..8d15fce0b 100644
--- a/examples/dynamic_dict/dynamic_dict.py
+++ b/examples/dynamic_dict/dynamic_dict.py
@@ -30,7 +30,7 @@ class ProxyDict(object):
 

 from sqlalchemy.ext.declarative import declarative_base

 from sqlalchemy import create_engine, Column, Integer, String, ForeignKey

-from sqlalchemy.orm import sessionmaker, relation

+from sqlalchemy.orm import sessionmaker, relationship

 

 engine=create_engine('sqlite://', echo=True)

 Base = declarative_base(engine)

@@ -39,7 +39,7 @@ class Parent(Base):
     __tablename__ = 'parent'

     id = Column(Integer, primary_key=True)

     name = Column(String(50))

-    _collection = relation("Child", lazy="dynamic", cascade="all, delete-orphan")

+    _collection = relationship("Child", lazy="dynamic", cascade="all, delete-orphan")

     

     @property

     def child_map(self):

diff --git a/examples/elementtree/adjacency_list.py b/examples/elementtree/adjacency_list.py
index b16dd780e..ad0f3f607 100644
--- a/examples/elementtree/adjacency_list.py
+++ b/examples/elementtree/adjacency_list.py
@@ -9,7 +9,7 @@ styles of persistence are identical, as is the structure of the main Document cl
 ################################# PART I - Imports/Coniguration ####################################
 from sqlalchemy import (MetaData, Table, Column, Integer, String, ForeignKey,
     Unicode, and_)
-from sqlalchemy.orm import mapper, relation, create_session, lazyload
+from sqlalchemy.orm import mapper, relationship, create_session, lazyload
 
 import sys, os, StringIO, re
 
@@ -79,13 +79,13 @@ class _Attribute(object):
 
 # setup mappers.  Document will eagerly load a list of _Node objects.
 mapper(Document, documents, properties={
-    '_root':relation(_Node, lazy=False, cascade="all")
+    '_root':relationship(_Node, lazy=False, cascade="all")
 })
 
 mapper(_Node, elements, properties={
-    'children':relation(_Node, cascade="all"),
+    'children':relationship(_Node, cascade="all"),
     # eagerly load attributes
-    'attributes':relation(_Attribute, lazy=False, cascade="all, delete-orphan"),
+    'attributes':relationship(_Attribute, lazy=False, cascade="all, delete-orphan"),
 })
 
 mapper(_Attribute, attributes)
diff --git a/examples/elementtree/optimized_al.py b/examples/elementtree/optimized_al.py
index dcc3c00ba..9cd2acc30 100644
--- a/examples/elementtree/optimized_al.py
+++ b/examples/elementtree/optimized_al.py
@@ -8,7 +8,7 @@ which joins on only three tables.
 ################################# PART I - Imports/Configuration ###########################################
 from sqlalchemy import (MetaData, Table, Column, Integer, String, ForeignKey,
     Unicode, and_)
-from sqlalchemy.orm import mapper, relation, create_session, lazyload
+from sqlalchemy.orm import mapper, relationship, create_session, lazyload
 
 import sys, os, StringIO, re
 
@@ -80,16 +80,16 @@ class _Attribute(object):
 # they will be ordered in primary key/insert order, so that we can reconstruct
 # an ElementTree structure from the list.
 mapper(Document, documents, properties={
-    '_nodes':relation(_Node, lazy=False, cascade="all, delete-orphan")
+    '_nodes':relationship(_Node, lazy=False, cascade="all, delete-orphan")
 })
 
 # the _Node objects change the way they load so that a list of _Nodes will organize
 # themselves hierarchically using the ElementTreeMarshal.  this depends on the ordering of
-# nodes being hierarchical as well; relation() always applies at least ROWID/primary key
+# nodes being hierarchical as well; relationship() always applies at least ROWID/primary key
 # ordering to rows which will suffice.
 mapper(_Node, elements, properties={
-    'children':relation(_Node, lazy=None),  # doesnt load; used only for the save relationship
-    'attributes':relation(_Attribute, lazy=False, cascade="all, delete-orphan"), # eagerly load attributes
+    'children':relationship(_Node, lazy=None),  # doesnt load; used only for the save relationship
+    'attributes':relationship(_Attribute, lazy=False, cascade="all, delete-orphan"), # eagerly load attributes
 })
 
 mapper(_Attribute, attributes)
diff --git a/examples/graphs/directed_graph.py b/examples/graphs/directed_graph.py
index 6122e65f1..418239098 100644
--- a/examples/graphs/directed_graph.py
+++ b/examples/graphs/directed_graph.py
@@ -1,7 +1,7 @@
 """a directed graph example."""
 
 from sqlalchemy import MetaData, Table, Column, Integer, ForeignKey
-from sqlalchemy.orm import mapper, relation, create_session
+from sqlalchemy.orm import mapper, relationship, create_session
 
 import logging
 logging.basicConfig()
@@ -42,9 +42,9 @@ class Edge(object):
 
 mapper(Node, nodes)
 mapper(Edge, edges, properties={
-    'lower_node':relation(Node,
+    'lower_node':relationship(Node,
 primaryjoin=edges.c.lower_id==nodes.c.nodeid, backref='lower_edges'),
-    'higher_node':relation(Node,
+    'higher_node':relationship(Node,
 primaryjoin=edges.c.higher_id==nodes.c.nodeid, backref='higher_edges')
     }
 )
diff --git a/examples/inheritance/polymorph.py b/examples/inheritance/polymorph.py
index 4cf13985b..3ebcd6efe 100644
--- a/examples/inheritance/polymorph.py
+++ b/examples/inheritance/polymorph.py
@@ -1,5 +1,5 @@
 from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
-from sqlalchemy.orm import mapper, relation, create_session
+from sqlalchemy.orm import mapper, relationship, create_session
 import sets
 
 # this example illustrates a polymorphic load of two classes
@@ -61,7 +61,7 @@ mapper(Engineer, engineers, inherits=person_mapper, polymorphic_identity='engine
 mapper(Manager, managers, inherits=person_mapper, polymorphic_identity='manager')
 
 mapper(Company, companies, properties={
-    'employees': relation(Person, lazy=False, backref='company', cascade="all, delete-orphan")
+    'employees': relationship(Person, lazy=False, backref='company', cascade="all, delete-orphan")
 })
 
 session = create_session()
diff --git a/examples/inheritance/single.py b/examples/inheritance/single.py
index 00feaefe8..29b214b20 100644
--- a/examples/inheritance/single.py
+++ b/examples/inheritance/single.py
@@ -1,5 +1,5 @@
 from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
-from sqlalchemy.orm import mapper, relation, create_session
+from sqlalchemy.orm import mapper, relationship, create_session
 
 metadata = MetaData('sqlite://')
 metadata.bind.echo = 'debug'
@@ -46,7 +46,7 @@ manager_mapper = mapper(Manager, inherits=person_mapper, polymorphic_identity='m
 engineer_mapper = mapper(Engineer, inherits=person_mapper, polymorphic_identity='engineer')
 
 mapper(Company, companies, properties={
-    'employees': relation(Person, lazy=True, backref='company')
+    'employees': relationship(Person, lazy=True, backref='company')
 })
 
 session = create_session()
diff --git a/examples/large_collection/__init__.py b/examples/large_collection/__init__.py
index a6c6179b8..3982f6799 100644
--- a/examples/large_collection/__init__.py
+++ b/examples/large_collection/__init__.py
@@ -1,8 +1,8 @@
 """Large collection example.
 
-Illustrates the options to use with :func:`~sqlalchemy.orm.relation()` when the list of related objects is very large, including:
+Illustrates the options to use with :func:`~sqlalchemy.orm.relationship()` when the list of related objects is very large, including:
 
-* "dynamic" relations which query slices of data as accessed
+* "dynamic" relationships which query slices of data as accessed
 * how to use ON DELETE CASCADE in conjunction with ``passive_deletes=True`` to greatly improve the performance of related collection deletion.
 
 """
diff --git a/examples/large_collection/large_collection.py b/examples/large_collection/large_collection.py
index c6adf1310..b8ade43ba 100644
--- a/examples/large_collection/large_collection.py
+++ b/examples/large_collection/large_collection.py
@@ -1,7 +1,7 @@
 
 from sqlalchemy import (MetaData, Table, Column, Integer, String, ForeignKey,
                         create_engine)
-from sqlalchemy.orm import (mapper, relation, sessionmaker)
+from sqlalchemy.orm import (mapper, relationship, sessionmaker)
 
 
 meta = MetaData()
@@ -27,7 +27,7 @@ class Member(object):
         self.name = name
 
 mapper(Organization, org_table, properties = {
-    'members' : relation(Member, 
+    'members' : relationship(Member, 
         # Organization.members will be a Query object - no loading
         # of the entire collection occurs unless requested
         lazy="dynamic", 
diff --git a/examples/poly_assoc/poly_assoc.py b/examples/poly_assoc/poly_assoc.py
index 6e09935cb..ecdc403e7 100644
--- a/examples/poly_assoc/poly_assoc.py
+++ b/examples/poly_assoc/poly_assoc.py
@@ -21,7 +21,7 @@ the associated target object from those which associate with it.
 """
 
 from sqlalchemy import MetaData, Table, Column, Integer, String, and_
-from sqlalchemy.orm import (mapper, relation, create_session, class_mapper,
+from sqlalchemy.orm import (mapper, relationship, create_session, class_mapper,
     backref)
 
 metadata = MetaData('sqlite://')
@@ -69,7 +69,7 @@ def addressable(cls, name, uselist=True):
             addresses.c.addressable_type == table.name
      )
     foreign_keys = [addresses.c.addressable_id]
-    mapper.add_property(name, relation(
+    mapper.add_property(name, relationship(
             Address,
             primaryjoin=primaryjoin, uselist=uselist, foreign_keys=foreign_keys,
             backref=backref('_backref_%s' % table.name, primaryjoin=list(table.primary_key)[0] == addresses.c.addressable_id, foreign_keys=foreign_keys)
diff --git a/examples/poly_assoc/poly_assoc_fk.py b/examples/poly_assoc/poly_assoc_fk.py
index f5dda2e39..96c9935c3 100644
--- a/examples/poly_assoc/poly_assoc_fk.py
+++ b/examples/poly_assoc/poly_assoc_fk.py
@@ -20,7 +20,7 @@ poly_assoc_generic.py.
 """
 
 from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
-from sqlalchemy.orm import mapper, relation, create_session, class_mapper
+from sqlalchemy.orm import mapper, relationship, create_session, class_mapper
 
 metadata = MetaData('sqlite://')
 
@@ -56,7 +56,7 @@ def addressable(cls, name, uselist=True):
     """
     mapper = class_mapper(cls)
     table = mapper.local_table
-    mapper.add_property('address_rel', relation(AddressAssoc, backref='_backref_%s' % table.name))
+    mapper.add_property('address_rel', relationship(AddressAssoc, backref='_backref_%s' % table.name))
 
     if uselist:
         # list based property decorator
@@ -78,7 +78,7 @@ def addressable(cls, name, uselist=True):
 mapper(Address, addresses)
 
 mapper(AddressAssoc, address_associations, properties={
-    'addresses':relation(Address, backref='association'),
+    'addresses':relationship(Address, backref='association'),
 })
 
 ######
diff --git a/examples/poly_assoc/poly_assoc_generic.py b/examples/poly_assoc/poly_assoc_generic.py
index 233df5195..235c21bec 100644
--- a/examples/poly_assoc/poly_assoc_generic.py
+++ b/examples/poly_assoc/poly_assoc_generic.py
@@ -7,7 +7,7 @@ function "association" which creates a new polymorphic association
 """
 
 from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
-from sqlalchemy.orm import mapper, relation, create_session, class_mapper
+from sqlalchemy.orm import mapper, relationship, create_session, class_mapper
 
 metadata = MetaData('sqlite://')
 
@@ -31,7 +31,7 @@ def association(cls, table):
 
         mapper = class_mapper(cls)
         table = mapper.local_table
-        mapper.add_property(attr_name, relation(GenericAssoc, backref='_backref_%s' % table.name))
+        mapper.add_property(attr_name, relationship(GenericAssoc, backref='_backref_%s' % table.name))
 
         if uselist:
             # list based property decorator
@@ -53,7 +53,7 @@ def association(cls, table):
     setattr(cls, 'member', property(lambda self: getattr(self.association, '_backref_%s' % self.association.type)))
 
     mapper(GenericAssoc, association_table, properties={
-        'targets':relation(cls, backref='association'),
+        'targets':relationship(cls, backref='association'),
     })
 
     return interface
diff --git a/examples/sharding/attribute_shard.py b/examples/sharding/attribute_shard.py
index 89d4243fc..352829cb6 100644
--- a/examples/sharding/attribute_shard.py
+++ b/examples/sharding/attribute_shard.py
@@ -2,7 +2,7 @@
 # step 1. imports
 from sqlalchemy import (create_engine, MetaData, Table, Column, Integer,
     String, ForeignKey, Float, DateTime)
-from sqlalchemy.orm import sessionmaker, mapper, relation
+from sqlalchemy.orm import sessionmaker, mapper, relationship
 from sqlalchemy.orm.shard import ShardedSession
 from sqlalchemy.sql import operators
 from sqlalchemy import sql
@@ -150,7 +150,7 @@ class Report(object):
 
 # step 7.  mappers
 mapper(WeatherLocation, weather_locations, properties={
-    'reports':relation(Report, backref='location')
+    'reports':relationship(Report, backref='location')
 })
 
 mapper(Report, weather_reports)    
diff --git a/examples/vertical/dictlike-polymorphic.py b/examples/vertical/dictlike-polymorphic.py
index a66576945..e4046b3ad 100644
--- a/examples/vertical/dictlike-polymorphic.py
+++ b/examples/vertical/dictlike-polymorphic.py
@@ -132,7 +132,7 @@ if __name__ == '__main__':
     from sqlalchemy import (MetaData, Table, Column, Integer, Unicode,
         ForeignKey, UnicodeText, and_, not_, or_, String, Boolean, cast, text,
         null, case)
-    from sqlalchemy.orm import mapper, relation, create_session
+    from sqlalchemy.orm import mapper, relationship, create_session
     from sqlalchemy.orm.collections import attribute_mapped_collection
 
     metadata = MetaData()
@@ -180,7 +180,7 @@ if __name__ == '__main__':
 
 
     mapper(Animal, animals, properties={
-        'facts': relation(
+        'facts': relationship(
             AnimalFact, backref='animal',
             collection_class=attribute_mapped_collection('key')),
         })
diff --git a/examples/vertical/dictlike.py b/examples/vertical/dictlike.py
index 683eda029..ce76b3140 100644
--- a/examples/vertical/dictlike.py
+++ b/examples/vertical/dictlike.py
@@ -59,7 +59,7 @@ class VerticalPropertyDictMixin(object):
 
     _property_mapping:
       A string, the name of the Python attribute holding a dict-based
-      relation of _property_type instances.
+      relationship of _property_type instances.
 
     Using the VerticalProperty class above as an example,::
 
@@ -68,10 +68,10 @@ class VerticalPropertyDictMixin(object):
           _property_mapping = 'props'
 
       mapper(MyObj, sometable, properties={
-        'props': relation(VerticalProperty,
+        'props': relationship(VerticalProperty,
                           collection_class=attribute_mapped_collection('key'))})
 
-    Dict-like access to MyObj is proxied through to the 'props' relation::
+    Dict-like access to MyObj is proxied through to the 'props' relationship::
 
       myobj['key'] = 'value'
       # ...is shorthand for:
@@ -125,7 +125,7 @@ class VerticalPropertyDictMixin(object):
 if __name__ == '__main__':
     from sqlalchemy import (MetaData, Table, Column, Integer, Unicode,
         ForeignKey, UnicodeText, and_, not_)
-    from sqlalchemy.orm import mapper, relation, create_session
+    from sqlalchemy.orm import mapper, relationship, create_session
     from sqlalchemy.orm.collections import attribute_mapped_collection
 
     metadata = MetaData()
@@ -166,7 +166,7 @@ if __name__ == '__main__':
 
 
     mapper(Animal, animals, properties={
-        'facts': relation(
+        'facts': relationship(
             AnimalFact, backref='animal',
             collection_class=attribute_mapped_collection('key')),
         })