Skip to content
Data-structure definition/validation/traversal, mapping and serialisation toolkit for Python
Branch: development
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Added Enum field to documentation Apr 10, 2018
odin Updated docs/typing and some small tweaks Apr 10, 2018
tests Tests to ensure codecs are compatible with enums Apr 10, 2018
.checkignore Added tests to ignore list Jul 15, 2015
.codeclimate.yml Added code-climate config May 11, 2015
.coveragerc Ignore coverage from the inspect tool Apr 4, 2016
.gitignore Added .cache to .gitignore Jun 23, 2016
AUTHORS Update contributor details for thedrow Mar 25, 2018
LICENSE Fixes for build and publishing Apr 7, 2016
README.rst Drop python 2.6 and 3.4 from supported list Jun 29, 2017
requirements-dev.txt Update tox from 3.11.1 to 3.12.1 May 24, 2019
requirements-optional.txt Update arrow from 0.13.1 to 0.13.2 May 18, 2019
requirements.txt Pin enum34 to latest version 1.1.6 Apr 3, 2019
setup.cfg Merge branch 'development' into patch-1 Apr 4, 2019 Bumped minimum PBR version to 3, and included typing as requirement f… Sep 12, 2017



Odin provides a declarative framework for defining resources (classes) and their relationships, validation of the fields that make up the resources and mapping between objects (either a resource, or other python structures).

Odin also comes with built in serialisation tools for importing and exporting data from resources.

License Travis CI Status Code cov Code Health Requirements Status


  • Class based declarative style
  • Fields for building composite resources
  • Field and Resource level validation
  • Easy extension to support custom fields
  • Python 2.7 1, Python 2.7+, Python 3.5+ and PyPy 1 supported
  • Integration with Django (see baldr)
  • Support for documenting resources with Sphinx
  • Minimal dependencies (base functionality only requires six)

1 certain contrib items are not supported. Pint is not installable with PyPy.

Use cases

  • Design, document and validate complex (and simple!) data structures
  • Convert structures to and from different formats such as JSON, YAML, MsgPack or CSV
  • Validate API inputs
  • Define message formats for communications protocols, like an RPC
  • Map API requests to ORM objects

Quick links

Upcoming features

In development

  • XML Codec (export completed)
  • Complete documentation coverage
  • Improvements for CSV Codec (writing, reading multi resource CSV's)
  • RESTful interface with support for Flask and Django
  • Integration with other libraries (ie Django Models/Forms)
  • Integration with SQLAlchemy


  • six


  • simplejson - Odin will use simplejson if it is available or fallback to the builtin json library
  • msgpack-python - To enable use of the msgpack codec
  • pyyaml - To enable use of the YAML codec


  • jinja2 >= 2.7 - For documentation generation
  • pint - Support for physical quantities using the Pint library.


  • pytest - Testing
  • pytest-cov - Coverage reporting


With definition:

import odin

class Author(odin.Resource):
    name = odin.StringField()

class Publisher(odin.Resource):
    name = odin.StringField()

class Book(odin.Resource):
    title = odin.StringField()
    authors = odin.ArrayOf(Author)
    publisher = odin.DictAs(Publisher)
    genre = odin.StringField()
    num_pages = odin.IntegerField()
>>> b = Book(
        title="Consider Phlebas",
        genre="Space Opera",
>>> b.authors.append(Author(name="Iain M. Banks"))
>>> from odin.codecs import json_codec
>>> json_codec.dumps(b, indent=4)
    "$": "Book",
    "authors": [
            "$": "Author",
            "name": "Iain M. Banks"
    "genre": "Space Opera",
    "num_pages": 471,
    "publisher": {
        "$": "Publisher",
        "name": "Macmillan"
    "title": "Consider Phlebas"


Tim Savage

Special Mention

I would like to acknowledge the strong influence on the design of Odin Resources from the Django ORM and it's notable contributor Malcolm Tredinnick. He was a valued colleague who's untimely passing left a large void in our company and the wider community.

You can’t perform that action at this time.