diff options
| -rw-r--r-- | MANIFEST.in | 2 | ||||
| -rw-r--r-- | README | 277 | ||||
| -rw-r--r--[l---------] | README.rst | 278 |
3 files changed, 278 insertions, 279 deletions
diff --git a/MANIFEST.in b/MANIFEST.in index 3f09bc6..3dfc1be 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include README +include README.rst include docs/Makefile recursive-include docs *.py *.rst include docs/_static/.keep_dir @@ -1,277 +0,0 @@ -factory_boy -=========== - -.. image:: https://secure.travis-ci.org/rbarrois/factory_boy.png?branch=master - :target: http://travis-ci.org/rbarrois/factory_boy/ - -factory_boy is a fixtures replacement based on thoughtbot's `factory_girl <http://github.com/thoughtbot/factory_girl>`_. - -Its features include: - -- Straightforward syntax -- Support for multiple build strategies (saved/unsaved instances, attribute dicts, stubbed objects) -- Powerful helpers for common cases (sequences, sub-factories, reverse dependencies, circular factories, ...) -- Multiple factories per class support, including inheritance -- Support for various ORMs (currently Django, Mogo, SQLAlchemy) - - -Links ------ - -* Documentation: http://factoryboy.readthedocs.org/ -* Official repository: https://github.com/rbarrois/factory_boy -* Package: https://pypi.python.org/pypi/factory_boy/ - -factory_boy supports Python 2.6, 2.7, 3.2 and 3.3, as well as PyPy; it requires only the standard Python library. - - -Download --------- - -PyPI: https://pypi.python.org/pypi/factory_boy/ - -.. code-block:: sh - - $ pip install factory_boy - -Source: https://github.com/rbarrois/factory_boy/ - -.. code-block:: sh - - $ git clone git://github.com/rbarrois/factory_boy/ - $ python setup.py install - - -Usage ------ - - -.. note:: This section provides a quick summary of factory_boy features. - A more detailed listing is available in the full documentation. - - -Defining factories -"""""""""""""""""" - -Factories declare a set of attributes used to instantiate an object. The class of the object must be defined in the FACTORY_FOR attribute: - -.. code-block:: python - - import factory - from . import models - - class UserFactory(factory.Factory): - FACTORY_FOR = models.User - - first_name = 'John' - last_name = 'Doe' - admin = False - - # Another, different, factory for the same object - class AdminFactory(factory.Factory): - FACTORY_FOR = models.User - - first_name = 'Admin' - last_name = 'User' - admin = True - - -Using factories -""""""""""""""" - -factory_boy supports several different build strategies: build, create, attributes and stub: - -.. code-block:: python - - # Returns a User instance that's not saved - user = UserFactory.build() - - # 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() - - -You can use the Factory class as a shortcut for the default build strategy: - -.. code-block:: python - - # Same as UserFactory.create() - user = UserFactory() - - -No matter which strategy is used, it's possible to override the defined attributes by passing keyword arguments: - -.. code-block:: pycon - - # Build a User instance and override first_name - >>> user = UserFactory.build(first_name='Joe') - >>> user.first_name - "Joe" - - -Lazy Attributes -""""""""""""""" - -Most factory attributes can be added using static values that are evaluated when the factory is defined, -but some attributes (such as fields whose value is computed from other elements) -will need values assigned each time an instance is generated. - -These "lazy" attributes can be added as follows: - -.. code-block:: python - - class UserFactory(factory.Factory): - FACTORY_FOR = models.User - first_name = 'Joe' - last_name = 'Blow' - email = factory.LazyAttribute(lambda a: '{0}.{1}@example.com'.format(a.first_name, a.last_name).lower()) - -.. code-block:: pycon - - >>> UserFactory().email - "joe.blow@example.com" - - -Sequences -""""""""" - -Unique values in a specific format (for example, e-mail addresses) can be generated using sequences. Sequences are defined by using ``Sequence`` or the decorator ``sequence``: - -.. code-block:: python - - class UserFactory(factory.Factory): - FACTORY_FOR = models.User - email = factory.Sequence(lambda n: 'person{0}@example.com'.format(n)) - - >>> UserFactory().email - 'person0@example.com' - >>> UserFactory().email - 'person1@example.com' - - -Associations -"""""""""""" - -Some objects have a complex field, that should itself be defined from a dedicated factories. -This is handled by the ``SubFactory`` helper: - -.. code-block:: python - - class PostFactory(factory.Factory): - FACTORY_FOR = models.Post - author = factory.SubFactory(UserFactory) - - -The associated object's strategy will be used: - - -.. code-block:: python - - # Builds and saves a User and a Post - >>> post = PostFactory() - >>> post.id is None # Post has been 'saved' - False - >>> post.author.id is None # post.author has been saved - False - - # Builds but does not save a User, and then builds but does not save a Post - >>> post = PostFactory.build() - >>> post.id is None - True - >>> post.author.id is None - True - - -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: - -.. code-block:: python - - with factory.debug(): - obj = TestModel2Factory() - - - import logging - logger = logging.getLogger('factory') - logger.addHandler(logging.StreamHandler()) - logger.setLevel(logging.DEBUG) - -This will yield messages similar to those (artificial indentation): - -.. code-block:: ini - - BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={}) - LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>) - SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True - BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4}) - LazyStub: Computing values for tests.test_using.TestModelFactory(one=4) - LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4) - BaseFactory: Generating tests.test_using.TestModelFactory(one=4) - LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>) - BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>) - - -ORM Support -""""""""""" - -factory_boy has specific support for a few ORMs, through specific :class:`~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` - -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. - -All pull request should pass the test suite, which can be launched simply with: - -.. code-block:: sh - - $ python setup.py test - - -.. note:: - - Running test requires the unittest2 (standard in Python 2.7+) and mock libraries. - - -In order to test coverage, please use: - -.. code-block:: sh - - $ pip install coverage - $ coverage erase; coverage run --branch setup.py test; coverage report - - -Contents, indices and tables ----------------------------- - -.. toctree:: - :maxdepth: 2 - - introduction - reference - orms - recipes - fuzzy - examples - internals - changelog - ideas - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/README.rst b/README.rst index 100b938..0371b28 120000..100644 --- a/README.rst +++ b/README.rst @@ -1 +1,277 @@ -README
\ No newline at end of file +factory_boy +=========== + +.. image:: https://secure.travis-ci.org/rbarrois/factory_boy.png?branch=master + :target: http://travis-ci.org/rbarrois/factory_boy/ + +factory_boy is a fixtures replacement based on thoughtbot's `factory_girl <http://github.com/thoughtbot/factory_girl>`_. + +Its features include: + +- Straightforward syntax +- Support for multiple build strategies (saved/unsaved instances, attribute dicts, stubbed objects) +- Powerful helpers for common cases (sequences, sub-factories, reverse dependencies, circular factories, ...) +- Multiple factories per class support, including inheritance +- Support for various ORMs (currently Django, Mogo, SQLAlchemy) + + +Links +----- + +* Documentation: http://factoryboy.readthedocs.org/ +* Official repository: https://github.com/rbarrois/factory_boy +* Package: https://pypi.python.org/pypi/factory_boy/ + +factory_boy supports Python 2.6, 2.7, 3.2 and 3.3, as well as PyPy; it requires only the standard Python library. + + +Download +-------- + +PyPI: https://pypi.python.org/pypi/factory_boy/ + +.. code-block:: sh + + $ pip install factory_boy + +Source: https://github.com/rbarrois/factory_boy/ + +.. code-block:: sh + + $ git clone git://github.com/rbarrois/factory_boy/ + $ python setup.py install + + +Usage +----- + + +.. note:: This section provides a quick summary of factory_boy features. + A more detailed listing is available in the full documentation. + + +Defining factories +"""""""""""""""""" + +Factories declare a set of attributes used to instantiate an object. The class of the object must be defined in the FACTORY_FOR attribute: + +.. code-block:: python + + import factory + from . import models + + class UserFactory(factory.Factory): + FACTORY_FOR = models.User + + first_name = 'John' + last_name = 'Doe' + admin = False + + # Another, different, factory for the same object + class AdminFactory(factory.Factory): + FACTORY_FOR = models.User + + first_name = 'Admin' + last_name = 'User' + admin = True + + +Using factories +""""""""""""""" + +factory_boy supports several different build strategies: build, create, attributes and stub: + +.. code-block:: python + + # Returns a User instance that's not saved + user = UserFactory.build() + + # 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() + + +You can use the Factory class as a shortcut for the default build strategy: + +.. code-block:: python + + # Same as UserFactory.create() + user = UserFactory() + + +No matter which strategy is used, it's possible to override the defined attributes by passing keyword arguments: + +.. code-block:: pycon + + # Build a User instance and override first_name + >>> user = UserFactory.build(first_name='Joe') + >>> user.first_name + "Joe" + + +Lazy Attributes +""""""""""""""" + +Most factory attributes can be added using static values that are evaluated when the factory is defined, +but some attributes (such as fields whose value is computed from other elements) +will need values assigned each time an instance is generated. + +These "lazy" attributes can be added as follows: + +.. code-block:: python + + class UserFactory(factory.Factory): + FACTORY_FOR = models.User + first_name = 'Joe' + last_name = 'Blow' + email = factory.LazyAttribute(lambda a: '{0}.{1}@example.com'.format(a.first_name, a.last_name).lower()) + +.. code-block:: pycon + + >>> UserFactory().email + "joe.blow@example.com" + + +Sequences +""""""""" + +Unique values in a specific format (for example, e-mail addresses) can be generated using sequences. Sequences are defined by using ``Sequence`` or the decorator ``sequence``: + +.. code-block:: python + + class UserFactory(factory.Factory): + FACTORY_FOR = models.User + email = factory.Sequence(lambda n: 'person{0}@example.com'.format(n)) + + >>> UserFactory().email + 'person0@example.com' + >>> UserFactory().email + 'person1@example.com' + + +Associations +"""""""""""" + +Some objects have a complex field, that should itself be defined from a dedicated factories. +This is handled by the ``SubFactory`` helper: + +.. code-block:: python + + class PostFactory(factory.Factory): + FACTORY_FOR = models.Post + author = factory.SubFactory(UserFactory) + + +The associated object's strategy will be used: + + +.. code-block:: python + + # Builds and saves a User and a Post + >>> post = PostFactory() + >>> post.id is None # Post has been 'saved' + False + >>> post.author.id is None # post.author has been saved + False + + # Builds but does not save a User, and then builds but does not save a Post + >>> post = PostFactory.build() + >>> post.id is None + True + >>> post.author.id is None + True + + +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: + +.. code-block:: python + + with factory.debug(): + obj = TestModel2Factory() + + + import logging + logger = logging.getLogger('factory') + logger.addHandler(logging.StreamHandler()) + logger.setLevel(logging.DEBUG) + +This will yield messages similar to those (artificial indentation): + +.. code-block:: ini + + BaseFactory: Preparing tests.test_using.TestModel2Factory(extra={}) + LazyStub: Computing values for tests.test_using.TestModel2Factory(two=<OrderedDeclarationWrapper for <factory.declarations.SubFactory object at 0x1e15610>>) + SubFactory: Instantiating tests.test_using.TestModelFactory(__containers=(<LazyStub for tests.test_using.TestModel2Factory>,), one=4), create=True + BaseFactory: Preparing tests.test_using.TestModelFactory(extra={'__containers': (<LazyStub for tests.test_using.TestModel2Factory>,), 'one': 4}) + LazyStub: Computing values for tests.test_using.TestModelFactory(one=4) + LazyStub: Computed values, got tests.test_using.TestModelFactory(one=4) + BaseFactory: Generating tests.test_using.TestModelFactory(one=4) + LazyStub: Computed values, got tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>) + BaseFactory: Generating tests.test_using.TestModel2Factory(two=<tests.test_using.TestModel object at 0x1e15410>) + + +ORM Support +""""""""""" + +factory_boy has specific support for a few ORMs, through specific :class:`~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` + +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. + +All pull request should pass the test suite, which can be launched simply with: + +.. code-block:: sh + + $ python setup.py test + + +.. note:: + + Running test requires the unittest2 (standard in Python 2.7+) and mock libraries. + + +In order to test coverage, please use: + +.. code-block:: sh + + $ pip install coverage + $ coverage erase; coverage run --branch setup.py test; coverage report + + +Contents, indices and tables +---------------------------- + +.. toctree:: + :maxdepth: 2 + + introduction + reference + orms + recipes + fuzzy + examples + internals + changelog + ideas + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + |