generate DataSet classes from real data.

There are several issues you may run into while working with fixtures:

The data model of a program is usually an implementation detail. It's bad practice to "know" about implementation details in tests because it means you have to update your tests when those details change; you should only have to update your tests when an interface changes.
Data accumulates very fast and there is already a useful tool for slicing and dicing data: the database! Hand-coding DataSet classes is not always the way to go.
When regression testing or when trying to reproduce a bug, you may want to grab a "snapshot" of the existing data.

fixture is a shell command to address these and other issues. It gets installed along with this module. Specifically, the fixture command accepts a path to a single object and queries that object using the command options. The output is python code that you can use in a test to reload the data retrieved by the query.

Usage

$ fixture --help
usage: fixture [options] object_path

Using the object specified in the path, generate DataSet classes (code) to
reproduce its data.  An object_path can be a python path or a file path
or anything else that a handler can recognize.

options:
  -h, --help            show this help message and exit
  --dsn=DSN             sets db connection for a handler that uses a db
  -w WHERE, --where=WHERE
                        SQL where clause, i.e. "id = 1705"
  --suffix=SUFFIX       string suffix for all dataset class names (default: Data; i.e. an Employee object becomes EmployeeData)
  --prefix=PREFIX       string prefix for all dataset class names (default: None)
  --env=ENV             module path to use as an environment for finding objects.  declaring multiple --env values will be recognized
  --require-egg=REQUIRED_EGGS
                        a requirement string to enable importing from a module that was installed in multi-version mode by setuptools.  I.E. foo==1.0.  You can repeat
                        this option as many times as necessary.
  --template=TEMPLATE   template to use; choices: ('fixture', 'testtools'), default: 'fixture'

An example

Let's set up a database and insert some data (using sqlalchemy code) so we can run the fixture command:

>>> from sqlalchemy import *
>>> DSN = 'sqlite:////tmp/fixture_example.db'
>>> from fixture.examples.db.sqlalchemy_examples import (
...                                 Author, Book, dynamic_meta)
>>> dynamic_meta.connect(DSN)
>>> dynamic_meta.create_all()
>>> session = create_session()

>>> frank = Author()
>>> frank.first_name = "Frank"
>>> frank.last_name = "Herbert"
>>> session.save(frank)

>>> dune = Book()
>>> dune.title = "Dune"
>>> dune.author = frank
>>> session.save(dune)

>>> session.flush()

It's now possible to run a command that points at our Book object, sends it a SQL query with a custom where clause, and turns the record sets into DataSet classes:

$ fixture --dsn=sqlite:////tmp/fixture_example.db --where="title='Dune'" fixture.examples.db.sqlalchemy_examples.Book
import datetime
from fixture import DataSet
from fixture.dataset import MergedSuperSet
from fixture.style import NamedDataStyle
from fixture import SQLAlchemyFixture
from fixture.examples.db.sqlalchemy_examples import authors
from fixture.examples.db.sqlalchemy_examples import books

fixture = SQLAlchemyFixture(
            env = globals(),
            style = NamedDataStyle(),
            dataclass = MergedSuperSet)


class authorsData(DataSet):
    class authors_1:
        first_name = u'Frank'
        last_name = u'Herbert'
        id = 1

class booksData(DataSet):
    class books_1:
        author_id = authorsData.authors_1.ref('id')
        id = 1
        title = u'Dune'

Notice that we only queried the Book object but we got back all the necessary foreign keys that were needed to reproduce the data (in this case, the Author data).

Creating a custom data handler

No documentation yet

The fixture.command.generate module

Class	NoData	no data was returned by a query
Class	HandlerException	Undocumented
Class	UnrecognizedObject	Undocumented
Class	UnsupportedHandler	Undocumented
Class	MisconfiguredHandler	Undocumented
Function	register_handler	Undocumented
Function	clear_handlers	Undocumented
Class	FixtureCache	cache of Fixture objects and their data sets to be generatred.
Class	DataSetGenerator	produces a callable object that can generate DataSet code.
Class	FixtureSet	a key, data_dict pair for a set in a fixture.
Class	HandlerType	Undocumented
Class	DataHandler	handles an object that can provide fixture data.
Function	dataset_generator	%prog [options] object_path
Function	get_object_data	query object at object_path and return generated code
Function	main	Undocumented

Module f.c.g.generate

Usage

An example

Creating a custom data handler

The fixture.command.generate module