Add docs for dependencies func

docs/model_helpers.rst

@@ -4,6 +4,12 @@ Model helpers
 .. module:: sqlalchemy_utils.functions
 
 
+dependencies
+^^^^^^^^^^^^
+
+.. autofunction:: dependencies
+
+
 escape_like
 ^^^^^^^^^^^
 

sqlalchemy_utils/__init__.py

@@ -8,6 +8,7 @@ from .functions import (
     create_mock_engine,
     database_exists,
     defer_except,
+    dependencies,
     drop_database,
     escape_like,
     get_columns,
@@ -74,6 +75,7 @@ __all__ = (
     create_mock_engine,
     database_exists,
     defer_except,
+    dependencies,
     drop_database,
     escape_like,
     force_auto_coercion,

sqlalchemy_utils/functions/__init__.py

@@ -12,6 +12,7 @@ from .database import (
     non_indexed_foreign_keys,
 )
 from .orm import (
+    dependencies,
     get_columns,
     get_declarative_base,
     get_primary_keys,

sqlalchemy_utils/functions/orm.py

@@ -27,6 +27,9 @@ def dependencies(obj, foreign_keys=None):
 
     ::
 
+        from sqlalchemy_utils import dependencies
+
+
         dependencies(user)
 
 
@@ -37,22 +40,29 @@ def dependencies(obj, foreign_keys=None):
         dependencies(user).limit(5)
 
 
-    The common use case is checking for all dependent objects before delete
-    operation occurs on parent object and inform the user if there are
-    dependent objects with ondelete='RESTRICT' foreign keys. This can be
-    achieved as follows::
+    The common use case is checking for all dependent objects before deleting
+    parent object and inform the user if there are dependent objects with
+    ondelete='RESTRICT' foreign keys. If this kind of checking is not used
+    it will lead to nasty IntegrityErrors being raised. This can be achieved
+    as follows::
 
 
-        dependencies(
-            user,
-            (
-                fk for fk in get_referencing_foreign_keys(obj)
-                # On most databases RESTRICT is the default mode hence we check
-                # for None values also
-                if fk.ondelete='RESTRICT' or fk.ondelete is None
-            )
+        deps = list(
+            dependencies(
+                user,
+                (
+                    fk for fk in get_referencing_foreign_keys(obj)
+                    # On most databases RESTRICT is the default mode hence we
+                    # check for None values also
+                    if fk.ondelete='RESTRICT' or fk.ondelete is None
+                )
+            ).limit(5)
         )
 
+        if deps:
+            # Do something to inform the user
+            pass
+
 
     :param obj: SQLAlchemy declarative model object
     :param foreign_keys: