if anybody complains that they didn't know it was called "relation" in 0.5, why..I'll eat my hat !

5 files changed, 19 insertions, 5 deletions

diff --git a/doc/build/mappers.rst b/doc/build/mappers.rst
index ec1bb5e18..c6ae0c85d 100644
--- a/doc/build/mappers.rst
+++ b/doc/build/mappers.rst
@@ -895,7 +895,8 @@ Relationship Configuration
 Basic Relational Patterns
 --------------------------
 
-A quick walkthrough of the basic relational patterns.
+A quick walkthrough of the basic relational patterns.   Note that the :func:`~sqlalchemy.orm.relationship()` function is known as :func:`~sqlalchemy.orm.relation()`
+in all SQLAlchemy versions prior to 0.6beta2, including the 0.5 and 0.4 series.
 
 One To Many
 ~~~~~~~~~~~~
diff --git a/doc/build/ormtutorial.rst b/doc/build/ormtutorial.rst
index fae23486e..616adae00 100644
--- a/doc/build/ormtutorial.rst
+++ b/doc/build/ormtutorial.rst
@@ -700,6 +700,8 @@ Now let's consider a second table to be dealt with.  Users in our system also ca
 
 The above class introduces a **foreign key** constraint which references the ``users`` table.  This defines for SQLAlchemy the relationship between the two tables at the database level.  The relationship between the ``User`` and ``Address`` classes is defined separately using the :func:`~sqlalchemy.orm.relationship()` function, which defines an attribute ``user`` to be placed on the ``Address`` class, as well as an ``addresses`` collection to be placed on the ``User`` class.  Such a relationship is known as a **bidirectional** relationship.   Because of the placement of the foreign key, from ``Address`` to ``User`` it is **many to one**, and from ``User`` to ``Address`` it is **one to many**.  SQLAlchemy is automatically aware of many-to-one/one-to-many based on foreign keys.
 
+.. note:: The :func:`~sqlalchemy.orm.relationship()` function has historically been known as :func:`~sqlalchemy.orm.relation()`, which is the name that's available in all versions of SQLAlchemy prior to 0.6beta2, including the 0.5 and 0.4 series. :func:`~sqlalchemy.orm.relationship()` is only available starting with SQLAlchemy 0.6beta2.  :func:`~sqlalchemy.orm.relation()` will remain available in SQLAlchemy for the foreseeable future to enable cross-compatibility.
+
 The :func:`~sqlalchemy.orm.relationship()` function is extremely flexible, and could just have easily been defined on the ``User`` class:
 
 .. sourcecode:: python+sql
@@ -1068,7 +1070,7 @@ The :class:`~sqlalchemy.orm.query.Query` features several operators which make u
     {stop}[]
 
 Common Relationship Operators
--------------------------
+-----------------------------
 
 Here's all the operators which build on relationships:
 
diff --git a/doc/build/reference/orm/mapping.rst b/doc/build/reference/orm/mapping.rst
index e6d3a6666..b8842d8dc 100644
--- a/doc/build/reference/orm/mapping.rst
+++ b/doc/build/reference/orm/mapping.rst
@@ -38,6 +38,8 @@ call::
 
 .. autofunction:: dynamic_loader
 
+.. autofunction:: relation
+
 .. autofunction:: relationship
 
 .. autofunction:: synonym
diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index c6423e7a0..0f5518045 100644
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -100,8 +100,11 @@ Configuring Relationships
 =========================
 
 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``
+feature that the class specified to :func:`~sqlalchemy.orm.relationship`
+may be a string name (note that :func:`~sqlalchemy.orm.relationship` is 
+only available as of SQLAlchemy 0.6beta2, and in all prior versions is known
+as :func:`~sqlalchemy.orm.relation`, 
+including 0.5 and 0.4).  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
 configuration is used:: 
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 26cb071b7..3337287d8 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -175,7 +175,13 @@ def create_session(bind=None, **kwargs):
 
 def relationship(argument, secondary=None, **kwargs):
     """Provide a relationship of a primary Mapper to a secondary Mapper.
-
+    
+    .. note:: This function is known as :func:`relation` in all versions
+      of SQLAlchemy prior to version 0.6beta2, including the 0.5 and 0.4 series.
+      :func:`~sqlalchemy.orm.relationship()` is only available starting with 
+      SQLAlchemy 0.6beta2.  The :func:`relation` name will remain available for 
+      the foreseeable future in order to enable cross-compatibility.
+    
     This corresponds to a parent-child or associative table relationship.  The
     constructed class is an instance of :class:`RelationshipProperty`.