diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 95 |
1 files changed, 77 insertions, 18 deletions
@@ -4,6 +4,22 @@ factory_boy .. image:: https://secure.travis-ci.org/rbarrois/factory_boy.png?branch=master :target: http://travis-ci.org/rbarrois/factory_boy/ +.. image:: https://img.shields.io/pypi/v/factory_boy.svg + :target: http://factoryboy.readthedocs.org/en/latest/changelog.html + :alt: Latest Version + +.. image:: https://img.shields.io/pypi/pyversions/factory_boy.svg + :target: https://pypi.python.org/pypi/factory_boy/ + :alt: Supported Python versions + +.. image:: https://img.shields.io/pypi/wheel/factory_boy.svg + :target: https://pypi.python.org/pypi/factory_boy/ + :alt: Wheel status + +.. image:: https://img.shields.io/pypi/l/factory_boy.svg + :target: https://pypi.python.org/pypi/factory_boy/ + :alt: License + factory_boy is a fixtures replacement based on thoughtbot's `factory_girl <http://github.com/thoughtbot/factory_girl>`_. As a fixtures replacement tool, it aims to replace static, hard to maintain fixtures @@ -52,7 +68,7 @@ Its main features include: - Straightforward declarative syntax - Chaining factory calls while retaining the global context -- Support for multiple build strategies (saved/unsaved instances, attribute dicts, stubbed objects) +- Support for multiple build strategies (saved/unsaved instances, stubbed objects) - Multiple factories per class support, including inheritance @@ -62,8 +78,9 @@ Links * Documentation: http://factoryboy.readthedocs.org/ * Repository: https://github.com/rbarrois/factory_boy * Package: https://pypi.python.org/pypi/factory_boy/ +* Mailing-list: `factoryboy@googlegroups.com <mailto:factoryboy@googlegroups.com>`_ | https://groups.google.com/forum/#!forum/factoryboy -factory_boy supports Python 2.6, 2.7, 3.2 and 3.3, as well as PyPy; it requires only the standard Python library. +factory_boy supports Python 2.6, 2.7, 3.2 to 3.5, as well as PyPy; it requires only the standard Python library. Download @@ -123,7 +140,7 @@ The class of the object must be defined in the ``model`` field of a ``class Meta Using factories """"""""""""""" -factory_boy supports several different build strategies: build, create, attributes and stub: +factory_boy supports several different build strategies: build, create, and stub: .. code-block:: python @@ -133,8 +150,8 @@ factory_boy supports several different build strategies: build, create, attribut # Returns a saved User instance user = UserFactory.create() - # Returns a dict of attributes that can be used to build a User instance - attributes = UserFactory.attributes() + # Returns a stub object (just a bunch of attributes) + obj = UserFactory.stub() You can use the Factory class as a shortcut for the default build strategy: @@ -159,12 +176,38 @@ It is also possible to create a bunch of objects in a single call: .. code-block:: pycon - >>> users = UserFactory.build(10, first_name="Joe") + >>> users = UserFactory.build_batch(10, first_name="Joe") >>> len(users) 10 >>> [user.first_name for user in users] ["Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe", "Joe"] + +Realistic, random values +"""""""""""""""""""""""" + +Demos look better with random yet realistic values; and those realistic values can also help discover bugs. +For this, factory_boy relies on the excellent `fake-factory <https://pypi.python.org/pypi/fake-factory>`_ library: + +.. code-block:: python + + class RandomUserFactory(factory.Factory): + class Meta: + model = models.User + + first_name = factory.Faker('first_name') + last_name = factory.Faker('last_name') + +.. code-block:: pycon + + >>> UserFactory() + <User: Lucy Murray> + + +.. note:: Use of fully randomized data in tests is quickly a problem for reproducing broken builds. + To that purpose, factory_boy provides helpers to handle the random seeds it uses. + + Lazy Attributes """"""""""""""" @@ -250,7 +293,7 @@ Debugging factory_boy Debugging factory_boy can be rather complex due to the long chains of calls. Detailed logging is available through the ``factory`` logger. -A helper, :meth:`factory.debug()`, is available to ease debugging: +A helper, `factory.debug()`, is available to ease debugging: .. code-block:: python @@ -281,12 +324,12 @@ This will yield messages similar to those (artificial indentation): ORM Support """"""""""" -factory_boy has specific support for a few ORMs, through specific :class:`~factory.Factory` subclasses: +factory_boy has specific support for a few ORMs, through specific ``factory.Factory`` subclasses: -* Django, with :class:`~factory.django.DjangoModelFactory` -* Mogo, with :class:`~factory.mogo.MogoFactory` -* MongoEngine, with :class:`~factory.mongoengine.MongoEngineFactory` -* SQLAlchemy, with :class:`~factory.alchemy.SQLAlchemyModelFactory` +* Django, with ``factory.django.DjangoModelFactory`` +* Mogo, with ``factory.mogo.MogoFactory`` +* MongoEngine, with ``factory.mongoengine.MongoEngineFactory`` +* SQLAlchemy, with ``factory.alchemy.SQLAlchemyModelFactory`` Contributing ------------ @@ -294,25 +337,41 @@ Contributing factory_boy is distributed under the MIT License. Issues should be opened through `GitHub Issues <http://github.com/rbarrois/factory_boy/issues/>`_; whenever possible, a pull request should be included. +Questions and suggestions are welcome on the `mailing-list <mailto:factoryboy@googlegroups.com>`_. All pull request should pass the test suite, which can be launched simply with: .. code-block:: sh - $ python setup.py test + $ make test + -.. note:: +In order to test coverage, please use: + +.. code-block:: sh - Running test requires the unittest2 (standard in Python 2.7+) and mock libraries. + $ make coverage -In order to test coverage, please use: +To test with a specific framework version, you may use: + +.. code-block:: sh + + $ make DJANGO=1.9 test + +Valid options are: + +* ``DJANGO`` for ``Django`` +* ``MONGOENGINE`` for ``mongoengine`` +* ``ALCHEMY`` for ``SQLAlchemy`` + + +To avoid running ``mongoengine`` tests (e.g no mongo server installed), run: .. code-block:: sh - $ pip install coverage - $ coverage erase; coverage run --branch setup.py test; coverage report + $ make SKIP_MONGOENGINE=1 test Contents, indices and tables |