document CircularDependencyError. [ticket:2285]

diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst
index 78fa6ee9c70fd00d8fc3b899fc96f75641cec82a..21fcf1648056e35d6dd0a5d418a69c70897813d3 100644 (file)
--- a/doc/build/core/schema.rst
+++ b/doc/build/core/schema.rst
@@ -925,6 +925,8 @@ would not be aware that these two values should be paired together - it would
 be two individual foreign key constraints instead of a single composite
 foreign key referencing two columns.
 
+.. _use_alter:
+
 Creating/Dropping Foreign Key Constraints via ALTER
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index fa46d0ba1f19e59a5d7bf9ec29b0200f05af1bf5..a506fc7f39b4173a008ff3e198f96279a84176db 100644 (file)
--- a/doc/build/orm/relationships.rst
+++ b/doc/build/orm/relationships.rst
@@ -966,6 +966,7 @@ to complement the ``boston_addresses`` attribute:
                     addresses_table.c.city=='New York')),
     })
 
+.. _post_update:
 
 Rows that point to themselves / Mutually Dependent Rows
 -------------------------------------------------------

diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py
index 0cc52fd25ca883c65a4967a5b2f71de2b22521e2..c76f68d2197529ac60acb99a7a023c145c685b7e 100644 (file)
--- a/lib/sqlalchemy/exc.py
+++ b/lib/sqlalchemy/exc.py
@@ -27,9 +27,24 @@ class ArgumentError(SQLAlchemyError):
 
 
 class CircularDependencyError(SQLAlchemyError):
-    """Raised by topological sorts when a circular dependency is detected"""
+    """Raised by topological sorts when a circular dependency is detected.
+    
+    There are two scenarios where this error occurs:
+    
+    * In a Session flush operation, if two objects are mutually dependent
+      on each other, they can not be inserted or deleted via INSERT or 
+      DELETE statements alone; an UPDATE will be needed to deassociate
+      one of the foreign key constraints first.  The ``post_update`` flag
+      described at :ref:`post_update` can resolve this cycle.
+    * In a :meth:`.MetaData.create_all`, :meth:`.MetaData.drop_all`,
+      :attr:`.MetaData.sorted_tables` operation, two :class:`.ForeignKey`
+      or :class:`.ForeignKeyConstraint` objects mutually refer to each
+      other.  Apply the ``use_alter=True`` flag to one or both,
+      see :ref:`use_alter`.
+      
+    """
     def __init__(self, message, cycles, edges):
-        message += ": cycles: %r all edges: %r" % (cycles, edges)
+        message += " Cycles: %r all edges: %r" % (cycles, edges)
         SQLAlchemyError.__init__(self, message)
         self.cycles = cycles
         self.edges = edges

diff --git a/lib/sqlalchemy/util/topological.py b/lib/sqlalchemy/util/topological.py
index ba68b713605c44c39a7891499f55e84a7c0d51f3..a5efa6388fb6103062c11781c99cfadd0aa9952f 100644 (file)
--- a/lib/sqlalchemy/util/topological.py
+++ b/lib/sqlalchemy/util/topological.py
@@ -28,7 +28,7 @@ def sort_as_subsets(tuples, allitems):
 
         if not output:
             raise CircularDependencyError(
-                    "Circular dependency detected",
+                    "Circular dependency detected.",
                     find_cycles(tuples, allitems), 
                     _gen_edges(edges)
                 )