Skip to main content

A backend agnostic data modeling entity library

Project description

Build Status

SpringField makes API data easy.

SpringField makes it simple to model structured data. Once the data is modeled, SpringField can parse API responses into easy to use Python objects and types. It can also generate the same structured data for making API request.

SpringField is ideal for:

  • Restful JSON API data structures

  • Parsing CSV data structures from csv.DictReader

  • Turning anything Python can parse into a dict or list into a structured object

There is also a helper library for using SpringField with Mongo: springfield- mongo


To define an springfield.Entity, subclass springfield.Entity. Define your attributes by specifying fields. This library provides the follow self-describing fields to start with:

  • IntField

  • FloatField

  • BooleanField

  • StringField

  • BytesField

  • DateTimeField

  • EmailField

  • UrlField

  • EntityField

  • CollectionField

A quick example:

#!/usr/bin/env python
from springfield import Entity, fields
from springfield.timeutil import utcnow

class Bookmark(Entity):
    uri = fields.UrlField(doc='The bookmark uri.')
    verified = fields.BooleanField(doc='Whether or not this bookmark URI has been verified to exist.')
    added = fields.DateTimeField()

class User(Entity):
    id = fields.IntField(doc='Auto-incremented database id.')
    email = fields.EmailField(doc='The user\'s email address.')
    bookmarks = fields.CollectionField(fields.EntityField(Bookmark))
    created = fields.DateTimeField()

if __name__ == '__main__':
    user = User() = 5 = ''
    user.bookmarks = [
        {'uri': ''},
        {'uri': '', 'verified': True}
    user.created = utcnow()
    data = user.to_json()
    # `data` is suitable to return in something like a JSON API.
    print data

    # Similarly, `data` can be adapted from a JSON API request body.
    user = User.from_json(data)
    print user.created
    print user.bookmarks

Will print (the json was prettified to protect the innocent):

2017-01-25 20:47:37+00:00
[<Bookmark {uri:}>, <Bookmark {verified: True, uri:}>]

Notice a few things:

  • Not every field is required for an entity. This is useful for doing sparse updates on an API.

  • SpringField will adapt types in a non-destructive way.

  • You can also create entities by adapting JSON, which is really handy at API boundaries.

Field Validation

SpringField does field validation when constructing entities, according to the types defined by the fields on that entity. For example:

You can define more complex field adaptation behavior by subclassing springfield.fields.Field and implementing your own fields. See the documentation on springfield.fields.Field for more information.

Similar Projects

Building Documentation

To build documentation, first install the requirements:

Now you can build requirements with make:

Running Tests

To run tests, first install the test requirements:

pip install -r test_requirements.txt

Tests can be run with ./src/tests/

python src/tests/



  • Added support for Python 3.6+

  • Dropped support for Python <2.7


  • Fix packages for pytest plugin


  • Allow EntityFields to use dotted-name class strings. This was done to allow circular references in entities that may refer to one another.

  • Added BytesField


Bug Fixes

  • Allow empty values for URL

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

springfield-0.8.0.tar.gz (25.1 kB view hashes)

Uploaded source

Built Distribution

springfield-0.8.0-py3-none-any.whl (16.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page