Add 'factory.debug' context manager.

3 files changed, 35 insertions, 2 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 0367246..326b245 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -15,6 +15,7 @@ ChangeLog
 
     - The :class:`~factory.django.DjangoModelFactory` now supports the ``FACTORY_FOR = 'myapp.MyModel'``
       syntax, making it easier to shove all factories in a single module (:issue:`66`).
+    - Add :meth:`factory.debug()` helper for easier backtrace analysis
     - Adding factory support for mongoengine with :class:`~factory.mongoengine.MongoEngineFactory`.
 
 .. _v2.1.2:
diff --git a/docs/orms.rst b/docs/orms.rst
index 74c5c62..a463bfb 100644
--- a/docs/orms.rst
+++ b/docs/orms.rst
@@ -165,7 +165,7 @@ factory_boy supports `Mogo`_-style models, through the :class:`MogoFactory` clas
 
 
 MongoEngine
-----
+-----------
 
 .. currentmodule:: factory.mongoengine
 
@@ -173,7 +173,7 @@ factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngin
 
 `mongoengine`_ is a wrapper around the ``pymongo`` library for MongoDB.
 
-.. _mongoengine:: http://mongoengine.org/
+.. _mongoengine: http://mongoengine.org/
 
 .. class:: MongoEngineFactory(factory.Factory)
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 3d3097d..53584a0 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -363,6 +363,38 @@ factory_boy supports two main strategies for generating instances, plus stubs.
     with a default strategy set to :data:`STUB_STRATEGY`.
 
 
+.. function:: debug(logger='factory', stream=None)
+
+    :param str logger: The name of the logger to enable debug for
+    :param file stream: The stream to send debug output to, defaults to :obj:`sys.stderr`
+
+    Context manager to help debugging factory_boy behavior.
+    It will temporarily put the target logger (e.g ``'factory'``) in debug mode,
+    sending all output to :obj`~sys.stderr`;
+    upon leaving the context, the logging levels are reset.
+
+    A typical use case is to understand what happens during a single factory call:
+
+    .. code-block:: python
+
+        with factory.debug():
+            obj = TestModel2Factory()
+
+    This will yield messages similar to those (artificial indentation):
+
+    .. code-block:: ini
+
+        BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={})
+          LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>)
+            SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True
+            BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4})
+              LazyStub: Computing values for tests.test_using.TestModelFactory(one=4)
+              LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4)
+            BaseFactory: Generating tests.test_using.TestModelFactory(one=4)
+          LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
+        BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>)
+
+
 .. _declarations:
 
 Declarations