diff options
Diffstat (limited to 'doc/build/orm/backref.rst')
| -rw-r--r-- | doc/build/orm/backref.rst | 54 |
1 files changed, 27 insertions, 27 deletions
diff --git a/doc/build/orm/backref.rst b/doc/build/orm/backref.rst index b221e75e7..80b395930 100644 --- a/doc/build/orm/backref.rst +++ b/doc/build/orm/backref.rst @@ -3,7 +3,7 @@ Linking Relationships with Backref ---------------------------------- -The :paramref:`~.relationship.backref` keyword argument was first introduced in :ref:`ormtutorial_toplevel`, and has been +The :paramref:`_orm.relationship.backref` keyword argument was first introduced in :ref:`ormtutorial_toplevel`, and has been mentioned throughout many of the examples here. What does it actually do ? Let's start with the canonical ``User`` and ``Address`` scenario:: @@ -30,8 +30,8 @@ The above configuration establishes a collection of ``Address`` objects on ``Use ``User.addresses``. It also establishes a ``.user`` attribute on ``Address`` which will refer to the parent ``User`` object. -In fact, the :paramref:`~.relationship.backref` keyword is only a common shortcut for placing a second -:func:`.relationship` onto the ``Address`` mapping, including the establishment +In fact, the :paramref:`_orm.relationship.backref` keyword is only a common shortcut for placing a second +:func:`_orm.relationship` onto the ``Address`` mapping, including the establishment of an event listener on both sides which will mirror attribute operations in both directions. The above configuration is equivalent to:: @@ -57,7 +57,7 @@ in both directions. The above configuration is equivalent to:: user = relationship("User", back_populates="addresses") Above, we add a ``.user`` relationship to ``Address`` explicitly. On -both relationships, the :paramref:`~.relationship.back_populates` directive tells each relationship +both relationships, the :paramref:`_orm.relationship.back_populates` directive tells each relationship about the other one, indicating that they should establish "bidirectional" behavior between each other. The primary effect of this configuration is that the relationship adds event handlers to both attributes @@ -96,27 +96,27 @@ The manipulation of the ``.addresses`` collection and the ``.user`` attribute occurs entirely in Python without any interaction with the SQL database. Without this behavior, the proper state would be apparent on both sides once the data has been flushed to the database, and later reloaded after a commit or -expiration operation occurs. The :paramref:`~.relationship.backref`/:paramref:`~.relationship.back_populates` behavior has the advantage +expiration operation occurs. The :paramref:`_orm.relationship.backref`/:paramref:`_orm.relationship.back_populates` behavior has the advantage that common bidirectional operations can reflect the correct state without requiring a database round trip. -Remember, when the :paramref:`~.relationship.backref` keyword is used on a single relationship, it's +Remember, when the :paramref:`_orm.relationship.backref` keyword is used on a single relationship, it's exactly the same as if the above two relationships were created individually -using :paramref:`~.relationship.back_populates` on each. +using :paramref:`_orm.relationship.back_populates` on each. Backref Arguments ~~~~~~~~~~~~~~~~~ -We've established that the :paramref:`~.relationship.backref` keyword is merely a shortcut for building -two individual :func:`.relationship` constructs that refer to each other. Part of +We've established that the :paramref:`_orm.relationship.backref` keyword is merely a shortcut for building +two individual :func:`_orm.relationship` constructs that refer to each other. Part of the behavior of this shortcut is that certain configurational arguments applied to -the :func:`.relationship` +the :func:`_orm.relationship` will also be applied to the other direction - namely those arguments that describe the relationship at a schema level, and are unlikely to be different in the reverse direction. The usual case -here is a many-to-many :func:`.relationship` that has a :paramref:`~.relationship.secondary` argument, -or a one-to-many or many-to-one which has a :paramref:`~.relationship.primaryjoin` argument (the -:paramref:`~.relationship.primaryjoin` argument is discussed in :ref:`relationship_primaryjoin`). Such +here is a many-to-many :func:`_orm.relationship` that has a :paramref:`_orm.relationship.secondary` argument, +or a one-to-many or many-to-one which has a :paramref:`_orm.relationship.primaryjoin` argument (the +:paramref:`_orm.relationship.primaryjoin` argument is discussed in :ref:`relationship_primaryjoin`). Such as if we limited the list of ``Address`` objects to those which start with "tony":: from sqlalchemy import Integer, ForeignKey, String, Column @@ -154,18 +154,18 @@ of the relationship have this join condition applied:: This reuse of arguments should pretty much do the "right thing" - it uses only arguments that are applicable, and in the case of a many-to- many relationship, will reverse the usage of -:paramref:`~.relationship.primaryjoin` and -:paramref:`~.relationship.secondaryjoin` to correspond to the other +:paramref:`_orm.relationship.primaryjoin` and +:paramref:`_orm.relationship.secondaryjoin` to correspond to the other direction (see the example in :ref:`self_referential_many_to_many` for this). It's very often the case however that we'd like to specify arguments that are specific to just the side where we happened to place the -"backref". This includes :func:`.relationship` arguments like -:paramref:`~.relationship.lazy`, -:paramref:`~.relationship.remote_side`, -:paramref:`~.relationship.cascade` and -:paramref:`~.relationship.cascade_backrefs`. For this case we use +"backref". This includes :func:`_orm.relationship` arguments like +:paramref:`_orm.relationship.lazy`, +:paramref:`_orm.relationship.remote_side`, +:paramref:`_orm.relationship.cascade` and +:paramref:`_orm.relationship.cascade_backrefs`. For this case we use the :func:`.backref` function in place of a string:: # <other imports> @@ -183,7 +183,7 @@ Where above, we placed a ``lazy="joined"`` directive only on the ``Address.user` side, indicating that when a query against ``Address`` is made, a join to the ``User`` entity should be made automatically which will populate the ``.user`` attribute of each returned ``Address``. The :func:`.backref` function formatted the arguments we gave -it into a form that is interpreted by the receiving :func:`.relationship` as additional +it into a form that is interpreted by the receiving :func:`_orm.relationship` as additional arguments to be applied to the new relationship it creates. Setting cascade for backrefs @@ -221,7 +221,7 @@ operation which indicates that this ``Address`` should be placed into the :class:`.Session` as a :term:`pending` object. Since this behavior has been identified as counter-intuitive to most people, -it can be disabled by setting :paramref:`~.relationship.cascade_backrefs` +it can be disabled by setting :paramref:`_orm.relationship.cascade_backrefs` to False, as in:: @@ -243,7 +243,7 @@ One Way Backrefs An unusual case is that of the "one way backref". This is where the "back-populating" behavior of the backref is only desirable in one direction. An example of this is a collection which contains a -filtering :paramref:`~.relationship.primaryjoin` condition. We'd +filtering :paramref:`_orm.relationship.primaryjoin` condition. We'd like to append items to this collection as needed, and have them populate the "parent" object on the incoming object. However, we'd also like to have items that are not part of the collection, but still @@ -251,7 +251,7 @@ have the same "parent" association - these items should never be in the collection. Taking our previous example, where we established a -:paramref:`~.relationship.primaryjoin` that limited the collection +:paramref:`_orm.relationship.primaryjoin` that limited the collection only to ``Address`` objects whose email address started with the word ``tony``, the usual backref behavior is that all items populate in both directions. We wouldn't want this behavior for a case like the @@ -268,8 +268,8 @@ is present in the ``addresses`` collection of ``u1``. After these objects are the transaction committed and their attributes expired for a re-load, the ``addresses`` collection will hit the database on next access and no longer have this ``Address`` object present, due to the filtering condition. But we can do away with this unwanted side -of the "backref" behavior on the Python side by using two separate :func:`.relationship` constructs, -placing :paramref:`~.relationship.back_populates` only on one side:: +of the "backref" behavior on the Python side by using two separate :func:`_orm.relationship` constructs, +placing :paramref:`_orm.relationship.back_populates` only on one side:: from sqlalchemy import Integer, ForeignKey, String, Column from sqlalchemy.ext.declarative import declarative_base @@ -312,7 +312,7 @@ will not append the ``Address`` object to the collection:: False Of course, we've disabled some of the usefulness of -:paramref:`~.relationship.backref` here, in that when we do append an +:paramref:`_orm.relationship.backref` here, in that when we do append an ``Address`` that corresponds to the criteria of ``email.startswith('tony')``, it won't show up in the ``User.addresses`` collection until the session is flushed, and the |