From a0af13067d952e05626f1ba240254cfcac58e9cc Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 26 Mar 2010 13:09:17 -0400 Subject: [PATCH] clarify cascade docstring, [ticket:1716] --- doc/build/session.rst | 2 +- lib/sqlalchemy/orm/__init__.py | 34 +++++++++++++++++++++------------- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/doc/build/session.rst b/doc/build/session.rst index 7bb0ae7e09..0731405b5e 100644 --- a/doc/build/session.rst +++ b/doc/build/session.rst @@ -393,7 +393,7 @@ Cascading is configured by setting the ``cascade`` keyword argument on a :func:` The above mapper specifies two relationships, ``items`` and ``customer``. The ``items`` relationship specifies "all, delete-orphan" as its ``cascade`` value, indicating that all ``add``, ``merge``, ``expunge``, ``refresh`` ``delete`` and ``expire`` operations performed on a parent ``Order`` instance should also be performed on the child ``Item`` instances attached to it. The ``delete-orphan`` cascade value additionally indicates that if an ``Item`` instance is no longer associated with an ``Order``, it should also be deleted. The "all, delete-orphan" cascade argument allows a so-called *lifecycle* relationship between an ``Order`` and an ``Item`` object. -The ``customer`` relationship specifies only the "save-update" cascade value, indicating most operations will not be cascaded from a parent ``Order`` instance to a child ``User`` instance except for the :func:`~sqlalchemy.orm.session.Session.add` operation. "save-update" cascade indicates that an :func:`~sqlalchemy.orm.session.Session.add` on the parent will cascade to all child items, and also that items added to a parent which is already present in the session will also be added. "save-update" cascade also cascades the *pending history* of a 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). +The ``customer`` relationship specifies only the "save-update" cascade value, indicating most operations will not be cascaded from a parent ``Order`` instance to a child ``User`` instance except for the :func:`~sqlalchemy.orm.session.Session.add` operation. "save-update" cascade indicates that an :func:`~sqlalchemy.orm.session.Session.add` on the parent will cascade to all child items, and also that items added to a parent which is already present in a session will also be added to that same session. "save-update" cascade also cascades the *pending history* of a 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). 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 appropriate for one-to-one or one-to-many relationships. For a :func:`~sqlalchemy.orm.relationship` which establishes one-to-one via a local foreign key, i.e. a many-to-one that stores only a single parent, or one-to-one/one-to-many via a "secondary" (association) table, a warning will be issued if ``delete-orphan`` is configured. To disable this warning, also specify the ``single_parent=True`` flag on the relationship, which constrains objects to allow attachment to only one parent at a time. diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 5d4bc2ee4f..2b577db878 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -230,25 +230,33 @@ def relationship(argument, secondary=None, **kwargs): Available cascades are: - ``save-update`` - cascade the "add()" operation (formerly - known as save() and update()) + * ``save-update`` - cascade the :meth:`~sqlalchemy.orm.session.Session.add` + operation. This cascade applies both to future and + past calls to :meth:`~sqlalchemy.orm.session.Session.add`, + meaning new items added to a collection or scalar relationship + get placed into the same session as that of the parent, and + also applies to items which have been removed from this + relationship but are still part of unflushed history. - ``merge`` - cascade the "merge()" operation + * ``merge`` - cascade the :meth:`~sqlalchemy.orm.session.Session.merge` + operation - ``expunge`` - cascade the "expunge()" operation + * ``expunge`` - cascade the :meth:`~sqlalchemy.orm.session.Session.expunge` + operation - ``delete`` - cascade the "delete()" operation + * ``delete`` - cascade the :meth:`~sqlalchemy.orm.session.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 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. - ``refresh-expire`` - cascade the expire() and refresh() - operations + * ``refresh-expire`` - cascade the :meth:`~sqlalchemy.orm.session.Session.expire` + and :meth:`~sqlalchemy.orm.session.Session.refresh` operations - ``all`` - shorthand for "save-update,merge, refresh-expire, - expunge, delete" + * ``all`` - shorthand for "save-update,merge, refresh-expire, + expunge, delete" :param collection_class: a class or callable that returns a new list-holding object. will -- 2.47.3