.. PyFactory documentation master file, created by
   sphinx-quickstart on Sat Aug 27 16:53:33 2011.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

PyFactory |release| Documentation
=================================

Overview
--------

**PyFactory** is a library for writing and using model factories. Model
factories allow you to replace test fixtures or manual model creation in
tests with succint, easy to use factories.

The need for factories becomes apparent when you're testing any
application of at least average complexity, where models often have a
large tree of dependencies. For example, on some website you may want to
test the ``Comment`` model. A ``Comment`` requires an author, which is a
``User``, and a ``Post``. A ``Post`` may further require a ``Category``,
and so on. So, just to test a simple ``Comment``, you're typically forced
to either create a brittle network of static fixtures, or manually create
many models and glue together their relationships. *Yuck!*

With model factories, you would simply do the following::

    comment = CommentFactory().create("comment")

This handles creating all the dependent models, as well. And the code for
this factory is equally simple::

    from pyfactory import Factory, association, schema
    import models

    class CommentFactory(Factory):
        _model = models.Comment
        _model_builder = models.ModelBuilder

        @schema()
        def comment(self):
            return {
                "body": "Some text...",
                "author_id": association(UserFactory(), "user", "id"),
                "post_id": association(PostFactory(), "post", "id")
            }

    # Imagine the UserFactory and PostFactory here, which are basically
    # equivalent to the above.

Documentation
-------------

Tutorial
~~~~~~~~

A :doc:`tutorial` covering most of the features is available.

Usage Documentation
~~~~~~~~~~~~~~~~~~~

The following is a list of pages dedicated to specific concepts of
**PyFactory**. It is recommended that you read the :doc:`tutorial`
before diving into these pages.

.. toctree::
   :maxdepth: 1

   usage/model_builders
   usage/factories
   usage/associations
   usage/special_fields

API Reference
~~~~~~~~~~~~~

A complete :doc:`API reference <api/index>` is the recommend documentation
for in-depth details on various pieces of **PyFactory**.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. toctree::
   :hidden:

   api/index
   tutorial
