Allow overriding the sequence counter.

2 files changed, 32 insertions, 0 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 100952c..80074ae 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -14,6 +14,7 @@ ChangeLog
     - Add support for ``get_or_create`` in :class:`~factory.DjangoModelFactory`,
       through :attr:`~factory.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE`.
     - Add support for :mod:`~factory.fuzzy` attribute definitions.
+    - The :class:`Sequence` counter can be overridden when calling a generating function
 
 *Removed:*
 
diff --git a/docs/reference.rst b/docs/reference.rst
index a2af327..13220b0 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -502,6 +502,37 @@ sequence counter is shared:
     '123-555-0003'
 
 
+Forcing a sequence counter
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a specific value of the sequence counter is required for one instance, the
+``__sequence`` keyword argument should be passed to the factory method.
+
+This will force the sequence counter during the call, without altering the
+class-level value.
+
+.. code-block:: python
+
+    class UserFactory(factory.Factory):
+        FACTORY_FOR = User
+
+        uid = factory.Sequence(int)
+
+.. code-block:: pycon
+
+    >>> UserFactory()
+    <User: 0>
+    >>> UserFactory()
+    <User: 1>
+    >>> UserFactory(__sequence=42)
+    <User: 42>
+
+
+.. warning:: The impact of setting ``__sequence=n`` on a ``_batch`` call is
+             undefined. Each generated instance may share a same counter, or
+             use incremental values starting from the forced value.
+
+
 LazyAttributeSequence
 """""""""""""""""""""