diff options
| -rw-r--r-- | doc/build/orm/session.rst | 13 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/__init__.py | 17 |
2 files changed, 20 insertions, 10 deletions
diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index 1e77a2cec..a41d514f2 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -523,8 +523,8 @@ is extremely convenient. The solution here would usually be to not assign ``a1.user`` to an object already persistent in the target session. -Note that a new :func:`.relationship` option introduced in 0.6.5, -``cascade_backrefs=False``, will also prevent the ``Address`` from +The ``cascade_backrefs=False`` option of :func:`.relationship` +will also prevent the ``Address`` from being added to the session via the ``a1.user = u1`` assignment. Further detail on cascade operation is at :ref:`unitofwork_cascades`. @@ -942,7 +942,7 @@ is already present in a session will also be added to that same session. relationship()-based attribute, meaning that objects which were removed from a scalar or collection attribute whose changes have not yet been flushed are also placed into the new session - this so that foreign key clear operations -and deletions will take place (new in 0.6). +and deletions will take place. Note that the ``delete-orphan`` cascade only functions for relationships where the target object can have a single parent at a time, meaning it is only @@ -957,7 +957,10 @@ objects to allow attachment to only one parent at a time. The default value for ``cascade`` on :func:`~sqlalchemy.orm.relationship` is ``save-update, merge``. -``save-update`` cascade also takes place on backrefs by default. This means +Controlling Cascade on Backrefs +------------------------------- + +The ``save-update`` cascade takes place on backrefs by default. This means that, given a mapping such as this:: mapper(Order, order_table, properties={ @@ -981,7 +984,7 @@ place:: >>> i1 in session True -This behavior can be disabled as of 0.6.5 using the ``cascade_backrefs`` flag:: +This behavior can be disabled using the ``cascade_backrefs`` flag:: mapper(Order, order_table, properties={ 'items' : relationship(Item, backref='order', diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index ec4f39fdf..afb64d491 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -295,10 +295,13 @@ def relationship(argument, secondary=None, **kwargs): * ``delete`` - cascade the :meth:`.Session.delete` operation - * ``delete-orphan`` - if an item of the child's type with no - parent is detected, mark it for deletion. Note that this - option prevents a pending item of the child's class from being - persisted without a parent present. + * ``delete-orphan`` - if an item of the child's type is + detached from its parent, mark it for deletion. + As of version 0.7, this option does not prevent + a new instance of the child object from being persisted + without a parent to start with; to constrain against + that case, ensure the child's foreign key column(s) + is configured as NOT NULL * ``refresh-expire`` - cascade the :meth:`.Session.expire` and :meth:`~sqlalchemy.orm.session.Session.refresh` operations @@ -306,6 +309,9 @@ def relationship(argument, secondary=None, **kwargs): * ``all`` - shorthand for "save-update,merge, refresh-expire, expunge, delete" + See the section :ref:`unitofwork_cascades` for more background + on configuring cascades. + :param cascade_backrefs=True: a boolean value indicating if the ``save-update`` cascade should operate along an assignment event intercepted by a backref. @@ -332,7 +338,8 @@ def relationship(argument, secondary=None, **kwargs): ) }) - ``cascade_backrefs`` is new in 0.6.5. + See the section :ref:`unitofwork_cascades` for more background + on configuring cascades. :param collection_class: a class or callable that returns a new list-holding object. will |