diff options
Diffstat (limited to 'docs/reference.rst')
| -rw-r--r-- | docs/reference.rst | 146 |
1 files changed, 116 insertions, 30 deletions
diff --git a/docs/reference.rst b/docs/reference.rst index b0dda50..b5ccd16 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -42,7 +42,7 @@ The :class:`Factory` class It will be automatically set to ``True`` if neither the :class:`Factory` subclass nor its parents define the :attr:`~FactoryOptions.model` attribute. - .. warning:: This flag is reset to ``False`` When a :class:`Factory` subclasses + .. warning:: This flag is reset to ``False`` when a :class:`Factory` subclasses another one if a :attr:`~FactoryOptions.model` is set. .. versionadded:: 2.4.0 @@ -106,43 +106,36 @@ The :class:`Factory` class .. versionadded:: 2.4.0 - .. attribute:: strategy - - Use this attribute to change the strategy used by a :class:`Factory`. - The default is :data:`BUILD_STRATEGY`. - + .. attribute:: rename + Sometimes, a model expect a field with a name already used by one + of :class:`Factory`'s methods. -.. class:: Factory - - .. note:: In previous versions, the fields of :class:`class Meta <factory.FactoryOptions>` were - defined as class attributes on :class:`Factory`. This is now deprecated and will be removed - in 2.5.0. + In this case, the :attr:`rename` attributes allows to define renaming + rules: the keys of the :attr:`rename` dict are those used in the + :class:`Factory` declarations, and their values the new name: - .. attribute:: FACTORY_FOR + .. code-block:: python - .. deprecated:: 2.4.0 - See :attr:`FactoryOptions.model`. + class ImageFactory(factory.Factory): + # The model expects "attributes" + form_attributes = ['thumbnail', 'black-and-white'] - .. attribute:: ABSTRACT_FACTORY + class Meta: + model = Image + rename = {'form_attributes': 'attributes'} - .. deprecated:: 2.4.0 - See :attr:`FactoryOptions.abstract`. + .. versionadded: 2.6.0 - .. attribute:: FACTORY_ARG_PARAMETERS - .. deprecated:: 2.4.0 - See :attr:`FactoryOptions.inline_args`. + .. attribute:: strategy - .. attribute:: FACTORY_HIDDEN_ARGS + Use this attribute to change the strategy used by a :class:`Factory`. + The default is :data:`CREATE_STRATEGY`. - .. deprecated:: 2.4.0 - See :attr:`FactoryOptions.exclude`. - .. attribute:: FACTORY_STRATEGY - .. deprecated:: 2.4.0 - See :attr:`FactoryOptions.strategy`. +.. class:: Factory **Class-level attributes:** @@ -258,7 +251,6 @@ The :class:`Factory` class .. OHAI_VIM** - .. classmethod:: _setup_next_sequence(cls) This method will compute the first value to use for the sequence counter @@ -398,7 +390,7 @@ factory_boy supports two main strategies for generating instances, plus stubs. when using the ``create`` strategy. That policy will be used if the - :attr:`associated class <FactoryOptions.model` has an ``objects`` + :attr:`associated class <FactoryOptions.model>` has an ``objects`` attribute *and* the :meth:`~Factory._create` classmethod of the :class:`Factory` wasn't overridden. @@ -482,6 +474,83 @@ 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 + + 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 + + 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> + + .. classmethod:: add_provider(cls, locale=None) + + Some projects may need to fake fields beyond those provided by ``fake-factory``; + in such cases, use :meth:`factory.Faker.add_provider` to declare additional providers + for those fields: + + .. code-block:: python + + factory.Faker.add_provider(SmileyProvider) + + class FaceFactory(factory.Factory): + class Meta: + model = Face + + smiley = factory.Faker('smiley') + + LazyAttribute """"""""""""" @@ -565,7 +634,7 @@ This declaration takes a single argument, a function accepting a single paramete .. note:: An extra kwarg argument, ``type``, may be provided. - This feature is deprecated in 1.3.0 and will be removed in 2.0.0. + This feature was deprecated in 1.3.0 and will be removed in 2.0.0. .. code-block:: python @@ -1221,7 +1290,7 @@ For instance, a :class:`PostGeneration` hook is declared as ``post``: model = SomeObject @post_generation - def post(self, create, extracted, **kwargs): + def post(obj, create, extracted, **kwargs): obj.set_origin(create) .. OHAI_VIM** @@ -1343,6 +1412,23 @@ If a value if passed for the :class:`RelatedFactory` attribute, this disables 1 +.. note:: The target of the :class:`RelatedFactory` is evaluated *after* the initial factory has been instantiated. + This means that calls to :class:`factory.SelfAttribute` cannot go higher than this :class:`RelatedFactory`: + + .. code-block:: python + + class CountryFactory(factory.Factory): + class Meta: + model = Country + + lang = 'fr' + capital_city = factory.RelatedFactory(CityFactory, 'capital_of', + # factory.SelfAttribute('..lang') will crash, since the context of + # ``CountryFactory`` has already been evaluated. + main_lang=factory.SelfAttribute('capital_of.lang'), + ) + + PostGeneration """""""""""""" |