Inheriting DataSet rows

Since a row is just a Python class, you can inherit from a row to morph its values, i.e.:

>>> class Authors(DataSet):
...     class frank_herbert:
...         first_name = "Frank"
...         last_name = "Herbert"
...     class brian_herbert(frank_herbert):
...         first_name = "Brian"

This is useful for adhering to the DRY principle (Don't Repeat Yourself) as well as for testing edge cases.

Referencing foreign DataSet classes

When defining rows in a DataSet that reference foreign keys, you need to mimic how your data object wants to save such a reference. If your data object wants to save foreign keys as objects (not ID numbers) then you can simply reference another row in a DataSet as if it were an object.:

>>> class Books(DataSet):
...     class dune:
...         title = "Dune"
...         author = Authors.frank_herbert
...     class sudanna:
...         title = "Sudanna Sudanna"
...         author = Authors.brian_herbert

During data loading, the reference to DataSet Authors.brian_herbert will be replaced with the actual stored object used to load that row into the database. This will work as expected for one-to-many relationships, i.e.:

>>> class Books(DataSet):
...     class two_worlds:
...         title = "Man of Two Worlds"
...         authors = [Authors.frank_herbert, Authors.brian_herbert]

However, in some cases you may need to reference an attribute that does not have a value until it is loaded, like a serial ID column. (Note that this is not supported by the sqlalchemy data layer when using sessions.) To facilitate this, each inner class of a DataSet gets decorated with a special method, ref(), that can be used to reference a column value before it exists, i.e.:

>>> class Books(DataSet):
...     class dune:
...         title = "Dune"
...         author_id = Authors.frank_herbert.ref('id')
...     class sudanna:
...         title = "Sudanna Sudanna"
...         author_id = Authors.brian_herbert.ref('id')

This sets the author_id to the id of another row in Author, as if it were a foreign key. But notice that the id attribute wasn't explicitly defined by the Authors data set. When the id attribute is accessed later on, its value is fetched from the actual row inserted.

Customizing a Dataset

A DataSet can be customized by defining a special inner class named Meta. See the DataSet.Meta API for more info.

Supported storage media

The Fixture class is designed to support many different types of storage media and there is a section later about creating your own Fixture. Here are the various storage media supported by built-in Fixture subclasses:

>>> from fixture import SQLAlchemyFixture

>>> from sqlalchemy import create_session
>>> from sqlalchemy.ext.sessioncontext import SessionContext
>>> from fixture.examples.db import sqlalchemy_examples
>>> dbfixture = SQLAlchemyFixture(
...                 session_context=SessionContext(create_session),
...                 env=sqlalchemy_examples)
...

>>> from fixture import SQLObjectFixture

>>> from fixture.examples.db import sqlobject_examples
>>> dbfixture = SQLObjectFixture(
...     dsn="sqlite:/:memory:", env=sqlobject_examples)
...

An Example Loading Data Using SQLAlchemy

Fixture is designed for applications that already define a way of accessing its data; the LoadableFixture just "hooks in" to that interface. To start this example, here is some sqlalchemy code to set up a database of books and authors:

>>> from sqlalchemy import *
>>> engine = create_engine('sqlite:///:memory:')
>>> meta = BoundMetaData(engine)
>>> session = create_session(engine)
>>> authors = Table('authors', meta,
...     Column('id', Integer, primary_key=True),
...     Column('first_name', String),
...     Column('last_name', String))
...
>>> class Author(object):
...     pass
...
>>> mapper(Author, authors) #doctest: +ELLIPSIS
<sqlalchemy.orm.mapper.Mapper object at ...>
>>> books = Table('books', meta,
...     Column('id', Integer, primary_key=True),
...     Column('title', String),
...     Column('author_id', Integer, ForeignKey('authors.id')))
...
>>> class Book(object):
...     pass
...
>>> mapper(Book, books, properties={
...     'author': relation(Author, backref='books')
... }) #doctest: +ELLIPSIS
<sqlalchemy.orm.mapper.Mapper object at ...>
>>> meta.create_all()

Consult the sqlalchemy documentation for further examples of data mapping.

Defining a Fixture

This is a fixture with minimal configuration to support loading data into the Book or Author mapped classes:

>>> from fixture import SQLAlchemyFixture
>>> dbfixture = SQLAlchemyFixture(
...     env={'BookData': Book, 'AuthorData': Author},
...     session=session )
...

There are several shortcuts, like fixture.style.NamedDataStyle and specifying the session_context keyword.

Loading DataSet objects

The job of the Fixture object is to load and unload DataSet objects. Let's consider the following DataSet objects (reusing the examples from earlier):

>>> from fixture import DataSet
>>> class AuthorData(DataSet):
...     class frank_herbert:
...         first_name = "Frank"
...         last_name = "Herbert"
>>> class BookData(DataSet):
...     class dune:
...         title = "Dune"
...         author = AuthorData.frank_herbert

As you recall, we passed a dictionary into the Fixture that associates DataSet names with storage objects. Using this dict, a Fixture.Data instance now knows to use the sqlalchemy mapped class Book when saving a DataSet named BookData. Since we also gave it a session keyword, this will be used to actually save objects:

>>> data = dbfixture.data(AuthorData, BookData)
>>> data.setup()
>>> all_books = list(session.query(Book).select())
>>> all_books #doctest: +ELLIPSIS
[<...Book object at ...>]
>>> all_books[0].author.first_name
'Frank'
>>> data.teardown()
>>> list(session.query(Book).select())
[]

Discovering storable objects with Style

If you didn't want to create a strict mapping of DataSet class names to their storable object names you can use Style objects to translate DataSet class names. For example, consider this Fixture :

>>> from fixture import SQLAlchemyFixture
>>> from fixture.style import TrimmedNameStyle
>>> dbfixture = SQLAlchemyFixture(
...     env=globals(),
...     style=TrimmedNameStyle(suffix="Data"),
...     session=session )
...

This would take the name AuthorData and trim off "Data" from its name to find Author, its mapped sqlalchemy class for storing data. Since this is a logical convention to follow for naming DataSet classes, you can use a shortcut:

>>> from fixture.style import NamedDataStyle
>>> dbfixture = SQLAlchemyFixture(
...     env=globals(),
...     style=NamedDataStyle(),
...     session=session )
...

See the Style API for all available Style objects.

Loading DataSet classes in a test

Now that you have a Fixture object to load DataSet classes you are ready to write some tests. You can either write your own code that creates a data instance and calls setup/teardown manually (like in previous examples), or you can use one of several utilities.

As a hoky attempt to make these tests somewhat realistic, here is a function we will be testing, that returns True if a book by author or title is in stock:

>>> def in_stock(book_title=None, author_last_name=None):
...     if book_title:
...         rs = session.query(Book).select(books.c.title==book_title)
...     elif author_last_name:
...         rs = session.query(Book).select(
...                 authors.c.last_name==author_last_name,
...                 from_obj=[books.join(authors)])
...     else:
...         return False
...     if len(list(rs)):
...         return True

>>> import unittest
>>> from fixture import DataTestCase
>>> class TestBookShop(DataTestCase, unittest.TestCase):
...     fixture = dbfixture
...     datasets = [BookData]
...
...     def test_books_are_in_stock(self):
...         assert in_stock(book_title=self.data.BookData.dune.title)
...
>>> suite = unittest.TestLoader().loadTestsFromTestCase(TestBookShop)
>>> unittest.TextTestRunner().run(suite)
<unittest._TextTestResult run=1 errors=0 failures=0>

easy_install fixture[decorators]

>>> @dbfixture.with_data(AuthorData, BookData)
... def test_books_are_in_stock(data):
...     assert in_stock(book_title=data.BookData.dune.title)
...
>>> import nose
>>> case = nose.case.FunctionTestCase(test_books_are_in_stock)
>>> unittest.TextTestRunner().run(case)
<unittest._TextTestResult run=1 errors=0 failures=0>

from __future__ import with_statement
with dbfixture.data(AuthorData, BookData) as data:
    assert in_stock(book_title=data.BookData.dune.title)

Defining a custom LoadableFixture

It's possible to create your own LoadableFixture if you need to load data with something other than SQLAlchemy or SQLObject.

You'll need to subclass at least fixture.loadable.loadable:LoadableFixture, possibly even fixture.loadable.loadable:EnvLoadableFixture or the more useful fixture.loadable.loadable:DBLoadableFixture. Here is a simple example for creating a fixture that hooks into some kind of database-centric loading mechanism:

>>> loaded_items = set()
>>> class Author(object):
...     '''This would be your actual storage object, i.e. data mapper.
...        For the sake of brevity, you'll have to imagine that it knows
...        how to somehow store "author" data.'''
...
...     name = None # gets set by the data set
...
...     def save(self):
...         '''just one example of how to save your object.
...            there is no signature guideline for how this object
...            should save itself (see the adapter below).'''
...         loaded_items.add(self)
...     def __repr__(self):
...         return "<%s name=%s>" % (self.__class__.__name__, self.name)
...
>>> from fixture.loadable import DBLoadableFixture
>>> class MyFixture(DBLoadableFixture):
...     '''This is the class you will instantiate, the one that knows how to
...        load datasets'''
...
...     class Medium(DBLoadableFixture.Medium):
...         '''This is an object that adapts a Fixture storage medium
...            to the actual storage medium.'''
...
...         def clear(self, obj):
...             '''where you need to expunge the obj'''
...             loaded_items.remove(obj)
...
...         def visit_loader(self, loader):
...             '''a chance to reference any attributes from the loader.
...                this is called before save().'''
...
...         def save(self, row, column_vals):
...             '''save data into your object using the provided
...                fixture.dataset.DataRow instance'''
...             # instantiate your real object class (Author), which was set
...             # in __init__ to self.medium ...
...             obj = self.medium()
...             for c, val in column_vals:
...                 # column values become object attributes...
...                 setattr(obj, c, val)
...             obj.save()
...             # be sure to return the object:
...             return obj
...
...     def create_transaction(self):
...         '''a chance to create a transaction.
...            two separate transactions are used: one during loading
...            and another during unloading.'''
...         class DummyTransaction(object):
...             def begin(self):
...                 pass
...             def commit(self):
...                 pass
...             def rollback(self):
...                 pass
...         t = DummyTransaction()
...         t.begin() # you must call begin yourself, if necessary
...         return t

Now let's load some data into the custom Fixture using a simple env mapping:

>>> from fixture import DataSet
>>> class AuthorData(DataSet):
...     class frank_herbert:
...         name="Frank Herbert"
...
>>> fixture = MyFixture(env={'AuthorData': Author})
>>> data = fixture.data(AuthorData)
>>> data.setup()
>>> loaded_items
set([<Author name=Frank Herbert>])
>>> data.teardown()
>>> loaded_items
set([])

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