####
Odin
####
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/ | .. image:: https://readthedocs.org/projects/odin/badge/?version=latest |
| Help | :target: https://odin.readthedocs.org/ |
| | :alt: ReadTheDocs |
| | .. image:: https://img.shields.io/badge/gitterim-timsavage.odin-brightgreen.svg?style=flat |
| | :target: https://gitter.im/timsavage/odin |
| | :alt: Gitter.im |
+---------+-------------------------------------------------------------------------------------------------------------+
| Build | .. image:: https://github.com/python-odin/odin/actions/workflows/python-package.yml/badge.svg |
| | :target: https://github.com/python-odin/odin/actions/workflows/python-package.yml |
| | :alt: Python package |
+---------+-------------------------------------------------------------------------------------------------------------+
| Quality | .. image:: https://sonarcloud.io/api/project_badges/measure?project=python-odin_odin&metric=sqale_rating |
| | :target: https://sonarcloud.io/dashboard?id=python-odin_odin |
| | :alt: Maintainability |
| | .. image:: https://sonarcloud.io/api/project_badges/measure?project=python-odin_odin&metric=security_rating |
| | :target: https://sonarcloud.io/project/security_hotspots |
| | :alt: Security |
| | .. image:: https://sonarcloud.io/api/project_badges/measure?project=python-odin_odin&metric=coverage |
| | :target: https://sonarcloud.io/code?id=python-odin_odin |
| | :alt: Test Coverage |
| | .. image:: https://img.shields.io/badge/code%20style-black-000000.svg |
| | :target: https://github.com/ambv/black |
| | :alt: Once you go Black... |
+---------+-------------------------------------------------------------------------------------------------------------+
| Package | .. image:: https://img.shields.io/pypi/v/odin |
| | :target: https://pypi.io/pypi/odin/ |
| | :alt: Latest Version |
| | .. image:: https://img.shields.io/pypi/pyversions/odin |
| | :target: https://pypi.io/pypi/odin/ |
| | .. image:: https://img.shields.io/pypi/l/odin |
| | :target: https://pypi.io/pypi/odin/ |
| | .. image:: https://img.shields.io/pypi/wheel/odin |
| | :alt: PyPI - Wheel |
| | :target: https://pypi.io/pypi/odin/ |
+---------+-------------------------------------------------------------------------------------------------------------+
Highlights
**********
* Class based declarative style
* Class based annotations style! ✨ new in 2.0
* Fields for building composite resources
* Field and Resource level validation
* Easy extension to support custom fields
* Python 3.8+ and PyPy :sup:`1` supported
* Support for documenting resources with `Sphinx <http://sphinx-doc.org/>`_
* Minimal dependencies
:sup:`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
***********
* `Documentation <https://odin.readthedocs.org/>`_
* `Project home <https://github.com/python-odin/odin>`_
* `Issue tracker <https://github.com/python-odin/odin/issues>`_
Upcoming features
*****************
**In development**
* XML Codec (export only)
* Complete documentation coverage
* Improvements for CSV Codec (writing, reading multi resource CSV's)
Requires
********
**Optional**
* 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
**Contrib**
* arrow - Support for Arrow data types.
* pint - Support for physical quantities using the `Pint <http://pint.readthedocs.org/>`_ library.
**Development**
* pytest - Testing
* pytest-cov - Coverage reporting
Example
*******
**Definition**
.. code-block:: python
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()
**Using Annotations**
.. code-block:: python
import odin
class Author(odin.AnnotatedResource):
name: str
class Publisher(odin.AnnotatedResource):
name: str
website: Optional[odin.Url]
class Book(odin.AnnotatedResource):
title: str
authors: List[Author]
publisher: Publisher
genre: str
num_pages: int
**Usage**::
>>> b = Book(
title="Consider Phlebas",
genre="Space Opera",
publisher=Publisher(name="Macmillan"),
num_pages=471
)
>>> 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"
}
Raw data
{
"_id": null,
"home_page": "https://github.com/python-odin/odin",
"name": "odin",
"maintainer": null,
"docs_url": "https://pythonhosted.org/odin/",
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "data-structure, validation, data-mapping",
"author": "Tim Savage",
"author_email": "tim@savage.company",
"download_url": "https://files.pythonhosted.org/packages/8f/4a/a177ebb8ee2592466d5223ce3cd5bed8638398ada02f394288c6e0bab547/odin-2.10.tar.gz",
"platform": null,
"description": "\n####\nOdin\n####\n\nOdin provides a declarative framework for defining resources (classes) and their relationships, validation of the fields\nthat make up the resources and mapping between objects (either a resource, or other python structures).\n\nOdin also comes with built in serialisation tools for importing and exporting data from resources.\n\n+---------+-------------------------------------------------------------------------------------------------------------+\n| Docs/ | .. image:: https://readthedocs.org/projects/odin/badge/?version=latest |\n| Help | :target: https://odin.readthedocs.org/ |\n| | :alt: ReadTheDocs |\n| | .. image:: https://img.shields.io/badge/gitterim-timsavage.odin-brightgreen.svg?style=flat |\n| | :target: https://gitter.im/timsavage/odin |\n| | :alt: Gitter.im |\n+---------+-------------------------------------------------------------------------------------------------------------+\n| Build | .. image:: https://github.com/python-odin/odin/actions/workflows/python-package.yml/badge.svg |\n| | :target: https://github.com/python-odin/odin/actions/workflows/python-package.yml |\n| | :alt: Python package |\n+---------+-------------------------------------------------------------------------------------------------------------+\n| Quality | .. image:: https://sonarcloud.io/api/project_badges/measure?project=python-odin_odin&metric=sqale_rating |\n| | :target: https://sonarcloud.io/dashboard?id=python-odin_odin |\n| | :alt: Maintainability |\n| | .. image:: https://sonarcloud.io/api/project_badges/measure?project=python-odin_odin&metric=security_rating |\n| | :target: https://sonarcloud.io/project/security_hotspots |\n| | :alt: Security |\n| | .. image:: https://sonarcloud.io/api/project_badges/measure?project=python-odin_odin&metric=coverage |\n| | :target: https://sonarcloud.io/code?id=python-odin_odin |\n| | :alt: Test Coverage |\n| | .. image:: https://img.shields.io/badge/code%20style-black-000000.svg |\n| | :target: https://github.com/ambv/black |\n| | :alt: Once you go Black... |\n+---------+-------------------------------------------------------------------------------------------------------------+\n| Package | .. image:: https://img.shields.io/pypi/v/odin |\n| | :target: https://pypi.io/pypi/odin/ |\n| | :alt: Latest Version |\n| | .. image:: https://img.shields.io/pypi/pyversions/odin |\n| | :target: https://pypi.io/pypi/odin/ |\n| | .. image:: https://img.shields.io/pypi/l/odin |\n| | :target: https://pypi.io/pypi/odin/ |\n| | .. image:: https://img.shields.io/pypi/wheel/odin |\n| | :alt: PyPI - Wheel |\n| | :target: https://pypi.io/pypi/odin/ |\n+---------+-------------------------------------------------------------------------------------------------------------+\n\n\nHighlights\n**********\n\n* Class based declarative style\n* Class based annotations style! \u2728 new in 2.0\n* Fields for building composite resources\n* Field and Resource level validation\n* Easy extension to support custom fields\n* Python 3.8+ and PyPy :sup:`1` supported\n* Support for documenting resources with `Sphinx <http://sphinx-doc.org/>`_\n* Minimal dependencies\n\n:sup:`1` certain contrib items are not supported. Pint is not installable with PyPy.\n\nUse cases\n*********\n* Design, document and validate complex (and simple!) data structures\n* Convert structures to and from different formats such as JSON, YAML, MsgPack, CSV, TOML\n* Validate API inputs\n* Define message formats for communications protocols, like an RPC\n* Map API requests to ORM objects\n\nQuick links\n***********\n\n* `Documentation <https://odin.readthedocs.org/>`_\n* `Project home <https://github.com/python-odin/odin>`_\n* `Issue tracker <https://github.com/python-odin/odin/issues>`_\n\n\nUpcoming features\n*****************\n\n**In development**\n\n* XML Codec (export only)\n* Complete documentation coverage\n* Improvements for CSV Codec (writing, reading multi resource CSV's)\n\n\nRequires\n********\n\n**Optional**\n\n* simplejson - Odin will use simplejson if it is available or fallback to the builtin json library\n* msgpack-python - To enable use of the msgpack codec\n* pyyaml - To enable use of the YAML codec\n* toml - To enable use of the TOML codec\n\n**Contrib**\n\n* arrow - Support for Arrow data types.\n* pint - Support for physical quantities using the `Pint <http://pint.readthedocs.org/>`_ library.\n\n**Development**\n\n* pytest - Testing\n* pytest-cov - Coverage reporting\n\nExample\n*******\n\n**Definition**\n\n.. code-block:: python\n\n import odin\n\n class Author(odin.Resource):\n name = odin.StringField()\n\n class Publisher(odin.Resource):\n name = odin.StringField()\n\n class Book(odin.Resource):\n title = odin.StringField()\n authors = odin.ArrayOf(Author)\n publisher = odin.DictAs(Publisher)\n genre = odin.StringField()\n num_pages = odin.IntegerField()\n\n**Using Annotations**\n\n.. code-block:: python\n\n import odin\n\n class Author(odin.AnnotatedResource):\n name: str\n\n class Publisher(odin.AnnotatedResource):\n name: str\n website: Optional[odin.Url]\n\n class Book(odin.AnnotatedResource):\n title: str\n authors: List[Author]\n publisher: Publisher\n genre: str\n num_pages: int\n\n**Usage**::\n\n >>> b = Book(\n title=\"Consider Phlebas\",\n genre=\"Space Opera\",\n publisher=Publisher(name=\"Macmillan\"),\n num_pages=471\n )\n >>> b.authors.append(Author(name=\"Iain M. Banks\"))\n >>> from odin.codecs import json_codec\n >>> json_codec.dumps(b, indent=4)\n {\n \"$\": \"Book\",\n \"authors\": [\n {\n \"$\": \"Author\",\n \"name\": \"Iain M. Banks\"\n }\n ],\n \"genre\": \"Space Opera\",\n \"num_pages\": 471,\n \"publisher\": {\n \"$\": \"Publisher\",\n \"name\": \"Macmillan\"\n },\n \"title\": \"Consider Phlebas\"\n }\n\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Data-structure definition/validation/traversal, mapping and serialisation toolkit for Python",
"version": "2.10",
"project_urls": {
"Documentation": "https://odin.readthedocs.org",
"Homepage": "https://github.com/python-odin/odin",
"Repository": "https://github.com/python-odin/odin"
},
"split_keywords": [
"data-structure",
" validation",
" data-mapping"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a101af536c687a49d52200c3f2f5f911194f077b9042aa8dfdb51ad7aab69f4",
"md5": "77cf64577496e531169eb83adf3cb516",
"sha256": "3ae643aaa655805478b22708fd7456b21a62f00104e634ae6dac3a68be872b7a"
},
"downloads": -1,
"filename": "odin-2.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77cf64577496e531169eb83adf3cb516",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 93447,
"upload_time": "2024-05-13T01:07:27",
"upload_time_iso_8601": "2024-05-13T01:07:27.361776Z",
"url": "https://files.pythonhosted.org/packages/5a/10/1af536c687a49d52200c3f2f5f911194f077b9042aa8dfdb51ad7aab69f4/odin-2.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f4aa177ebb8ee2592466d5223ce3cd5bed8638398ada02f394288c6e0bab547",
"md5": "9efa32324346e11b182d9eebd6496100",
"sha256": "4e94ac2acd3168a25323d80a9ef26220aeaf4d7967ec9b637f9585f2d0b94edf"
},
"downloads": -1,
"filename": "odin-2.10.tar.gz",
"has_sig": false,
"md5_digest": "9efa32324346e11b182d9eebd6496100",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 113049,
"upload_time": "2024-05-13T01:07:29",
"upload_time_iso_8601": "2024-05-13T01:07:29.538305Z",
"url": "https://files.pythonhosted.org/packages/8f/4a/a177ebb8ee2592466d5223ce3cd5bed8638398ada02f394288c6e0bab547/odin-2.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 01:07:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "python-odin",
"github_project": "odin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "odin"
}
JSON
