Commits

Mike Bayer committed 17ecf15

- cross link remote_side/self-referential
- trim off fn prefix on some relationship parameter names

  • Participants
  • Parent commits 28229a3

Comments (0)

Files changed (2)

doc/build/orm/relationships.rst

 exception that the "direction", i.e. whether the relationship
 is one-to-many or many-to-one, is assumed by default to
 be one-to-many.   To establish the relationship as many-to-one,
-an extra directive is added known as ``remote_side``, which
+an extra directive is added known as :paramref:`~.relationship.remote_side`, which
 is a :class:`.Column` or collection of :class:`.Column` objects
 that indicate those which should be considered to be "remote"::
 
         data = Column(String(50))
         parent = relationship("Node", remote_side=[id])
 
-Where above, the ``id`` column is applied as the ``remote_side``
+Where above, the ``id`` column is applied as the :paramref:`~.relationship.remote_side`
 of the ``parent`` :func:`.relationship`, thus establishing
 ``parent_id`` as the "local" side, and the relationship
 then behaves as a many-to-one.
                             remote_side=[account_id, folder_id]
                       )
 
-Above, we pass ``account_id`` into the ``remote_side`` list.
+Above, we pass ``account_id`` into the :paramref:`~.relationship.remote_side` list.
 :func:`.relationship` recognizes that the ``account_id`` column here
 is on both sides, and aligns the "remote" column along with the
 ``folder_id`` column, which it recognizes as uniquely present on
 is that it equates the value of primary key columns
 on one side to that of foreign-key-referring columns on the other.
 We can change this criterion to be anything we'd like using the
-:paramref:`.relationship.primaryjoin`
-argument, as well as the :paramref:`.relationship.secondaryjoin`
+:paramref:`~.relationship.primaryjoin`
+argument, as well as the :paramref:`~.relationship.secondaryjoin`
 argument in the case when a "secondary" table is used.
 
 In the example below, using the ``User`` class
 how it should load and persist data for this relationship.   However, the
 ``primaryjoin`` argument can be used to create a join condition that
 doesn't involve any "schema" level foreign keys.  We can combine ``primaryjoin``
-along with ``foreign_keys`` and ``remote_side`` explicitly in order to
+along with :paramref:`~.relationship.foreign_keys` and :paramref:`~.relationship.remote_side` explicitly in order to
 establish such a join.
 
 Below, a class ``HostEntry`` joins to itself, equating the string ``content``
 
     inet_column.op("<<")(cidr_column)
 
-However, if we construct a :paramref:`.relationship.primaryjoin` using this
+However, if we construct a :paramref:`~.relationship.primaryjoin` using this
 operator, :func:`.relationship` will still need more information.  This is because
 when it examines our primaryjoin condition, it specifically looks for operators
 used for **comparisons**, and this is typically a fixed list containing known
 comparison operators such as ``==``, ``<``, etc.   So for our custom operator
 to participate in this system, we need it to register as a comparison operator
-using the :paramref:`.Operators.op.is_comparison` parameter::
+using the :paramref:`~.Operators.op.is_comparison` parameter::
 
     inet_column.op("<<", is_comparison=True)(cidr_column)
 
 many of these exotic use cases needs to be hammered out on the SQLAlchemy mailing
 list.
 
-In more recent versions of SQLAlchemy, the :paramref:`.relationship.secondary`
+In more recent versions of SQLAlchemy, the :paramref:`~.relationship.secondary`
 parameter can be used in some of these cases in order to provide a composite
 target consisting of multiple tables.   Below is an example of such a
 join condition (requires version 0.9.2 at least to function as is)::
 
         id = Column(Integer, primary_key=True)
 
-In the above example, we provide all three of :paramref:`.relationship.secondary`,
-:paramref:`.relationship.primaryjoin`, and :paramref:`.relationship.secondaryjoin`,
+In the above example, we provide all three of :paramref:`~.relationship.secondary`,
+:paramref:`~.relationship.primaryjoin`, and :paramref:`~.relationship.secondaryjoin`,
 in the declarative style referring to the named tables ``a``, ``b``, ``c``, ``d``
 directly.  A query from ``A`` to ``D`` looks like:
 
 complexity is kept within the middle.
 
 .. versionadded:: 0.9.2  Support is improved for allowing a :func:`.join()`
-   construct to be used directly as the target of the :paramref:`.relationship.secondary`
+   construct to be used directly as the target of the :paramref:`~.relationship.secondary`
    argument, including support for joins, eager joins and lazy loading,
    as well as support within declarative to specify complex conditions such
    as joins involving class names as targets.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In the previous section, we illustrated a technique where we used
-:paramref:`.relationship.secondary` in order to place additional tables
+:paramref:`~.relationship.secondary` in order to place additional tables
 within a join condition.   There is one complex join case where even this technique is not
 sufficient; when we seek to join from ``A`` to ``B``, making use of any
 number of ``C``, ``D``, etc. in between, however there are also join conditions
 the relationship.  This is where we use :func:`.mapper` in order to make a mapping to
 a class that includes all the additional tables we need for this join.
 In order to produce this mapper as an "alternative" mapping for our class,
-we use the :paramref:`.mapper.non_primary` flag.
+we use the :paramref:`~.mapper.non_primary` flag.
 
 Below illustrates a :func:`.relationship` with a simple join from ``A`` to
 ``B``, however the primaryjoin condition is augmented with two additional

lib/sqlalchemy/orm/relationships.py

           used for self-referential relationships, indicates the column or
           list of columns that form the "remote side" of the relationship.
 
-          ``remote_side`` may also be passed as a callable function
+          :paramref:`.relationship.remote_side` may also be passed as a callable function
           which is evaluated at mapper initialization time, and may be passed as a
           Python-evaluable string when using Declarative.
 
               more specific system of describing which columns in a particular
               ``primaryjoin`` should be considered "remote".
 
+          .. seealso::
+
+            :ref:`self_referential` - in-depth explaination of how
+            :paramref:`.relationship.remote_side`
+            is used to configure self-referential relationships.
+
         :param query_class:
           a :class:`.Query` subclass that will be used as the base of the
           "appender query" returned by a "dynamic" relationship, that