From 0ee3c9d6458d004c6229014e31f762f1e5d1b733 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= Date: Sun, 18 Aug 2024 21:36:17 +0200 Subject: [PATCH] Enable "nitpicky" mode on Sphinx And fix related missing references. Closes: #929 --- Makefile | 2 +- docs/changelog.rst | 102 +++++++++++++++++++++--------------------- docs/conf.py | 6 ++- docs/examples.rst | 2 +- docs/fuzzy.rst | 2 +- docs/ideas.rst | 2 +- docs/internals.rst | 8 ++-- docs/introduction.rst | 6 +-- docs/orms.rst | 53 +++++++++++----------- docs/recipes.rst | 8 ++-- docs/reference.rst | 93 ++++++++++++++++++++------------------ 11 files changed, 146 insertions(+), 138 deletions(-) diff --git a/Makefile b/Makefile index 778fd785..f7404eba 100644 --- a/Makefile +++ b/Makefile @@ -104,7 +104,7 @@ TAGS: # DOC: Compile the documentation doc: - $(MAKE) -C $(DOC_DIR) SPHINXOPTS=-W html + $(MAKE) -C $(DOC_DIR) SPHINXOPTS="-n -W" html linkcheck: $(MAKE) -C $(DOC_DIR) linkcheck diff --git a/docs/changelog.rst b/docs/changelog.rst index 9df2a88e..fd49f447 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -40,16 +40,15 @@ ChangeLog - Make :meth:`~factory.django.mute_signals` mute signals during post-generation. - - :issue:`775`: Change the signature for :meth:`~factory.alchemy.SQLAlchemyModelFactory._save` and - :meth:`~factory.alchemy.SQLAlchemyModelFactory._get_or_create` to avoid argument names clashes with a field named - ``session``. + - :issue:`775`: Change the signature for :class:`~factory.alchemy.SQLAlchemyModelFactory`'s ``_save`` and + ``_get_or_create`` methods to avoid argument names clashes with a field named ``session``. *Deprecated:* - :class:`~factory.django.DjangoModelFactory` will stop issuing a second call to :meth:`~django.db.models.Model.save` on the created instance when :ref:`post-generation-hooks` return a value. - To help with the transition, :class:`factory.django.DjangoModelFactory._after_postgeneration` raises a + To help with the transition, :class:`factory.django.DjangoModelFactory`'s ``_after_postgeneration`` raises a :class:`DeprecationWarning` when calling :meth:`~django.db.models.Model.save`. Inspect your :class:`~factory.django.DjangoModelFactory` subclasses: @@ -61,7 +60,7 @@ ChangeLog - call :meth:`django.db.models.Model.save` in the :class:`~factory.PostGeneration` hook that modifies the instance, or - - override :class:`~factory.django.DjangoModelFactory._after_postgeneration` to + - override the :class:`~factory.Factory._after_postgeneration` method to :meth:`~django.db.models.Model.save` the instance. *Removed:* @@ -82,9 +81,8 @@ ChangeLog - Do not override signals receivers registered in a :meth:`~factory.django.mute_signals` context. - - :issue:`775`: Change the signature for :meth:`~factory.alchemy.SQLAlchemyModelFactory._save` and - :meth:`~factory.alchemy.SQLAlchemyModelFactory._get_or_create` to avoid argument names clashes with a field named - ``session``. + - :issue:`775`: Change the signature for :class:`~factory.alchemy.SQLAlchemyModelFactory`'s ``_save`` and + ``_get_or_create`` methods to avoid argument names clashes with a field named ``session``. 3.2.0 (2020-12-28) ------------------ @@ -138,7 +136,7 @@ Breaking changes The following aliases were removed: -+------------------------------------------------+---------------------------------------------------+ ++================================================+===================================================+ | Broken alias | New import | +================================================+===================================================+ | ``from factory import DjangoModelFactory`` | ``from factory.django import DjangoModelFactory`` | @@ -150,7 +148,7 @@ The following aliases were removed: | ``from factory.fuzzy import set_random_state`` | ``from factory.random import set_random_state`` | +------------------------------------------------+---------------------------------------------------+ | ``from factory.fuzzy import reseed_random`` | ``from factory.random import reseed_random`` | -+------------------------------------------------+---------------------------------------------------+ ++================================================+===================================================+ *Removed:* @@ -167,14 +165,14 @@ The following aliases were removed: - Add support for Python 3.8 - Add support for Django 2.2 and 3.0 - - Report misconfiguration when a :py:class:`~factory.Factory` is used as the :py:attr:`~factory.Factory.model` for another :py:class:`~factory.Factory`. + - Report misconfiguration when a :py:class:`~factory.Factory` is used as the :py:attr:`~factory.FactoryOptions.model` for another :py:class:`~factory.Factory`. - Allow configuring the color palette of :py:class:`~factory.django.ImageField`. - - :py:meth:`get_random_state()` now represents the state of Faker and ``factory_boy`` fuzzy attributes. + - :py:meth:`~factory.random.get_random_state()` now represents the state of Faker and ``factory_boy`` fuzzy attributes. - Add SQLAlchemy ``get_or_create`` support *Improvements:* - - :issue:`561`: Display a developer-friendly error message when providing a model instead of a factory in a :class:`~factory.declarations.SubFactory` class. + - :issue:`561`: Display a developer-friendly error message when providing a model instead of a factory in a :class:`~factory.SubFactory` class. *Bug fix:* @@ -192,11 +190,11 @@ The following aliases were removed: - Add support for Python 3.7 - Add support for Django 2.1 - - Add :attr:`~factory.fuzzy.FuzzyChoice.getter` to :class:`~factory.fuzzy.FuzzyChoice` that mimics + - Add ``getter`` to :class:`~factory.fuzzy.FuzzyChoice` that mimics the behavior of ``getter`` in :class:`~factory.Iterator` - - Make the ``extra_kwargs`` parameter of :meth:`~factory.faker.Faker.generate` optional + - Make the ``extra_kwargs`` parameter of :class:`~factory.Faker`'s ``generate`` method optional - Add :class:`~factory.RelatedFactoryList` class for one-to-many support, thanks `Sean Harrington `_. - - Make the `locale` argument for :class:`~factory.faker.Faker` keyword-only + - Make the `locale` argument for :class:`~factory.Faker` keyword-only *Bug fix:* @@ -219,7 +217,7 @@ The following aliases were removed: - Fix :class:`~factory.fuzzy.FuzzyFloat` to return a 15 decimal digits precision float by default - :issue:`451`: Restore :class:`~factory.django.FileField` to a - :class:`~factory.declarations.ParameteredAttribute`, relying on composition to parse the provided parameters. + ``factory.declarations.ParameteredAttribute``, relying on composition to parse the provided parameters. - :issue:`389`: Fix random state management with ``faker``. - :issue:`466`: Restore mixing :class:`~factory.Trait` and :meth:`~factory.post_generation`. @@ -233,7 +231,7 @@ The following aliases were removed: *New:* - - :issue:`397`: Allow a :class:`factory.Maybe` to contain a :class:`~factory.PostGenerationDeclaration`. + - :issue:`397`: Allow a :class:`factory.Maybe` to contain a :class:`~factory.PostGeneration` declaration. This also applies to :class:`factory.Trait`, since they use a :class:`factory.Maybe` declaration internally. .. _v2.9.2: @@ -355,8 +353,8 @@ corner cases and weird behaviors. - :issue:`201`: Properly handle custom Django managers when dealing with abstract Django models. - :issue:`212`: Fix :meth:`factory.django.mute_signals` to handle Django's signal caching - - :issue:`228`: Don't load :func:`django.apps.apps.get_model()` until required - - :pr:`219`: Stop using :meth:`mogo.model.Model.new()`, deprecated 4 years ago. + - :issue:`228`: Don't load ``django.apps.apps.get_model()`` until required + - :pr:`219`: Stop using ``mogo.model.Model.new()``, deprecated 4 years ago. .. _v2.5.2: @@ -465,19 +463,19 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a For :class:`factory.Factory`: - * Rename :attr:`~factory.Factory.FACTORY_FOR` to :attr:`~factory.FactoryOptions.model` - * Rename :attr:`~factory.Factory.ABSTRACT_FACTORY` to :attr:`~factory.FactoryOptions.abstract` - * Rename :attr:`~factory.Factory.FACTORY_STRATEGY` to :attr:`~factory.FactoryOptions.strategy` - * Rename :attr:`~factory.Factory.FACTORY_ARG_PARAMETERS` to :attr:`~factory.FactoryOptions.inline_args` - * Rename :attr:`~factory.Factory.FACTORY_HIDDEN_ARGS` to :attr:`~factory.FactoryOptions.exclude` + * Rename ``factory.Factory.FACTORY_FOR`` to :attr:`~factory.FactoryOptions.model` + * Rename ``factory.Factory.ABSTRACT_FACTORY`` to :attr:`~factory.FactoryOptions.abstract` + * Rename ``factory.Factory.FACTORY_STRATEGY`` to :attr:`~factory.FactoryOptions.strategy` + * Rename ``factory.Factory.FACTORY_ARG_PARAMETERS`` to :attr:`~factory.FactoryOptions.inline_args` + * Rename ``factory.Factory.FACTORY_HIDDEN_ARGS`` to :attr:`~factory.FactoryOptions.exclude` For :class:`factory.django.DjangoModelFactory`: - * Rename :attr:`~factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE` to :attr:`~factory.django.DjangoOptions.django_get_or_create` + * Rename ``factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE`` to :attr:`~factory.django.DjangoOptions.django_get_or_create` For :class:`factory.alchemy.SQLAlchemyModelFactory`: - * Rename :attr:`~factory.alchemy.SQLAlchemyModelFactory.FACTORY_SESSION` to :attr:`~factory.alchemy.SQLAlchemyOptions.sqlalchemy_session` + * Rename ``factory.alchemy.SQLAlchemyModelFactory.FACTORY_SESSION`` to :attr:`~factory.alchemy.SQLAlchemyOptions.sqlalchemy_session` .. _v2.3.1: @@ -539,9 +537,9 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a *New:* - - The :class:`~factory.Factory.ABSTRACT_FACTORY` keyword is now optional, and automatically set + - The ``factory.Factory.ABSTRACT_FACTORY`` keyword is now optional, and automatically set to ``True`` if neither the :class:`~factory.Factory` subclass nor its parent declare the - :class:`~factory.Factory.FACTORY_FOR` attribute (:issue:`74`) + ``factory.Factory.FACTORY_FOR`` attribute (:issue:`74`) .. _v2.1.1: @@ -562,8 +560,8 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a - Add :class:`~factory.fuzzy.FuzzyDate` thanks to `saulshanabrook `_ - Add :class:`~factory.fuzzy.FuzzyDateTime` and :class:`~factory.fuzzy.FuzzyNaiveDateTime`. - - Add a :attr:`~factory.builder.Resolver.factory_parent` attribute to the - :class:`~factory.builder.Resolver` passed to :class:`~factory.LazyAttribute`, in order to access + - Add a ``factory_parent`` attribute to the + ``factory.builder.Resolver`` passed to :class:`~factory.LazyAttribute`, in order to access 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`) @@ -594,7 +592,7 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a *New:* - - When :attr:`~factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE` is + - When ``factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE`` is empty, use ``Model.objects.create()`` instead of ``Model.objects.get_or_create``. @@ -606,7 +604,7 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a *New:* - Don't push ``defaults`` to ``get_or_create`` when - :attr:`~factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE` is not set. + ``factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE`` is not set. .. _v2.0.0: @@ -618,11 +616,11 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a - Allow overriding the base factory class for :func:`~factory.make_factory` and friends. - Add support for Python3 (Thanks to `kmike `_ and `nkryptic `_) - - The default :attr:`~factory.Sequence.type` for :class:`~factory.Sequence` is now :obj:`int` - - Fields listed in :attr:`~factory.Factory.FACTORY_HIDDEN_ARGS` won't be passed to + - The default type for :class:`~factory.Sequence` is now :obj:`int` + - Fields listed in ``factory.Factory.FACTORY_HIDDEN_ARGS`` won't be passed to the associated class' constructor - Add support for ``get_or_create`` in :class:`~factory.django.DjangoModelFactory`, - through :attr:`~factory.django.DjangoModelFactory.FACTORY_DJANGO_GET_OR_CREATE`. + through ``factory.django.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 - Add :class:`~factory.Dict` and :class:`~factory.List` declarations (Closes :issue:`18`). @@ -630,12 +628,12 @@ This takes care of all ``FACTORY_FOR`` occurrences; the files containing other a *Removed:* - Remove associated class discovery - - Remove :class:`~factory.InfiniteIterator` and :func:`~factory.infinite_iterator` - - Remove :class:`~factory.CircularSubFactory` + - Remove ``factory.InfiniteIterator`` and ``factory.infinite_iterator`` + - Remove ``factory.CircularSubFactory`` - Remove ``extract_prefix`` kwarg to post-generation hooks. - Stop defaulting to Django's ``Foo.objects.create()`` when "creating" instances - Remove STRATEGY_* - - Remove :meth:`~factory.Factory.set_building_function` / :meth:`~factory.Factory.set_creation_function` + - Remove ``factory.Factory.set_building_function`` / ``factory.Factory.set_creation_function`` .. _v1.3.0: @@ -659,8 +657,8 @@ New - **The Factory class:** - Better creation/building customization hooks at :meth:`factory.Factory._build` and :meth:`factory.Factory.create` - Add support for passing non-kwarg parameters to a :class:`~factory.Factory` - wrapped class through :attr:`~factory.Factory.FACTORY_ARG_PARAMETERS`. - - Keep the :attr:`~factory.Factory.FACTORY_FOR` attribute in :class:`~factory.Factory` classes + wrapped class through ``FACTORY_ARG_PARAMETERS``. + - Keep the ``FACTORY_FOR`` attribute in :class:`~factory.Factory` classes - **Declarations:** - Allow :class:`~factory.SubFactory` to solve circular dependencies between factories @@ -681,14 +679,14 @@ Pending deprecation The following features have been deprecated and will be removed in an upcoming release. - **Declarations:** - - :class:`~factory.InfiniteIterator` is deprecated in favor of :class:`~factory.Iterator` - - :class:`~factory.CircularSubFactory` is deprecated in favor of :class:`~factory.SubFactory` + - ``factory.InfiniteIterator`` is deprecated in favor of :class:`~factory.Iterator` + - ``factory.CircularSubFactory`` is deprecated in favor of :class:`~factory.SubFactory` - The ``extract_prefix`` argument to :meth:`~factory.post_generation` is now deprecated - **Factory:** - - Usage of :meth:`~factory.Factory.set_creation_function` and :meth:`~factory.Factory.set_building_function` + - Usage of ``factory.Factory.set_creation_function`` and ``factory.Factory.set_building_function`` are now deprecated - - Implicit associated class discovery is no longer supported, you must set the :attr:`~factory.Factory.FACTORY_FOR` + - Implicit associated class discovery is no longer supported, you must set the ``FACTORY_FOR`` attribute on all :class:`~factory.Factory` subclasses @@ -725,7 +723,7 @@ In order to upgrade client code, apply the following rules: *New:* - - Add :class:`~factory.CircularSubFactory` to solve circular dependencies between factories + - Add ``factory.CircularSubFactory`` to solve circular dependencies between factories .. _v1.1.5: @@ -735,7 +733,7 @@ In order to upgrade client code, apply the following rules: *Bug fix:* - - Fix :class:`~factory.PostGenerationDeclaration` and derived classes. + - Fix ``factory.PostGenerationDeclaration`` and derived classes. .. _v1.1.4: @@ -769,7 +767,7 @@ In order to upgrade client code, apply the following rules: *New:* - - Add :class:`~factory.Iterator` and :class:`~factory.InfiniteIterator` for :class:`~factory.Factory` attribute declarations. + - Add :class:`~factory.Iterator` and ``factory.InfiniteIterator`` for :class:`~factory.Factory` attribute declarations. - Provide :func:`~factory.Factory.generate` and :func:`~factory.Factory.simple_generate`, that allow specifying the instantiation strategy directly. Also provides :func:`~factory.Factory.generate_batch` and :func:`~factory.Factory.simple_generate_batch`. @@ -792,7 +790,7 @@ In order to upgrade client code, apply the following rules: *New:* - Improve the :class:`~factory.SelfAttribute` syntax to fetch sub-attributes using the ``foo.bar`` syntax; - - Add :class:`~factory.ContainerAttribute` to fetch attributes from the container of a :class:`~factory.SubFactory`. + - Add ``factory.ContainerAttribute`` to fetch attributes from the container of a :class:`~factory.SubFactory`. - Provide the :func:`~factory.make_factory` helper: ``MyClassFactory = make_factory(MyClass, x=3, y=4)`` - Add :func:`~factory.build`, :func:`~factory.create`, :func:`~factory.stub` helpers @@ -802,7 +800,7 @@ In order to upgrade client code, apply the following rules: *Deprecation:* - - Auto-discovery of :attr:`~factory.Factory.FACTORY_FOR` based on class name is now deprecated + - Auto-discovery of ``factory.Factory.FACTORY_FOR`` based on class name is now deprecated .. _v1.0.4: @@ -815,9 +813,9 @@ In order to upgrade client code, apply the following rules: - Improve the algorithm for populating a :class:`~factory.Factory` attributes dict - Add ``python setup.py test`` command to run the test suite - Allow custom build functions - - Introduce :data:`~factory.MOGO_BUILD` build function + - Introduce ``factory.MOGO_BUILD`` build function - Add support for inheriting from multiple :class:`~factory.Factory` - - Base :class:`~factory.Factory` classes can now be declared :attr:`abstract `. + - Base :class:`~factory.Factory` classes can now be declared abstract through ``factory.Factory.ABSTRACT_FACTORY``. - Provide :class:`~factory.django.DjangoModelFactory`, whose :class:`~factory.Sequence` counter starts at the next free database id - Introduce :class:`~factory.SelfAttribute`, a shortcut for ``factory.LazyAttribute(lambda o: o.foo.bar.baz``. diff --git a/docs/conf.py b/docs/conf.py index 876a1c49..dc4a3863 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,7 +21,7 @@ project = 'Factory Boy' copyright = '2011-2015, Raphaël Barrois, Mark Sandstrom' -author = 'adfasf' +author = 'Raphaël Barrois, Mark Sandstrom' # The full version, including alpha/beta/rc tags release = factory.__version__ @@ -84,6 +84,10 @@ 'https://docs.djangoproject.com/en/dev/', 'https://docs.djangoproject.com/en/dev/_objects/', ), + 'mongoengine': ( + 'https://mongoengine-odm.readthedocs.io/', + None, + ), 'sqlalchemy': ( 'https://docs.sqlalchemy.org/en/latest/', 'https://docs.sqlalchemy.org/en/latest/objects.inv', diff --git a/docs/examples.rst b/docs/examples.rst index 7d868f8c..bd27af6a 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -76,7 +76,7 @@ And now, we'll define the related factories: -We have now defined basic factories for our :class:`~Account` and :class:`~Profile` classes. +We have now defined basic factories for our ``Account`` and ``Profile`` classes. If we commonly use a specific variant of our objects, we can refine a factory accordingly: diff --git a/docs/fuzzy.rst b/docs/fuzzy.rst index ca251656..bef86778 100644 --- a/docs/fuzzy.rst +++ b/docs/fuzzy.rst @@ -354,4 +354,4 @@ They should inherit from the :class:`BaseFuzzyAttribute` class, and override its Custom :class:`BaseFuzzyAttribute` subclasses **MUST** use :obj:`factory.random.randgen` as a randomness source; this ensures that data they generate can be regenerated using the simple state from - :meth:`get_random_state`. + :meth:`factory.random.get_random_state`. diff --git a/docs/ideas.rst b/docs/ideas.rst index 6e3962d4..b9f3691b 100644 --- a/docs/ideas.rst +++ b/docs/ideas.rst @@ -4,6 +4,6 @@ Ideas This is a list of future features that may be incorporated into factory_boy: -* When a :class:`Factory` is built or created, pass the calling context throughout the calling chain instead of custom solutions everywhere +* When a :class:`~factory.Factory` is built or created, pass the calling context throughout the calling chain instead of custom solutions everywhere * Define a proper set of rules for the support of third-party ORMs * Properly evaluate nested declarations (e.g ``factory.fuzzy.FuzzyDate(start_date=factory.SelfAttribute('since'))``) diff --git a/docs/internals.rst b/docs/internals.rst index d71afbec..62ca3fed 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -57,11 +57,11 @@ First, decide the strategy: use the strategy defined at the :attr:`class Meta ` level -Then, we'll pass the strategy and passed-in overrides to the :meth:`~Factory._generate` method. +Then, we'll pass the strategy and passed-in overrides to the ``Factory._generate`` method. -.. note:: According to the project road map, a future version will use a :meth:`~Factory._generate_batch` at its core instead. +.. note:: According to the project road map, a future version will use a ``Factory._generate_batch`` at its core instead. -A factory's :meth:`~Factory._generate` function actually delegates to a ``StepBuilder()`` object. +A factory's ``Factory._generate`` function actually delegates to a ``StepBuilder()`` object. This object will carry the overall "build an object" context (strategy, depth, and possibly other). @@ -81,7 +81,7 @@ Instantiating, Step 3: Building the object 1. The ``StepBuilder`` fetches the attributes computed by the ``Resolver``. 2. It applies renaming/adjustment rules -3. It passes them to the :meth:`FactoryOptions.instantiate` method, which +3. It passes them to the ``FactoryOptions.instantiate`` method, which forwards to the proper methods. 4. Post-declaration are applied (in declaration order) diff --git a/docs/introduction.rst b/docs/introduction.rst index e9ad3248..d3b169a0 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -112,7 +112,7 @@ This is achieved with the :class:`~factory.Sequence` declaration: >>> UserFactory() -.. note:: For more complex situations, you may also use the :meth:`~factory.@sequence` decorator (note that ``self`` is not added as first parameter): +.. note:: For more complex situations, you may also use the :meth:`@factory.sequence ` decorator (note that ``self`` is not added as first parameter): .. code-block:: python @@ -152,7 +152,7 @@ argument and returning the value for the field: .. note:: For complex cases when you happen to write a specific function, - the :meth:`~factory.@lazy_attribute` decorator should be more appropriate. + the :meth:`@factory.lazy_attribute ` decorator should be more appropriate. LazyAttribute @@ -185,7 +185,7 @@ taking the object being built and returning the value for the field: -.. note:: As for :class:`~factory.Sequence`, a :meth:`~factory.@lazy_attribute` decorator is available: +.. note:: As for :class:`~factory.Sequence`, a :meth:`@factory.lazy_attribute ` decorator is available: .. code-block:: python diff --git a/docs/orms.rst b/docs/orms.rst index 5967e1bc..7f9d1ef0 100644 --- a/docs/orms.rst +++ b/docs/orms.rst @@ -13,7 +13,7 @@ adding dedicated features. Django ------ -.. currentmodule:: factory.django +.. module:: factory.django The first versions of factory_boy were designed specifically for Django, @@ -111,11 +111,10 @@ All factories for a Django :class:`~django.db.models.Model` should use the .. attribute:: skip_postgeneration_save - Transitional option to prevent - :meth:`~factory.django.DjangoModelFactory._after_postgeneration` from - issuing a duplicate call to :meth:`~django.db.models.Model.save` on the - created instance when :class:`factory.PostGeneration` hooks return a - value. + Transitional option to prevent :class:`~factory.django.DjangoModelFactory`'s + ``_after_postgeneration`` from issuing a duplicate call to + :meth:`~django.db.models.Model.save` on the created instance when + :class:`factory.PostGeneration` hooks return a value. Extra fields @@ -167,9 +166,9 @@ Extra fields :param str from_path: Use data from the file located at ``from_path``, and keep its filename - :param file from_file: Use the contents of the provided file object; use its filename + :param io.BytesIO from_file: Use the contents of the provided file object; use its filename if available, unless ``filename`` is also provided. - :param func from_func: Use function that returns a file object + :param Callable from_func: Use function that returns a file object :param bytes data: Use the provided bytes as file contents :param str filename: The filename for the FileField @@ -200,9 +199,9 @@ Extra fields :param str from_path: Use data from the file located at ``from_path``, and keep its filename - :param file from_file: Use the contents of the provided file object; use its filename + :param io.BytesIO from_file: Use the contents of the provided file object; use its filename if available - :param func from_func: Use function that returns a file object + :param Callable from_func: Use function that returns a file object :param str filename: The filename for the ImageField :param int width: The width of the generated image (default: ``100``) :param int height: The height of the generated image (default: ``100``) @@ -272,7 +271,7 @@ To work around this problem, use the :meth:`mute_signals()` decorator/context ma Mogo ---- -.. currentmodule:: factory.mogo +.. module:: factory.mogo factory_boy supports `Mogo`_-style models, through the :class:`MogoFactory` class. @@ -294,7 +293,7 @@ factory_boy supports `Mogo`_-style models, through the :class:`MogoFactory` clas MongoEngine ----------- -.. currentmodule:: factory.mongoengine +.. module:: factory.mongoengine factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngineFactory` class. @@ -312,8 +311,8 @@ factory_boy supports `MongoEngine`_-style models, through the :class:`MongoEngin * :func:`~factory.Factory.create()` builds an instance through ``__init__`` then saves it. - .. note:: If the :attr:`associated class ` is a :class:`mongoengine.EmbeddedDocument`, + the :class:`~MongoEngineFactory`'s ``create`` function won't "save" it, since this wouldn't make sense. This feature makes it possible to use :class:`~factory.SubFactory` to create embedded document. @@ -349,7 +348,7 @@ A minimalist example: SQLAlchemy ---------- -.. currentmodule:: factory.alchemy +.. module:: factory.alchemy Factory_boy also supports `SQLAlchemy`_ models through the :class:`SQLAlchemyModelFactory` class. @@ -364,12 +363,12 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr: This class provides the following features: - * :func:`~factory.Factory.create()` uses :meth:`sqlalchemy.orm.session.Session.add` + * :func:`~factory.Factory.create()` uses :meth:`sqlalchemy.orm.Session.add` .. class:: SQLAlchemyOptions(factory.base.FactoryOptions) - In addition to the usual parameters available in :class:`class Meta `, + In addition to the usual parameters available in :class:`class Meta `, a :class:`SQLAlchemyModelFactory` also supports the following settings: .. attribute:: sqlalchemy_session @@ -403,8 +402,8 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr: Valid values are: * ``None``: do nothing - * ``'flush'``: perform a session :meth:`~sqlalchemy.orm.session.Session.flush` - * ``'commit'``: perform a session :meth:`~sqlalchemy.orm.session.Session.commit` + * ``'flush'``: perform a session :meth:`~sqlalchemy.orm.Session.flush` + * ``'commit'``: perform a session :meth:`~sqlalchemy.orm.Session.commit` The default value is ``None``. @@ -413,8 +412,8 @@ To work, this class needs an `SQLAlchemy`_ session object affected to the :attr: .. versionadded:: 3.0.0 Fields whose name are passed in this list will be used to perform a - :meth:`Model.query.one_or_none() ` - or the usual :meth:`Session.add() `: + :meth:`Model.query.one_or_none() ` + or the usual :meth:`Session.add() `: .. code-block:: python @@ -516,15 +515,15 @@ there is no "global" session management system. The most common pattern when working with unit tests and ``factory_boy`` is to use `SQLAlchemy`_'s :class:`sqlalchemy.orm.scoping.scoped_session`: -* The test runner configures some project-wide :class:`~sqlalchemy.orm.scoping.scoped_session` +* The test runner configures some project-wide :class:`~sqlalchemy.orm.scoped_session` * Each :class:`~SQLAlchemyModelFactory` subclass uses this - :class:`~sqlalchemy.orm.scoping.scoped_session` as its :attr:`~SQLAlchemyOptions.sqlalchemy_session` + :class:`~sqlalchemy.orm.scoped_session` as its :attr:`~SQLAlchemyOptions.sqlalchemy_session` * The :meth:`~unittest.TestCase.tearDown` method of tests calls - :meth:`Session.remove ` + :meth:`Session.remove ` to reset the session. .. note:: See the excellent :ref:`SQLAlchemy guide on scoped_session ` - for details of :class:`~sqlalchemy.orm.scoping.scoped_session`'s usage. + for details of :class:`~sqlalchemy.orm.scoped_session`'s usage. The basic idea is that declarative parts of the code (including factories) need a simple way to access the "current session", @@ -536,7 +535,7 @@ is to use `SQLAlchemy`_'s :class:`sqlalchemy.orm.scoping.scoped_session`: Here is an example layout: -- A global (test-only?) file holds the :class:`~sqlalchemy.orm.scoping.scoped_session`: +- A global (test-only?) file holds the :class:`~sqlalchemy.orm.scoped_session`: .. code-block:: python @@ -568,7 +567,7 @@ Here is an example layout: name = factory.Sequence(lambda n: "User %d" % n) -- The test runner configures the :class:`~sqlalchemy.orm.scoping.scoped_session` when it starts: +- The test runner configures the :class:`~sqlalchemy.orm.scoped_session` when it starts: .. code-block:: python diff --git a/docs/recipes.rst b/docs/recipes.rst index a1717ad5..457bcf9c 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -89,7 +89,7 @@ use a :class:`~factory.RelatedFactory` declaration: ) -When a :class:`UserFactory` is instantiated, factory_boy will call +When a ``UserFactory`` is instantiated, factory_boy will call ``UserLogFactory(user=that_user, action=...)`` just before returning the created ``User``. @@ -101,7 +101,7 @@ using a :class:`~django.db.models.OneToOneField` from the ``Profile`` to the ``U A typical way to create those profiles was to hook a post-save signal to the ``User`` model. -Prior to version 2.9, the solution to this was to override the :meth:`~factory.Factory._generate` method on the factory. +Prior to version 2.9, the solution to this was to override the ``factory.Factory._generate`` method on the factory. Since version 2.9, the :meth:`~factory.django.mute_signals` decorator should be used: @@ -216,8 +216,8 @@ Many-to-many relation with a 'through' -------------------------------------- -If only one link is required, this can be simply performed with a :class:`RelatedFactory`. -If more links are needed, simply add more :class:`RelatedFactory` declarations: +If only one link is required, this can be simply performed with a :class:`~factory.RelatedFactory`. +If more links are needed, simply add more :class:`~factory.RelatedFactory` declarations: .. code-block:: python diff --git a/docs/reference.rst b/docs/reference.rst index 130e194c..2122b9f7 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -1,7 +1,7 @@ Reference ========= -.. currentmodule:: factory +.. module:: factory This section offers an in-depth description of factory_boy features. @@ -181,17 +181,19 @@ Attributes and methods **Base functions:** - The :class:`Factory` class provides a few methods for getting objects; - the usual way being to simply call the class: + .. classmethod:: __call__(**kwargs) - .. code-block:: pycon + The :class:`Factory` class provides a few methods for getting objects; + the usual way being to simply call the class: + + .. code-block:: pycon - >>> UserFactory() # Calls UserFactory.create() - >>> UserFactory(login='john') # Calls UserFactory.create(login='john') + >>> UserFactory() # Calls UserFactory.create() + >>> UserFactory(login='john') # Calls UserFactory.create(login='john') - Under the hood, factory_boy will define the :class:`Factory` - :meth:`~object.__new__` method to call the default :ref:`strategy ` - of the :class:`Factory`. + Under the hood, factory_boy will define the :class:`Factory` + :meth:`~object.__new__` method to call the default :ref:`strategy ` + of the :class:`Factory`. A specific strategy for getting instance can be selected by calling the @@ -203,7 +205,7 @@ Attributes and methods .. classmethod:: build_batch(cls, size, **kwargs) - Provides a list of :obj:`size` instances from the :class:`Factory`, + Provides a list of ``size`` instances from the :class:`Factory`, through the 'build' strategy. @@ -213,7 +215,7 @@ Attributes and methods .. classmethod:: create_batch(cls, size, **kwargs) - Provides a list of :obj:`size` instances from the :class:`Factory`, + Provides a list of ``size`` instances from the :class:`Factory`, through the 'create' strategy. @@ -223,16 +225,16 @@ Attributes and methods .. classmethod:: stub_batch(cls, size, **kwargs) - Provides a list of :obj:`size` stubs from the :class:`Factory`. + Provides a list of ``size`` stubs from the :class:`Factory`. .. classmethod:: generate(cls, strategy, **kwargs) - Provide a new instance, with the provided :obj:`strategy`. + Provide a new instance, with the provided ``strategy``. .. classmethod:: generate_batch(cls, strategy, size, **kwargs) - Provides a list of :obj:`size` instances using the specified strategy. + Provides a list of ``size`` instances using the specified strategy. .. classmethod:: simple_generate(cls, create, **kwargs) @@ -241,8 +243,8 @@ Attributes and methods .. classmethod:: simple_generate_batch(cls, create, size, **kwargs) - Provides a list of :obj:`size` instances, either built or created - according to :obj:`create`. + Provides a list of ``size`` instances, either built or created + according to ``create``. **Extension points:** @@ -585,7 +587,7 @@ factory_boy supports two main strategies for generating instances, plus stubs. *Decorator* - Change the default strategy of the decorated :class:`Factory` to the chosen :obj:`strategy`: + Change the default strategy of the decorated :class:`Factory` to the chosen ``strategy``: .. code-block:: python @@ -626,7 +628,7 @@ factory_boy supports two main strategies for generating instances, plus stubs. .. function:: debug(logger='factory', stream=None) :param str logger: The name of the logger to enable debug for - :param file stream: The stream to send debug output to, defaults to :obj:`sys.stderr` + :param io.StringIO stream: The stream to send debug output to, defaults to :obj:`sys.stderr` Context manager to help debugging factory_boy behavior. It will temporarily put the target logger (e.g ``'factory'``) in debug mode, @@ -821,7 +823,7 @@ Decorator The class :class:`LazyFunction` does not provide a decorator. -For complex cases, use :meth:`LazyAttribute.lazy_attribute` directly. +For complex cases, use :meth:`~factory.lazy_attribute` directly. LazyAttribute """"""""""""" @@ -855,7 +857,7 @@ accept the object being built as sole argument, and return a value. The object passed to :class:`LazyAttribute` is not an instance of the target class, -but instead a :class:`~builder.Resolver`: a temporary container that computes +but instead a ``builder.Resolver``: a temporary container that computes the value of all declared fields. @@ -1158,7 +1160,7 @@ The :class:`SubFactory` attribute should be called with: .. note:: When passing an actual :class:`~factory.Factory` for the - :attr:`~factory.SubFactory.factory` argument, make sure to pass + :class:`~factory.SubFactory`'s ``factory`` argument, make sure to pass the class and not instance (i.e no ``()`` after the class): .. code-block:: python @@ -1365,7 +1367,7 @@ Obviously, this "follow parents" ability also handles overriding some attributes This feature is also available to :class:`LazyAttribute` and :class:`LazyAttributeSequence`, -through the :attr:`~builder.Resolver.factory_parent` attribute of the passed-in object: +through the ``factory_parent`` attribute of the passed-in object: .. code-block:: python @@ -1819,7 +1821,7 @@ RelatedFactoryList in a future version for increased consistency with other declarations. .. note:: - Note that using a ``lambda`` for :attr:`size` allows the number of related objects per + Note that using a ``lambda`` for ``size`` allows the number of related objects per parents object to vary. This is useful for testing, when you likely don't want your mock data to have parent objects with the exact same, static number of related objects. @@ -2047,18 +2049,18 @@ Internally, helper methods use :func:`make_factory` to create a new :class:`Factory` according to the method name. Please note, that all Factories created with this methods inherit from the -:class:`factory.base.Factory` class. For full support of your ``ORM``, specify +:class:`factory.Factory` class. For full support of your ``ORM``, specify a base class with the ``FACTORY_CLASS`` parameter as shown in :func:`make_factory` examples. .. function:: build(klass, FACTORY_CLASS=None, **kwargs) .. function:: build_batch(klass, size, FACTORY_CLASS=None, **kwargs) - Create a factory for :obj:`klass` using declarations passed in kwargs; + Create a factory for ``klass`` using declarations passed in kwargs; return an instance built from that factory with :data:`BUILD_STRATEGY`, - or a list of :obj:`size` instances (for :func:`build_batch`). + or a list of ``size`` instances (for :func:`build_batch`). - :param class klass: Class of the instance to build + :param type klass: Class of the instance to build :param int size: Number of instances to build :param kwargs: Declarations to use for the generated factory :param FACTORY_CLASS: Alternate base class (instead of :class:`Factory`) @@ -2068,11 +2070,11 @@ a base class with the ``FACTORY_CLASS`` parameter as shown in .. function:: create(klass, FACTORY_CLASS=None, **kwargs) .. function:: create_batch(klass, size, FACTORY_CLASS=None, **kwargs) - Create a factory for :obj:`klass` using declarations passed in kwargs; + Create a factory for ``klass`` using declarations passed in kwargs; return an instance created from that factory with :data:`CREATE_STRATEGY`, - or a list of :obj:`size` instances (for :func:`create_batch`). + or a list of ``size`` instances (for :func:`create_batch`). - :param class klass: Class of the instance to create + :param type klass: Class of the instance to create :param int size: Number of instances to create :param kwargs: Declarations to use for the generated factory :param FACTORY_CLASS: Alternate base class (instead of :class:`Factory`) @@ -2082,11 +2084,11 @@ a base class with the ``FACTORY_CLASS`` parameter as shown in .. function:: stub(klass, FACTORY_CLASS=None, **kwargs) .. function:: stub_batch(klass, size, FACTORY_CLASS=None, **kwargs) - Create a factory for :obj:`klass` using declarations passed in kwargs; + Create a factory for ``klass`` using declarations passed in kwargs; return an instance stubbed from that factory with :data:`STUB_STRATEGY`, - or a list of :obj:`size` instances (for :func:`stub_batch`). + or a list of ``size`` instances (for :func:`stub_batch`). - :param class klass: Class of the instance to stub + :param type klass: Class of the instance to stub :param int size: Number of instances to stub :param kwargs: Declarations to use for the generated factory :param FACTORY_CLASS: Alternate base class (instead of :class:`Factory`) @@ -2096,11 +2098,11 @@ a base class with the ``FACTORY_CLASS`` parameter as shown in .. function:: generate(klass, strategy, FACTORY_CLASS=None, **kwargs) .. function:: generate_batch(klass, strategy, size, FACTORY_CLASS=None, **kwargs) - Create a factory for :obj:`klass` using declarations passed in kwargs; - return an instance generated from that factory with the :obj:`strategy` strategy, - or a list of :obj:`size` instances (for :func:`generate_batch`). + Create a factory for ``klass`` using declarations passed in kwargs; + return an instance generated from that factory with the ``strategy`` strategy, + or a list of ``size`` instances (for :func:`generate_batch`). - :param class klass: Class of the instance to generate + :param type klass: Class of the instance to generate :param str strategy: The strategy to use :param int size: Number of instances to generate :param kwargs: Declarations to use for the generated factory @@ -2111,11 +2113,11 @@ a base class with the ``FACTORY_CLASS`` parameter as shown in .. function:: simple_generate(klass, create, FACTORY_CLASS=None, **kwargs) .. function:: simple_generate_batch(klass, create, size, FACTORY_CLASS=None, **kwargs) - Create a factory for :obj:`klass` using declarations passed in kwargs; - return an instance generated from that factory according to the :obj:`create` flag, - or a list of :obj:`size` instances (for :func:`simple_generate_batch`). + Create a factory for ``klass`` using declarations passed in kwargs; + return an instance generated from that factory according to the ``create`` flag, + or a list of ``size`` instances (for :func:`simple_generate_batch`). - :param class klass: Class of the instance to generate + :param type klass: Class of the instance to generate :param bool create: Whether to build (``False``) or create (``True``) instances :param int size: Number of instances to generate :param kwargs: Declarations to use for the generated factory @@ -2125,7 +2127,7 @@ a base class with the ``FACTORY_CLASS`` parameter as shown in Randomness management --------------------- -.. currentmodule:: factory.random +.. module:: factory.random Using :mod:`random` in factories allows to "fuzz" a program efficiently. However, it's sometimes required to *reproduce* a failing test. @@ -2147,6 +2149,11 @@ of :class:`random.Random`, which can be managed through the :mod:`factory.random .. method:: reseed_random(seed) The :meth:`reseed_random` function allows to load a chosen seed into the random generator. - That seed can be anything accepted by :meth:`random.seed`. + That seed can be anything accepted by :func:`random.seed`. + +.. data:: randgen + + The :class:`random.Random` global instance used by :mod:`factory.fuzzy` + and :class:`factory.Faker`. See :ref:`recipe-random-management` for help in using those methods in a test setup.