From 50bea2e0e8d4ffa30e4f94ea21748e7ff57d0c0a Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 17 Mar 2010 20:49:41 -0400 Subject: [PATCH] if anybody complains that they didn't know it was called "relation" in 0.5, why..I'll eat my hat ! --- doc/build/mappers.rst | 3 ++- doc/build/ormtutorial.rst | 4 +++- doc/build/reference/orm/mapping.rst | 2 ++ lib/sqlalchemy/ext/declarative.py | 7 +++++-- lib/sqlalchemy/orm/__init__.py | 8 +++++++- 5 files changed, 19 insertions(+), 5 deletions(-) diff --git a/doc/build/mappers.rst b/doc/build/mappers.rst index ec1bb5e188..c6ae0c85dc 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 fae23486ea..616adae00b 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 e6d3a66669..b8842d8dc8 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 c6423e7a0d..0f55180451 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 26cb071b76..3337287d88 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`. -- 2.47.3