- 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]

4 files changed, 45 insertions, 45 deletions

diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py
index b63bd9b00..c7437d722 100644
--- a/lib/sqlalchemy/ext/associationproxy.py
+++ b/lib/sqlalchemy/ext/associationproxy.py
@@ -30,13 +30,13 @@ def association_proxy(target_collection, attr, **kw):
     always in sync with *target_collection*, and mutations made to either
     collection will be reflected in both.
 
-    Implements a Python property representing a relation as a collection of
+    Implements a Python property representing a relationship as a collection of
     simpler values.  The proxied property will mimic the collection type of
-    the target (list, dict or set), or, in the case of a one to one relation,
+    the target (list, dict or set), or, in the case of a one to one relationship,
     a simple scalar value.
 
-    :param target_collection: Name of the relation attribute we'll proxy to,
-      usually created with :func:`~sqlalchemy.orm.relation`.
+    :param target_collection: Name of the relationship attribute we'll proxy to,
+      usually created with :func:`~sqlalchemy.orm.relationship`.
 
     :param attr: Attribute on the associated instances we'll proxy for.
 
@@ -44,7 +44,7 @@ def association_proxy(target_collection, attr, **kw):
       by this proxy property would look like [getattr(obj1, *attr*),
       getattr(obj2, *attr*)]
 
-      If the relation is one-to-one or otherwise uselist=False, then simply:
+      If the relationship is one-to-one or otherwise uselist=False, then simply:
       getattr(obj, *attr*)
 
     :param creator: optional.
@@ -58,14 +58,14 @@ def association_proxy(target_collection, attr, **kw):
       If you want to construct instances differently, supply a *creator*
       function that takes arguments as above and returns instances.
 
-      For scalar relations, creator() will be called if the target is None.
+      For scalar relationships, creator() will be called if the target is None.
       If the target is present, set operations are proxied to setattr() on the
       associated object.
 
       If you have an associated object with multiple attributes, you may set
       up multiple association proxies mapping to different attributes.  See
       the unit tests for examples, and for examples of how creator() functions
-      can be used to construct the scalar relation on-demand in this
+      can be used to construct the scalar relationship on-demand in this
       situation.
 
     :param \*\*kw: Passes along any other keyword arguments to
@@ -84,7 +84,7 @@ class AssociationProxy(object):
 
         target_collection
           Name of the collection we'll proxy to, usually created with
-          'relation()' in a mapper setup.
+          'relationship()' in a mapper setup.
 
         attr
           Attribute on the collected instances we'll proxy for.  For example,
@@ -117,7 +117,7 @@ class AssociationProxy(object):
           sniffing the target collection.  If your collection type can't be
           determined by duck typing or you'd like to use a different
           collection implementation, you may supply a factory function to
-          produce those collections.  Only applicable to non-scalar relations.
+          produce those collections.  Only applicable to non-scalar relationships.
 
         proxy_bulk_set
           Optional, use with proxy_factory.  See the _set() method for
@@ -316,7 +316,7 @@ class _AssociationCollection(object):
 
         lazy_collection
           A callable returning a list-based collection of entities (usually an
-          object attribute managed by a SQLAlchemy relation())
+          object attribute managed by a SQLAlchemy relationship())
 
         creator
           A function that creates new target entities.  Given one parameter:
diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index fe45e6c17..c6423e7a0 100644
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -49,7 +49,7 @@ added to the underlying :class:`~sqlalchemy.schema.Table` and
 :func:`~sqlalchemy.orm.mapper()` definitions as appropriate::
 
     SomeClass.data = Column('data', Unicode)
-    SomeClass.related = relation(RelatedInfo)
+    SomeClass.related = relationship(RelatedInfo)
 
 Classes which are mapped explicitly using
 :func:`~sqlalchemy.orm.mapper()` can interact freely with declarative
@@ -96,11 +96,11 @@ objects::
     mymetadata = MetaData()
     Base = declarative_base(metadata=mymetadata)
 
-Configuring Relations
-=====================
+Configuring Relationships
+=========================
 
-Relations to other classes are done in the usual way, with the added
-feature that the class specified to :func:`~sqlalchemy.orm.relation()`
+Relationships to other classes are done in the usual way, with the added
+feature that the class specified to :func:`~sqlalchemy.orm.relationship()`
 may be a string name.  The "class registry" associated with ``Base``
 is used at mapper compilation time to resolve the name into the actual
 class object, which is expected to have been defined once the mapper
@@ -111,7 +111,7 @@ configuration is used::
 
         id = Column(Integer, primary_key=True)
         name = Column(String(50))
-        addresses = relation("Address", backref="user")
+        addresses = relationship("Address", backref="user")
 
     class Address(Base):
         __tablename__ = 'addresses'
