jdataclass is a Python module that extends the functionality of Python's native dataclasses by allowing custom mappings for reading from dataclass objects and writing to other objects during serialization and deserialization. With jdataclass, you can easily control how data is mapped between your dataclass and external data sources like JSON, databases, or other data formats.
You can install jdataclass using pip:
pip install jdataclass
Here's a guide on how to use jdataclass in your Python projects.
Create a dataclass as you normally would, and use jfield and jproperty annotations to specify custom mappings for your fields and properties.
from dataclasses import dataclass, field
from jdataclass import jfield
@dataclass
class Person:
first_name: str = jfield(path="firstName")
last_name: str = jfield(path="lastName")
age: int = field(default=0)
In the example above, we have defined a dataclass, Person
. This dataclass uses jfield
annotations to specify custom field mappings.
You can now serialize and deserialize your dataclasses using jdataclass:
>>> from jdataclass import asdict
>>> person = Person(first_name="John", last_name="Doe", age=30)
>>> asdict(person) # Serialize Person to JSON
{'firstName': 'John', 'lastName': 'Doe', 'age': 30}
>>> from jdataclass import create
>>> json_data = {
... "firstName": "Jane",
... "lastName": "Doe",
... "age": 25
... }
>>> create(Person, json_data) # Deserialize JSON to Person
Person(first_name='Jane', last_name='Doe', age=25)
jdataclass provides several functions to work with custom mappings and dataclass objects:
JField
: Holds options for a field, used during serialization and deserialization.JFieldOptions
: dataclass that is added to a field metadata and is used to create aJField
.JProperty
: A descriptor that replaces the getters and setters for a jproperty.jfield
: Factory function to create a Field with the metadata that JField needs.jfields
: Function that returns all jfields defined of a given class.jproperty
: A decorator to specify custom property mappings for a dataclass property.jproperties
: A function that returns all jproperties of a given class.create
: Create a dataclass object from a dictionary of data using custom mappings.asdict
: Serialize a dataclass object to a dictionary using custom mappings.convert
: Converts one dataclass to another.
Sometimes we need to map the result of a function to a field in the serialized object or have custom functionality when deserializing a field.
For these scenarios jproperties allow us to define read-only or read-write operations that happen during deserialization and/or serialization.
Consider the following JSON response from the Purview Azure SDK
:
{
"friendlyName": "SubCollection",
"name": "000001",
"parentCollection": {
"referenceName": "000000",
"type": "CollectionReference"
}
}
The property parentCollection
contains the name
of the parent collection and a type
that is fixed to CollectionReference
.
We can create a jdataclass that represents these mappings as follows:
from dataclasses import dataclass
from jdataclass import jfield, jproperty
from typing import Any, Optional
@dataclass
class PurviewCollection:
name: str
friendly_name: str = jfield(path="friendlyName")
parent_name: Optional[str] = jfield(
path="parentCollection.referenceName",
default=None,
)
@jproperty(path="parentCollection.type")
def collection_reference(self):
return "CollectionReference"
...
>>> from jdataclass import create
>>> json_data = {'name': '000001', 'friendlyName': 'SubCollection', 'parentCollection': {'referenceName': '000000', 'type': 'CollectionReference'}}
>>> create(PurviewCollection, json_data) # Deserialize JSON to PurviewCollection
PurviewCollection(name='000001', friendly_name='SubCollection', parent_name='000000')
>>> from jdataclass import asdict
>>> collection = PurviewCollection(name='000001', friendly_name='SubCollection', parent_name='000000')
>>> asdict(collection) # Serialize PurviewCollection to JSON
{'name': '000001', 'friendlyName': 'SubCollection', 'parentCollection': {'referenceName': '000000', 'type': 'CollectionReference'}}
Sometimes we need to interfere with the serialization process for custom post processing of the generated dict.
Considering the previous example, assume a collection that has no parent. We would like the generated JSON to drop the parentCollection
property entirelly.
So, let's change the class a little and add a new method called __post_asdict__
...
@dataclass
class PurviewCollection:
...
def __post_asdict__(self, data: dict[str, Any]) -> dict[str, Any]:
if self.parent_name is None:
del data["parentCollection"]
return data
>>> from jdataclass import asdict
>>> collection = PurviewCollection(name='000000', friendly_name='Root', parent_name=None)
>>> asdict(collection) # Serialize PurviewCollection to JSON
{'name': '000000', 'friendlyName': 'Root'}
__post_asdict__
method is called just after all fields and properties have been initialized.
The dataclass
native __post_init__
method can be used for post deserialization.
Consider the previous example, collections from the Purview
api are returned with only the referenceName
for the parent collection. Let's say we want to make the hierarchy explicit by combining collections by parent_name
. We can accomplish this after serialization with somthing like the following:
json_data = {
"value": [
{
"friendlyName": "Root",
"name": "000000",
},
{
"friendlyName": "SubCollection",
"name": "000001",
"parentCollection": {
"referenceName": "000000",
"type": "CollectionReference",
},
},
],
}
...
@dataclass
class PurviewCollection:
...
collections: list["PurviewCollection"] = jfield(
init=False,
default_factory=list,
)
parent: Optional["PurviewCollection"] = jfield(
init=False,
default=None,
)
...
@dataclass
class PurviewResponse:
root: Optional[PurviewCollection] = jfield(init=False)
collections: list[PurviewCollection] = jfield(
path="value",
default_factory=list,
)
def __post_init__(self):
by_name = {c.name: c for c in self.collections}
for c in self.collections:
if c.parent_name and (parent := by_name.get(c.parent_name)):
c.parent = parent
parent.collections.append(c)
else:
self.root = c
>>> from jdataclass import create
>>> response = create(PurviewResponse, json_data) # Deserialize JSON to PurviewResponse
>>> response.root
PurviewCollection(name='000000', friendly_name='Root', collections=[PurviewCollection(name='000001', friendly_name='SubCollection', parent_name='000000')], parent_name=None)
Sometimes we need to convert a dataclass that maps an external api to an internal mapper to save the data in a different format.
Consider the previous example, now we would like to store the contents of a PurviewCollection
as a different format like the following:
@dataclass
class LocalCollection:
name: str
friendly_name: str = jfield(path="friendlyName")
collections: list["LocalCollection"] = jfield(default_factory=list)
parent: Optional["LocalCollection"] = jfield(
parent_ref=True,
default=None,
)
@property
def parent_name(self) -> Optional[str]:
return self.parent and self.parent.name
We can easily convert a PurviewCollection
to such class by using the convert
function. It will copy all fields defined in the LocalCollection
from the given instance of PurviewCollection
.
>>> from jdataclass import convert
>>> response = create(PurviewResponse, json_data) # Deserialize JSON to PurviewResponse
>>> collection = convert(response.root, LocalCollection)
>>> collection
LocalCollection(name='000000', friendly_name='Root', collections=[LocalCollection(name='000001', friendly_name='SubCollection', collections=[], parent=...)], parent=None)
>>> asdict(collection)
{'name': '000000', 'friendlyName': 'Root', 'collections': [{'name': '000001', 'friendlyName': 'SubCollection', 'collections': []}]}
If you encounter any issues, have questions, or want to contribute to jdataclass, please visit our GitHub repository. We welcome your feedback and contributions.
jdataclass is licensed under the MIT License. See the LICENSE file for more details.
Thank you for using jdataclass! We hope this library simplifies the process of custom data mappings for your dataclass objects.