Add factory.Faker()

This relies on the ``fake-factory`` library, and provides realistic
random values for most field types.

2 files changed, 62 insertions, 0 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index cd5d281..886db0b 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -9,6 +9,8 @@ ChangeLog
 *New:*
 
     - Add :attr:`factory.FactoryOptions.rename` to help handle conflicting names (:issue:`206`)
+    - Add support for random-yet-realistic values through `fake-factory <https://pypi.python.org/pypi/fake-factory>`_,
+      through the :class:`factory.Faker` class.
 
 .. _v2.5.2:
 
diff --git a/docs/reference.rst b/docs/reference.rst
index 0705ca2..a168de5 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -474,6 +474,66 @@ factory_boy supports two main strategies for generating instances, plus stubs.
 Declarations
 ------------
 
+
+Faker
+"""""
+
+.. class:: Faker(provider, locale=None, **kwargs)
+
+    .. OHAIVIM**
+
+    In order to easily define realistic-looking factories,
+    use the :class:`Faker` attribute declaration.
+
+    This is a wrapper around `fake-factory <https://pypi.python.org/pypi/fake-factory>`_;
+    its argument is the name of a ``fake-factory`` provider:
+
+    .. code-block:: python
+
+        class UserFactory(factory.Factory):
+            class Meta:
+                model = User
+
+            first_name = factory.Faker('name')
+
+    .. code-block:: pycon
+
+        >>> user = UserFactory()
+        >>> user.name
+        'Lucy Cechtelar'
+
+
+    .. attribute:: locale
+
+        If a custom locale is required for one specific field,
+        use the ``locale`` parameter:
+
+        .. code-block:: python
+
+            class UserFactory(factory.Factory):
+                class Meta:
+                    model = User
+
+                first_name = factory.Faker('name', locale='fr_FR')
+
+        .. code-block:: pycon
+
+            >>> user = UserFactory()
+            >>> user.name
+            'Jean Valjean'
+
+
+    .. classmethod:: override_default_locale(cls, locale)
+
+        If the locale needs to be overridden for a whole test,
+        use :meth:`~factory.Faker.override_default_locale`:
+
+        .. code-block:: pycon
+
+            >>> with factory.Faker.override_default_locale('de_DE'):
+            ...     UserFactory()
+            <User: Johannes Brahms>
+
 LazyAttribute
 """""""""""""