@@ -130,9 +130,9 @@ class using them::
         id = Column(Integer, primary_key=True)
         email = Column(String(50))
         user_id = Column(Integer, ForeignKey('users.id'))
-        user = relation(User, primaryjoin=user_id == User.id)
+        user = relationship(User, primaryjoin=user_id == User.id)
 
-In addition to the main argument for :func:`~sqlalchemy.orm.relation`,
+In addition to the main argument for :func:`~sqlalchemy.orm.relationship`,
 other arguments which depend upon the columns present on an as-yet
 undefined class may also be specified as strings.  These strings are
 evaluated as Python expressions.  The full namespace available within
@@ -143,7 +143,7 @@ expression functions like :func:`~sqlalchemy.sql.expression.desc` and
 
     class User(Base):
         # ....
-        addresses = relation("Address",
+        addresses = relationship("Address",
                              order_by="desc(Address.email)", 
                              primaryjoin="Address.user_id==User.id")
 
@@ -151,14 +151,14 @@ As an alternative to string-based attributes, attributes may also be
 defined after all classes have been created.  Just add them to the target
 class after the fact::
 
-    User.addresses = relation(Address,
+    User.addresses = relationship(Address,
                               primaryjoin=Address.user_id==User.id)
 
-Configuring Many-to-Many Relations
-==================================
+Configuring Many-to-Many Relationships
+======================================
 
 There's nothing special about many-to-many with declarative.  The
-``secondary`` argument to :func:`~sqlalchemy.orm.relation` still
+``secondary`` argument to :func:`~sqlalchemy.orm.relationship` still
 requires a :class:`~sqlalchemy.schema.Table` object, not a declarative
 class. The :class:`~sqlalchemy.schema.Table` should share the same
 :class:`~sqlalchemy.schema.MetaData` object used by the declarative
@@ -173,10 +173,10 @@ base::
     class Author(Base):
         __tablename__ = 'authors'
         id = Column(Integer, primary_key=True)
-        keywords = relation("Keyword", secondary=keywords)
+        keywords = relationship("Keyword", secondary=keywords)
 
 You should generally **not** map a class and also specify its table in
-a many-to-many relation, since the ORM may issue duplicate INSERT and
+a many-to-many relationship, since the ORM may issue duplicate INSERT and
 DELETE statements. 
 
 
@@ -576,7 +576,7 @@ def _as_declarative(cls, classname, dict_):
             continue
         if not isinstance(value, (Column, MapperProperty)):
             continue
-        prop = _deferred_relation(cls, value)
+        prop = _deferred_relationship(cls, value)
         our_stuff[k] = prop
 
     # set up attributes in the order they were created
@@ -717,7 +717,7 @@ class DeclarativeMeta(type):
                         cls.__table__.append_column(col)
                 cls.__mapper__.add_property(key, value)
             elif isinstance(value, MapperProperty):
-                cls.__mapper__.add_property(key, _deferred_relation(cls, value))
+                cls.__mapper__.add_property(key, _deferred_relationship(cls, value))
             else:
                 type.__setattr__(cls, key, value)
         else:
@@ -740,7 +740,7 @@ class _GetColumns(object):
         return getattr(self.cls, key)
 
 
-def _deferred_relation(cls, prop):
+def _deferred_relationship(cls, prop):
     def resolve_arg(arg):
         import sqlalchemy
         
@@ -764,7 +764,7 @@ def _deferred_relation(cls, prop):
             except NameError, n:
                 raise exceptions.InvalidRequestError(
                     "When compiling mapper %s, expression %r failed to locate a name (%r). "
-                    "If this is a class name, consider adding this relation() to the %r "
+                    "If this is a class name, consider adding this relationship() to the %r "
                     "class after both dependent classes have been defined." % (
                     prop.parent, arg, n.args[0], cls))
         return return_cls
@@ -838,7 +838,7 @@ def _declarative_constructor(self, **kwargs):
 
     Only keys that are present as
     attributes of the instance's class are allowed. These could be,
-    for example, any mapped columns or relations.
+    for example, any mapped columns or relationships.
     """
     for k in kwargs:
         if not hasattr(type(self), k):
@@ -890,7 +890,7 @@ def declarative_base(bind=None, metadata=None, mapper=None, cls=object,
       Defaults to
       :func:`~sqlalchemy.ext.declarative._declarative_constructor`, an
       __init__ implementation that assigns \**kwargs for declared
-      fields and relations to an instance.  If ``None`` is supplied,
+      fields and relationships to an instance.  If ``None`` is supplied,
       no __init__ will be provided and construction will fall back to
       cls.__init__ by way of the normal Python semantics.
 
diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py
index 8e63ed1c2..db0bd2a4e 100644
--- a/lib/sqlalchemy/ext/orderinglist.py
+++ b/lib/sqlalchemy/ext/orderinglist.py
@@ -1,17 +1,17 @@
 """A custom list that manages index/position information for its children.
 
 ``orderinglist`` is a custom list collection implementation for mapped
-relations that keeps an arbitrary "position" attribute on contained objects in
+relationships that keeps an arbitrary "position" attribute on contained objects in
 sync with each object's position in the Python list.
 
 The collection acts just like a normal Python ``list``, with the added
 behavior that as you manipulate the list (via ``insert``, ``pop``, assignment,
 deletion, what have you), each of the objects it contains is updated as needed
-to reflect its position.  This is very useful for managing ordered relations
+to reflect its position.  This is very useful for managing ordered relationships
 which have a user-defined, serialized order::
 
   >>> from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
-  >>> from sqlalchemy.orm import mapper, relation
+  >>> from sqlalchemy.orm import mapper, relationship
   >>> from sqlalchemy.ext.orderinglist import ordering_list
 
 A simple model of users their "top 10" things::
@@ -32,7 +32,7 @@ A simple model of users their "top 10" things::
   ...        self.blurb = blurb
   ...
   >>> mapper(User, users, properties={
-  ...  'topten': relation(Blurb, collection_class=ordering_list('position'),
+  ...  'topten': relationship(Blurb, collection_class=ordering_list('position'),
   ...                     order_by=[blurbs.c.position])})
   <Mapper ...>
   >>> mapper(Blurb, blurbs)
@@ -73,7 +73,7 @@ __all__ = [ 'ordering_list' ]
 def ordering_list(attr, count_from=None, **kw):
     """Prepares an OrderingList factory for use in mapper definitions.
 
-    Returns an object suitable for use as an argument to a Mapper relation's
+    Returns an object suitable for use as an argument to a Mapper relationship's
     ``collection_class`` option.  Arguments are:
 
     attr
@@ -136,7 +136,7 @@ class OrderingList(list):
 
     See the module and __init__ documentation for more details.  The
     ``ordering_list`` factory function is used to configure ``OrderingList``
-    collections in ``mapper`` relation definitions.
+    collections in ``mapper`` relationship definitions.
 
     """
 
@@ -149,11 +149,11 @@ class OrderingList(list):
         mapped objects.
 
         This implementation relies on the list starting in the proper order,
-        so be **sure** to put an ``order_by`` on your relation.
+        so be **sure** to put an ``order_by`` on your relationship.
 
         ordering_attr
           Name of the attribute that stores the object's order in the
-          relation.
+          relationship.
 
         ordering_func
           Optional.  A function that maps the position in the Python list to a
diff --git a/lib/sqlalchemy/ext/sqlsoup.py b/lib/sqlalchemy/ext/sqlsoup.py
index 8b5d6bbc3..4d5f4b76f 100644
--- a/lib/sqlalchemy/ext/sqlsoup.py
+++ b/lib/sqlalchemy/ext/sqlsoup.py
@@ -170,10 +170,10 @@ You can also join directly to a labeled object::
     [u'name', u'email', u'password', u'classname', u'admin', u'loans_book_id', u'loans_user_name', u'loans_loan_date']
 
 
-Relations
-=========
+Relationships
+=============
 
-You can define relations on SqlSoup classes:
+You can define relationships on SqlSoup classes:
 
     >>> db.users.relate('loans', db.loans)
 
@@ -186,7 +186,7 @@ These can then be used like a normal SA property:
     [MappedUsers(name=u'Bhargan Basepair',email='basepair+nospam@example.edu',password=u'basepair',classname=None,admin=1)]
 
 
-relate can take any options that the relation function accepts in normal mapper definition:
+relate can take any options that the relationship function accepts in normal mapper definition:
 
     >>> del db._cache['users']
     >>> db.users.relate('loans', db.loans, order_by=db.loans.loan_date, cascade='all, delete-orphan')
@@ -308,7 +308,7 @@ from sqlalchemy import Table, MetaData, join
 from sqlalchemy import schema, sql
 from sqlalchemy.engine.base import Engine
 from sqlalchemy.orm import scoped_session, sessionmaker, mapper, \
-                            class_mapper, relation, session,\
+                            class_mapper, relationship, session,\
                             object_session
 from sqlalchemy.orm.interfaces import MapperExtension, EXT_CONTINUE
 from sqlalchemy.exceptions import SQLAlchemyError, InvalidRequestError, ArgumentError
@@ -373,7 +373,7 @@ class TableClassType(SelectableClassType):
         return o
 
     def relate(cls, propname, *args, **kwargs):
-        class_mapper(cls)._configure_property(propname, relation(*args, **kwargs))
+        class_mapper(cls)._configure_property(propname, relationship(*args, **kwargs))
 
 def _is_outer_join(selectable):
     if not isinstance(selectable, sql.Join):