Permalink
Browse files

Work on documentation.

  • Loading branch information...
1 parent 86bdb88 commit e4e0cfd831286de9e6617ec25d03ee616a716deb @gregmuellegger committed Oct 14, 2010
Showing with 88 additions and 37 deletions.
  1. +3 −2 autofixture/base.py
  2. +9 −0 docs/builtin_autofixtures.rst
  3. +2 −1 docs/index.rst
  4. +0 −29 docs/registry.rst
  5. +74 −5 docs/usage.rst
View
@@ -212,8 +212,9 @@ def prepare_class(self):
def add_field_value(self, name, value):
'''
- Pass a static *value* that should be assigned to the field called
- *name*. *value* may be a :ref:`Generator <Generator>` instance.
+ Pass a *value* that should be assigned to the field called *name*.
+ Thats the same as specifying it in the *field_values* argument of the
+ :meth:`constructor <autofixture.base.AutoFixture.__init__>`.
'''
self.field_values[name] = value
@@ -0,0 +1,9 @@
+Builtin :class:`AutoFixture` subclasses
+=======================================
+
+There are some :class:`AutoFixture` subclasses that are shipped by default
+with ``django-autofixture``. They are listed below.
+
+.. _UserFixture:
+.. autoclass:: autofixture.autofixtures.UserFixture
+ :members: __init__
View
@@ -26,4 +26,5 @@ Contents
installation
loadtestdata
usage
- registry
+ builtin_autofixtures
+ contribute
View
@@ -1,29 +0,0 @@
-The :class:`AutoFixture` registry
-=================================
-
-.. _registry:
-
-Since :class:`AutoFixture` is designed to fit for almost all models, its very
-generic and doesn't know anything about the actual logic and meanings of
-relations or the purpose of your model fields. This makes it sometimes a bit
-difficult to provide the correct :ref:`field_values <field values>` in all
-places where you want ``autofixture`` to instanciate your models.
-
-So there is a registry to register custom :class:`AutoFixture` subclasses with
-specific models. These subclasses are then used by default if you generated
-test data either with the :ref:`loadtestdata <loadtestdata>` management
-command or with one of the :ref:`shortcuts <shortcuts>` in :mod:`autofixture`.
-
-.. autofunction:: autofixture.register
-
-.. autofunction:: autofixture.unregister
-
-Default :class:`AutoFixture` subclasses
----------------------------------------
-
-There are some :class:`AutoFixture` subclasses that are shipped by default
-with ``django-autofixture``. These are listed below.
-
-.. _UserFixture:
-.. autoclass:: autofixture.autofixtures.UserFixture
- :members: __init__
View
@@ -23,17 +23,86 @@ test data as fast as possible.
.. _AutoFixture:
-Using the :class:`AutoFixture` class
-------------------------------------
+Using the :class:`~autofixture.base.AutoFixture` class
+------------------------------------------------------
.. autoclass:: autofixture.base.AutoFixture
- :members: __init__, add_field_value, add_constraint, check_constrains,
+ :members: __init__, add_field_value, add_constraint,
create, create_one
+The :class:`~autofixture.base.AutoFixture` registry
+---------------------------------------------------
+
+.. _registry:
+
+Since :class:`~autofixture.base.AutoFixture` is designed to fit for almost all
+models, its very generic and doesn't know anything about the actual logic and
+meanings of relations or the purpose of your model fields. This makes it
+sometimes a bit difficult to provide the correct :ref:`field_values <field
+values>` in all places where you want ``autofixture`` to instanciate your
+models.
+
+So there is a registry to register custom
+:class:`~autofixture.base.AutoFixture` subclasses with specific models. These
+subclasses are then used by default if you generate test data either with the
+:ref:`loadtestdata <loadtestdata>` management command or with one of the
+:ref:`shortcuts <shortcuts>` in :mod:`autofixture`.
+
+.. autofunction:: autofixture.register
+
+.. autofunction:: autofixture.unregister
+
Subclassing :class:`AutoFixture`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
+
+.. _subclassing:
+.. _values:
+
+In most cases it will by sufficient to provide a different logic to generate
+the values for your model fields in :class:`~autofixture.base.AutoFixture`
+subclasses. This can be simply done by a nested ``Values`` class::
+
+ class EntryFixture(AutoFixture):
+ class Values:
+ title = 'My static title'
+ status = staticmethod(lambda: random.choice((1,2)))
+ pub_date = generators.DateTimeGenerator(
+ min_date=datetime(2009,1,1),
+ max_date=datetime(2009,12,31))
+
+This will make sure that ``title`` is always ``'My static title'``, status is
+either ``1`` or ``2`` and that ``pub_date`` is in the somewhere in 2009.
+
+Like you can see in the example you can apply static values, simple callables
+or specific generators to specific fields. However remember to use the
+``staticmethod`` decorator when using a ``method`` as callable - like the
+``lambda`` statement in the example. It's in fact also just a shorter
+definition of a method.
+
+*A note on subclassing subclasses and turtles all the way down:* Some times
+it's usefull for a project to have a common base class for all the registered
+*AutoFixtures*. This is ofcourse possible and very usable since you don't need
+to re-define all the field definitions in the nested ``Values`` class. The
+:class:`~autofixture.base.AutoFixture` class is caring about this and will
+collect all ``Values`` of base classes and merge them together. For
+clarification here a short example::
+
+ class CommonFixture(AutoFixture):
+ class Values:
+ tags = generators.ChoicesGenerator(
+ values=('apple', 'banana', 'orange'))
+
+ class EntryFixture(AutoFixture):
+ class Values:
+ title = 'My static title'
+
+ # all created entries will have the same title 'My static title' and one
+ # tag out of apple, banana and orange.
+ EntryFixture(Entry).create(5)
-The following methods may be overwritten by subclasses:
+If you want to digg deeper and need to customize more logic of model creation,
+you can override some handy methods of the
+:class:`~autofixture.base.AutoFixture` class:
.. automethod:: autofixture.base.AutoFixture.prepare_class

0 comments on commit e4e0cfd

Please sign in to comment.