Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/python-odin/odin
Data-structure definition/validation/traversal, mapping and serialisation toolkit for Python
https://github.com/python-odin/odin
csv data-mapping data-structures de-serialize json msgpack python serialize validation xml yaml
Last synced: 13 days ago
JSON representation
Data-structure definition/validation/traversal, mapping and serialisation toolkit for Python
- Host: GitHub
- URL: https://github.com/python-odin/odin
- Owner: python-odin
- License: bsd-3-clause
- Created: 2013-08-20T09:00:16.000Z (about 11 years ago)
- Default Branch: development
- Last Pushed: 2024-07-09T19:14:59.000Z (4 months ago)
- Last Synced: 2024-10-01T06:55:02.122Z (about 1 month ago)
- Topics: csv, data-mapping, data-structures, de-serialize, json, msgpack, python, serialize, validation, xml, yaml
- Language: Python
- Homepage: https://odin.readthedocs.org/en/latest/
- Size: 1.83 MB
- Stars: 38
- Watchers: 3
- Forks: 11
- Open Issues: 11
-
Metadata Files:
- Readme: README.rst
- Changelog: HISTORY
- Funding: .github/FUNDING.yml
- License: LICENSE
- Authors: AUTHORS
Awesome Lists containing this project
README
####
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 `_
* 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 `_
* `Project home `_
* `Issue tracker `_
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 `_ 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"
}