Installing¶

For the less adventurous, Appengine-Fixture-Loader is available on PyPI at https://pypi.python.org/pypi/Appengine-Fixture-Loader.

Single-kind loads¶

Let’s say you have a model like this:

class Person(ndb.Model):
    """Our sample class"""
    first_name = ndb.StringProperty()
    last_name = ndb.StringProperty()
    born = ndb.DateTimeProperty()
    userid = ndb.IntegerProperty()
    thermostat_set_to = ndb.FloatProperty()
    snores = ndb.BooleanProperty()
    started_school = ndb.DateProperty()
    sleeptime = ndb.TimeProperty()
    favorite_movies = ndb.JsonProperty()
    processed = ndb.BooleanProperty(default=False)

If you want to load a data file like this:

[
    {
        "__id__": "jdoe",
        "born": "1968-03-03T00:00:00",
        "first_name": "John",
        "last_name": "Doe",
        "favorite_movies": [
            "2001",
            "The Day The Earth Stood Still (1951)"
        ],
        "snores": false,
        "sleeptime": "23:00",
        "started_school": "1974-02-15",
        "thermostat_set_to": 18.34,
        "userid": 1
    },

...

    {
        "born": "1980-05-25T00:00:00",
        "first_name": "Bob",
        "last_name": "Schneier",
        "favorite_movies": [
            "2001",
            "Superman"
        ],
        "snores": true,
        "sleeptime": "22:00",
        "started_school": "1985-08-01",
        "thermostat_set_to": 18.34,
        "userid": -5
    }
]

All you need to do is to:

from appengine_fixture_loader.loader import load_fixture

and then:

loaded_data = load_fixture('tests/persons.json', kind=Person)

In our example, loaded_data will contain a list of already persisted Person models you can then manipulate and persist again.

The __id__ attribute, when defined, will save the object with that given id. In our case, the key to the first object defined will be a ndb.Key(‘Person’, ‘jdoe’). The key may be defined on an object by object base - where the __id__ parameter is omitted, an automatic id will be generated - the key to the second one will be something like ndb.Key(‘Person’, 1).

Multi-kind loads¶

It’s convenient to be able to load multiple kinds of objects from a single file. For those cases, we provide a simple way to identify the kind of object being loaded and to provide a set of models to use when loading the objects.

Consider our original example model:

class Person(ndb.Model):
    """Our sample class"""
    first_name = ndb.StringProperty()
    last_name = ndb.StringProperty()
    born = ndb.DateTimeProperty()
    userid = ndb.IntegerProperty()
    thermostat_set_to = ndb.FloatProperty()
    snores = ndb.BooleanProperty()
    started_school = ndb.DateProperty()
    sleeptime = ndb.TimeProperty()
    favorite_movies = ndb.JsonProperty()
    processed = ndb.BooleanProperty(default=False)

and let’s add a second one:

class Dog(ndb.Model):
    """Another sample class"""
    name = ndb.StringProperty()

Now, if we wanted to make a single file load objects of the two kinds, we’d need to use the __kind__ attribute in the JSON:

[
    {
        "__kind__": "Person",
        "born": "1968-03-03T00:00:00",
        "first_name": "John",
        "last_name": "Doe",
        "favorite_movies": [
            "2001",
            "The Day The Earth Stood Still (1951)"
        ],
        "snores": false,
        "sleeptime": "23:00",
        "started_school": "1974-02-15",
        "thermostat_set_to": 18.34,
        "userid": 1
    },
    {
        "__kind__": "Dog",
        "name": "Fido"
    }
]

And, to load the file, we’d have to:

from appengine_fixture_loader.loader import load_fixture

and:

loaded_data = load_fixture('tests/persons_and_dogs.json',
                           kind={'Person': Person, 'Dog': Dog})

will result in a list of Persons and Dogs (in this case, one person and one dog).

Multi-kind, multi-level loads¶

Anther common case is having hierarchies of entities that you want to reconstruct for your tests.

Using slightly modified versions of our example classes:

class Person(ndb.Model):
    """Our sample class"""
    first_name = ndb.StringProperty()
    last_name = ndb.StringProperty()
    born = ndb.DateTimeProperty()
    userid = ndb.IntegerProperty()
    thermostat_set_to = ndb.FloatProperty()
    snores = ndb.BooleanProperty()
    started_school = ndb.DateProperty()
    sleeptime = ndb.TimeProperty()
    favorite_movies = ndb.JsonProperty()
    processed = ndb.BooleanProperty(default=False)
    appropriate_adult = ndb.KeyProperty()

and:

class Dog(ndb.Model):
    """Another sample class"""
    name = ndb.StringProperty()
    processed = ndb.BooleanProperty(default=False)
    owner = ndb.KeyProperty()

And using __children__[attribute_name]__ like meta-attributes, as in:

[
    {
        "__kind__": "Person",
        "born": "1968-03-03T00:00:00",
        "first_name": "John",
        "last_name": "Doe",

        ...

        "__children__appropriate_adult__": [
            {
                "__kind__": "Person",
                "born": "1970-04-27T00:00:00",

                ...

                "__children__appropriate_adult__": [
                    {
                        "__kind__": "Person",
                        "born": "1980-05-25T00:00:00",
                        "first_name": "Bob",

                        ...

                        "userid": 3
                    }
                ]
            }
        ]
    },
    {
        "__kind__": "Person",
        "born": "1999-09-19T00:00:00",
        "first_name": "Alice",

        ...

        "__children__appropriate_adult__": [
            {
                "__kind__": "Person",

                ...

                "__children__owner__": [
                    {
                        "__kind__": "Dog",
                        "name": "Fido"
                    }
                ]
            }
        ]
    }
]

you can reconstruct entire entity trees for your tests.

Parent/Ancestor-based relationships with automatic keys¶

It’s also possible to set the parent by using the __children__ attribute.

For our example classes, importing:

[
    {
        "__kind__": "Person",
        "first_name": "Alice",

        ...

        "__children__": [
            {
                "__kind__": "Person",
                "first_name": "Bob",
                ...

                "__children__owner__": [
                    {
                        "__kind__": "Dog",
                        "name": "Fido"
                    }
                ]
            }
        ]
    }
]

should be equivalent to:

alice = Person(first_name='Alice')
alice.put()
bob = Person(first_name='Bob', parent=alice)
bob.put()
fido = Dog(name='Fido', parent=bob)
fido.put()

You can then retrieve fido with:

fido = Dog.query(ancestor=alice.key).get()

Types of Contributions¶

Get Started!¶

Ready to contribute? Here’s how to set up appengine-fixture-loader for local development.

1. Fork the appengine-fixture-loader repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/appengine-fixture-loader.git
   

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

   $ mkvirtualenv appengine-fixture-loader
   $ cd appengine-fixture-loader/
   $ python setup.py develop
   

4. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

   $ flake8 appengine-fixture-loader tests
   $ python setup.py test
   $ tox
   

   To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

7. Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.6, 2.7, 3.3, and 3.4, and for PyPy. Check https://travis-ci.org/rbanffy/appengine-fixture-loader/pull_requests and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ python -m unittest tests.test_appengine-fixture-loader

Development Lead¶

• Ricardo Bánffy <rbanffy@gmail.com>

Contributors¶

John Del Rosario (john2x)