Add Factory.reset_sequence.

2 files changed, 44 insertions, 0 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index e820d8c..da3c4dc 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -13,6 +13,8 @@ ChangeLog
       fields defined in wrapping factories.
     - Move :class:`~factory.django.DjangoModelFactory` and :class:`~factory.mogo.MogoFactory`
       to their own modules (:mod:`factory.django` and :mod:`factory.mogo`)
+    - Add the :meth:`~factory.Factory.reset_sequence` classmethod to :class:`~factory.Factory`
+      to ease resetting the sequence counter for a given factory.
 
 *Deprecation:*
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 377feb1..a2d6c9a 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -234,6 +234,48 @@ The :class:`Factory` class
         values, for instance.
 
 
+    **Advanced functions:**
+
+
+    .. classmethod:: reset_sequence(cls, value=None, force=False)
+
+        :arg int value: The value to reset the sequence to
+        :arg bool force: Whether to force-reset the sequence
+
+        Allows to reset the sequence counter for a :class:`~factory.Factory`.
+        The new value can be passed in as the ``value`` argument:
+
+        .. code-block:: pycon
+
+            >>> SomeFactory.reset_sequence(4)
+            >>> SomeFactory._next_sequence
+            4
+
+        Since subclasses of a non-:attr:`abstract <factory.Factory.ABSTRACT_FACTORY>`
+        :class:`~factory.Factory` share the same sequence counter, special care needs
+        to be taken when resetting the counter of such a subclass.
+
+        By default, :meth:`reset_sequence` will raise a :exc:`ValueError` when
+        called on a subclassed :class:`~factory.Factory` subclass. This can be
+        avoided by passing in the ``force=True`` flag:
+
+        .. code-block:: pycon
+
+            >>> InheritedFactory.reset_sequence()
+            Traceback (most recent call last):
+              File "factory_boy/tests/test_base.py", line 179, in test_reset_sequence_subclass_parent
+                SubTestObjectFactory.reset_sequence()
+              File "factory_boy/factory/base.py", line 250, in reset_sequence
+                "Cannot reset the sequence of a factory subclass. "
+            ValueError: Cannot reset the sequence of a factory subclass. Please call reset_sequence() on the root factory, or call reset_sequence(forward=True).
+
+            >>> InheritedFactory.reset_sequence(force=True)
+            >>>
+
+        This is equivalent to calling :meth:`reset_sequence` on the base
+        factory in the chain.
+
+
 .. _strategies:
 
 Strategies