Skip to content
Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time


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.

Docs/ Help ReadTheDocs
Build Python package Dependabot Status
Quality Maintainability Security Test Coverage Once you go Black...
Package Latest Version PyPI - Wheel


  • 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.6+ and PyPy 1 supported
  • 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, CSV, TOML
  • 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)
  • 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
  • toml - To enable use of the TOML 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