Databind Core

Common errors

• ModuleNotFoundError: No module named 'databind.json'

  cause Attempting to import `databind.json` after `databind-core`'s JSON functionality was moved into the new, consolidated `databind` package.
  fix Install the `databind` package (`pip install databind`) and ensure your import statement is `from databind.json import load, dump`.

• RecursionError: maximum recursion depth exceeded while calling a Python object

  cause This error often occurs in older `databind-core` versions (prior to 4.5.4) due to a bug where `Union` settings inherited through the Method Resolution Order (MRO) would cause an infinite recursion loop during de/serialization.
  fix Upgrade `databind-core` to version 4.5.4 or higher, or preferably, migrate to the `databind` package.

• TypeError: Cannot deserialize into a generic type without type arguments.

  cause When deserializing into a dataclass that inherits from an uninstantiated `Generic` type, older `databind-core` versions (prior to 4.5.3) could fail to correctly resolve and serialize all fields.
  fix Upgrade `databind-core` to version 4.5.3 or higher, or migrate to the `databind` package.

Warnings

• deprecated The `databind-core` package is officially deprecated. All new development and maintenance will focus on the unified `databind` package. Users should migrate to `databind` for continued support and new features.
  Fix: Uninstall `databind-core` (`pip uninstall databind-core`) and install `databind` (`pip install databind`). Update import paths accordingly (e.g., `from databind.json import load, dump`).
• breaking Version 4.5.0 of `databind-core` dropped support for Python 3.6 and 3.7. Attempting to use this version on unsupported Python versions will lead to installation or runtime errors.
  Fix: Upgrade your Python environment to 3.8 or newer, or pin `databind-core` to a version older than 4.5.0 if Python 3.6/3.7 support is strictly required (not recommended due to deprecation).
• gotcha Prior to version 4.5.4, `Union` settings inherited via MRO could cause `RecursionError` during serialization/deserialization, especially with complex inheritance hierarchies involving `Union` types.
  Fix: Upgrade to `databind-core` version 4.5.4 or later, or migrate to the `databind` package.
• gotcha Prior to version 4.5.3, dataclasses inheriting from uninstantiated `Generic` types might not have all their fields correctly serialized, leading to incomplete output.
  Fix: Upgrade to `databind-core` version 4.5.3 or later, or migrate to the `databind` package.
• gotcha Before version 4.5.3, `Union` types containing `typing.Literal` were unable to correctly de/serialize, resulting in errors when processing data that matched these patterns.
  Fix: Upgrade to `databind-core` version 4.5.3 or later, or migrate to the `databind` package.

Install

• pip install databind-core Install databind-core (deprecated)
• pip install databind Install databind (recommended successor)

Imports

• load, dump
  wrong:

  from databind.core.json import load, dump

  correct:

  from databind.json import load, dump

  The `load` and `dump` functions for JSON de/serialization are now part of the `databind.json` module within the `databind` package. `databind-core` no longer directly exposes these.
• dataclass

  from dataclasses import dataclass

  `dataclass` is a standard library feature, essential for defining data structures that `databind` processes.

Quickstart

This quickstart demonstrates basic JSON de/serialization using the `databind` package, which is the recommended successor to `databind-core`. It shows how to define dataclasses and use `load` and `dump` for conversion between dictionaries and dataclass instances.

from dataclasses import dataclass
from databind.json import dump, load
import os

# Note: This quickstart uses the 'databind' package (the recommended successor)
# as 'databind-core' is deprecated and its JSON functionality has moved.

@dataclass
class Server:
    host: str
    port: int

@dataclass
class Config:
    server: Server

# Example payload
dict_payload = {"server": {"host": "localhost", "port": 8080}}

# Load data into a dataclass instance
loaded_config = load(dict_payload, Config)
print(f"Loaded Config: {loaded_config}")

# Dump a dataclass instance back to a dictionary
dumped_payload = dump(loaded_config, Config)
print(f"Dumped Payload: {dumped_payload}")

assert loaded_config == Config(server=Server(host="localhost", port=8080))
assert dumped_payload == dict_payload