Serialization for JSON and XML using typing
Project description
jetblack-serialization
Serialization for JSON, YAML and XML in Python using type annotations (read the docs).
Installation
This is a Python 3.8+ package.
The package can be installed with pip.
pip install jetblack-serialization
It has dependencies on the following packages:
By default, the dependencies for YAML and XML are not installed.
To install the dependencies for XML
(lxml
).
pip install jetblack-serialization[xml]
To install the dependencies for YAML (PyYAML
).
pip install jetblack-serialization[yaml]
To install the dependencies for all.
pip install jetblack-serialization[all]
Overview
The package adds support for type annotations when serializing or deserializing JSON, YAML or XML.
JSON
Given a typed dictionary:
from datetime import datetime
from typing import List, Optional, TypedDict, Union
class Book(TypedDict, total=False):
book_id: int
title: str
author: str
publication_date: datetime
keywords: List[str]
phrases: List[str]
age: Optional[Union[datetime, int]]
pages: Optional[int]
Serializing JSON
This could be serialized to JSON as:
from stringcase import camelcase
from jetblack_serialization.json import serialize, SerializerConfig
obj: Book = {
'author': 'Chairman Mao',
'book_id': 42,
'title': 'Little Red Book',
'publication_date': datetime(1973, 1, 1, 21, 52, 13),
'keywords': ['Revolution', 'Communism'],
'phrases': [
'Revolutionary wars are inevitable in class society',
'War is the continuation of politics'
],
'age': 24,
}
text = serialize(
obj,
Book,
SerializerConfig(key_serializer=camelcase, pretty_print=True)
)
print(text)
giving:
{
"bookId": 42,
"title": "Little Red Book",
"author": "Chairman Mao",
"publicationDate": "1973-01-01T21:52:13.00Z",
"keywords": ["Revolution", "Communism"],
"phrases": ["Revolutionary wars are inevitable in class society", "War is the continuation of politics"],
"age": 24,
"pages": null
}
Note the fields have been camel cased, and the publication date has been turned into an ISO 8601 date.
Deserializing JSON
We can deserialize the data as follows:
from stringcase import snakecase
from jetblack_serialization.json import deserialize, SerializerConfig
dct = deserialize(
text,
Annotated[Book, JSONValue()],
SerializerConfig(key_deserializer=snakecase)
)
YAML
YAML is a superset of JSON, so for serialization things are very similar.
Given a typed dictionary:
from datetime import datetime
from typing import List, Optional, TypedDict, Union
class Book(TypedDict, total=False):
book_id: int
title: str
author: str
publication_date: datetime
keywords: List[str]
phrases: List[str]
age: Optional[Union[datetime, int]]
pages: Optional[int]
Serializing YAML
This could be serialized to YAML as:
from stringcase import camelcase
from jetblack_serialization.yaml import serialize, SerializerConfig
obj: Book = {
'author': 'Chairman Mao',
'book_id': 42,
'title': 'Little Red Book',
'publication_date': datetime(1973, 1, 1, 21, 52, 13),
'keywords': ['Revolution', 'Communism'],
'phrases': [
'Revolutionary wars are inevitable in class society',
'War is the continuation of politics'
],
'age': 24,
}
text = serialize(
obj,
Book,
SerializerConfig(key_serializer=camelcase, pretty_print=True)
)
print(text)
giving:
bookId: 42
title: Little Red Book
author: Chairman Mao
publicationDate: '1973-01-01T21:52:13.00Z'
keywords:
- Revolution
- Communism
phrases:
- Revolutionary wars are inevitable in class society
- War is the continuation of politics
age: 24
pages: null
Note the fields have been camel cased, and the publication date has been turned into an ISO 8601 date.
Deserializing YAML
We can deserialize the data as follows:
from stringcase import snakecase
from jetblack_serialization.yaml import deserialize, SerializerConfig
dct = deserialize(
text,
Annotated[Book, JSONValue()],
SerializerConfig(key_deserializer=snakecase)
)
XML
The XML version of the typed dictionary might look like this:
from datetime import datetime
from typing import List, Optional, TypedDict, Union
from typing_extensions import Annotated
from jetblack_serialization.xml import XMLEntity, XMLAttribute
class Book(TypedDict, total=False):
book_id: Annotated[int, XMLAttribute("bookId")]
title: str
author: str
publication_date: datetime
keywords: Annotated[List[Annotated[str, XMLEntity("Keyword")]], XMLEntity("Keywords")]
phrases: List[str]
age: Optional[Union[datetime, int]]
pages: Optional[int]
Note we have introduced some annotations to control the serialization. For XML we have used pascal-case to serialized the keys and snake-case for deserialization.
Serializing XML
To serialize we need to provide the containing tag Book
:
from stringcase import pascalcase
from jetblack_serialization.xml import serialize, SerializerConfig
book: Book = {
'author': 'Chairman Mao',
'book_id': 42,
'title': 'Little Red Book',
'publication_date': datetime(1973, 1, 1, 21, 52, 13),
'keywords': ['Revolution', 'Communism'],
'phrases': [
'Revolutionary wars are inevitable in class society',
'War is the continuation of politics'
],
'age': 24,
'pages': None
}
text = serialize(
book,
Annotated[Book, XMLEntity("Book")],
SerializerConfig(key_serializer=pascalcase)
)
print(text)
Producing:
<Book bookId="42">
<Title>Little Red Book</Title>
<Author>Chairman Mao</Author>
<PublicationDate>1973-01-01T21:52:13.00Z</PublicationDate>
<Keywords>
<Keyword>Revolution</Keyword>
<Keyword>Communism</Keyword>
</Keywords>
<Phrase>Revolutionary wars are inevitable in class society</Phrase>
<Phrase>War is the continuation of politics</Phrase>
<Age>24</Age>
</Book>'
The annotations are more elaborate here. However, much of the typed dictionary requires no annotation.
First we needed the outer document wrapper XMLEntity("Book")
.
Next we annotated the book_id
to be an XMLAttribute
.
Finally we annotated the two lists differently. The keywords
list used
a nested structure, which we indicated by giving the list a different
XMLEntity
tag to the list items. For the phrases we used the default
in-line behaviour.
Deserializing XML
We can deserialize the XML as follows:
from stringcase import snakecase
from jetblack_serialization.xml import deserialize, SerializerConfig
dct = deserialize(
text,
Annotated[Book, XMLEntity("Book")],
SerializerConfig(key_deserializer=snakecase)
)
Attributes
For JSON, attributes are typically not required. However
JSONProperty(tag: str)
and JSONValue()
are provided for
completeness.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jetblack_serialization-4.0.0a0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f90a5e8c43bd92ac2361322316205e575cf4b89098c4f75b2daad058d0bb7fa1 |
|
MD5 | 9c4ea315f9c775da8ea766edc3aa8363 |
|
BLAKE2b-256 | 20e0b869381d60fec233fab22171aa9e25165d9b9dfdc4574cbdfc7fbc5b9aef |
Hashes for jetblack_serialization-4.0.0a0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 41610278c8b06c59fcddcce2ede5815eff5582dec5f0c0ab7a6715ca38834fab |
|
MD5 | 21fa2bc2bc6fcc38bfd6b0f7d9fd903e |
|
BLAKE2b-256 | 4ae4b24d67bfebf2176430396d3ded815fe93482baeab11f952dc66c825bc86f |