Serialization for JSON and XML using typing
Project description
jetblack-serialization
Serialization for JSON and XML in Python using typing annotations.
Status
This is work in progress.
It has been tested with Python 3.7 used the typing_extensions
package for TypedDict
and Annotated
. In Python 3.8 the TypedDict
class is available in the standard typing
package.
Installation
The package can be installed with pip.
pip install jetblack-serialization
Overview
The package adds support for type annotations when serializing or deserializing JSON 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
This could be serialized to JSON as:
from stringcase import camelcase, snakecase
from jetblack_serialize import SerializerConfig
from jetblack_serialize.json import serialize
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(camelcase, snakecase, 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
We can deserialize the data as follows:
from stringcase import camelcase, snakecase
from jetblack_serialize import SerializerConfig
from jetblack_serialize.json import deserialize
dct = deserialize(
text,
Annotated[Book, JSONValue()],
SerializerConfig(camelcase, 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 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
To serialize we need to provide the containing tag Book
:
from stringcase import pascalcase, snakecase
from jetblack_serialize import SerializerConfig
from jetblack_serialize.xml import serialize
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(pascalcase, snakecase)
)
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
We can deserialize the XML as follows:
from stringcase import pascalcase, snakecase
from jetblack_serialize import SerializerConfig
from jetblack_serialize.xml import deserialize
dct = deserialize(
text,
Annotated[Book, XMLEntity("Book")],
SerializerConfig(pascalcase, 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-0.4.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d3f7b94dae7f9634764eb336793b4213546e79398799de59f12d3e0b9a482e3f |
|
MD5 | a3fa7a287db816f9b2a78cc4abec34b9 |
|
BLAKE2b-256 | a951a01cdc07a5d4495a27719a24688621b4703494f9940234d6ce6201d9ec2f |
Hashes for jetblack_serialization-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a91c0bf48a6ac69aabbbc324731ed06cca9b745f7fc489f7528ffc97125a673f |
|
MD5 | cbb11535b3ddea54dcca162bc3d9edb2 |
|
BLAKE2b-256 | ad50dfd88efed2096826ba7ae28c35be9d4610705f1dd29e3a45aa083a8ae266 |