From de6bcaf0bf91a32a3c756a2940ca6243062b67d1 Mon Sep 17 00:00:00 2001
From: Arthur Hamon <arthur@lumapps.com>
Date: Wed, 18 Nov 2020 14:07:55 +0100
Subject: [PATCH] Add documentation on how to use unique with faker.

---
 docs/changelog.rst |  1 +
 docs/reference.rst | 18 ++++++++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index a8588d4c..b38b3301 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -8,6 +8,7 @@ ChangeLog
 
     - Add support for Django 3.1
     - Add support for Python 3.9
+    - Add support for `unique` Faker feature
 
 *Removed:*
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 0c938693..74c94924 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -709,6 +709,24 @@ Faker
                 date_end=datetime.date(2020, 5, 31),
             )
 
+    Since Faker 4.9.0 version (see `Faker documentation <https://faker.readthedocs.io/en/master/fakerclass.html#unique-values>`_),
+    on every provider, you can specify whether to return an unique value or not:
+
+    .. code-block:: python
+
+        class UserFactory(fatory.Factory):
+            class Meta:
+                model = User
+
+            arrival = factory.Faker(
+                'date_between_dates',
+                date_start=datetime.date(2020, 1, 1),
+                date_end=datetime.date(2020, 5, 31),
+                unique=True  # The generated date is guaranteed to be unique inside the test execution.
+            )
+
+    Note that an `UniquenessException` will be thrown if Faker fails to generate an unique value.
+
     As with :class:`~factory.SubFactory`, the parameters can be any valid declaration.
     This does not apply to the provider name or the locale.