Dataclasses JSON is a Python library that provides a simple API for easily serializing dataclasses to and from JSON. It leverages the built-in `dataclasses` module and internally uses `marshmallow` for robust schema generation and deserialization, supporting complex types like nested dataclasses and various collections. The current version is 0.6.7, and it maintains an active release cadence with frequent bug fixes and feature enhancements.
pip install dataclasses-jsonVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates the core functionality of `dataclasses-json` using the `@dataclass_json` decorator. It shows how to serialize dataclass instances to JSON strings and deserialize JSON strings back into dataclass instances. An example of converting field names to camelCase for JSON representation is also included.
Upgrade to v0.6.0 or higher. For complex Union types, ensure your data has sufficient information for `dataclasses-json` to infer the correct type, or provide custom decoding logic.
Review type hint usage for complexity. If encountering 'Unknown type' warnings with `from __future__ import annotations`, consider separating dataclass definitions into files without this import, or explicitly providing Marshmallow fields via `mm_field` metadata for problematic fields.
Always use timezone-aware `datetime` objects for predictable serialization/deserialization, or implement custom encoders/decoders (e.g., for ISO 8601 string format) if exact inverse behavior or specific timezone handling is required.
Upgrade to v0.6.5 or a newer version to ensure proper deserialization of generic dataclasses.
Avoid overriding `__init__` directly. Instead, use `__post_init__` for post-initialization logic. If `__init__` must be overridden, ensure all dataclass fields are correctly initialized.
Provide a default value for the field in the dataclass (e.g., `field_name: Optional[str] = None`). Alternatively, if the field should genuinely be optional and infer `None` if missing, use `infer_missing=True` when calling `from_dict` or `from_json`. For example: `YourDataclass.from_json(json_string, infer_missing=True)`.
Ensure the types in your JSON string precisely match the type hints in your dataclass. For missing required fields, provide them in the JSON string. If a field can be optional, define it as `Optional[Type]` and either provide `null` in the JSON or ensure `infer_missing=True` is used with `from_json`/`from_dict` (though `schema().loads` will still apply Marshmallow's validation rules).
Always provide explicit type arguments for generic types. For example, change `field: tuple` to `field: Tuple[int, str]` or `field: tuple[int, str]` (using `from typing import Tuple` if on Python < 3.9).
Ensure that the `@dataclass_json` decorator is applied *first*, followed by `@dataclass`. The correct order is:
```python
from dataclasses import dataclass
from dataclasses_json import dataclass_json
@dataclass_json
@dataclass
class MyDataClass:
field_a: str
field_b: int
```