Install & Compatibility
Where this runs
tested against v1.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.122s · 89.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.120s · 86MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ClassType
✓ from jsonconversion import ClassType
✗ from jsonconversion import JSONObject
PackageNotFoundError
✓ from jsonconversion import PackageNotFoundError
get_all_args
✓ from jsonconversion import get_all_args
This quickstart demonstrates how to define a custom class inheriting from `JSONObject`, implement the required `to_dict` and `from_dict` methods, and then use `JSONObjectEncoder` and `JSONObjectDecoder` with the standard `json` module to serialize and deserialize instances of your custom class.
import json
from jsonconversion import JSONObject, JSONObjectEncoder, JSONObjectDecoder
# 1. Define a class that inherits from JSONObject
class MyCustomObject(JSONObject):
def __init__(self, name: str, value: int):
self.name = name
self.value = value
# Required: Convert object to a dictionary for serialization
def to_dict(self) -> dict:
return {"name": self.name, "value": self.value}
# Required: Create an object from a dictionary for deserialization
@classmethod
def from_dict(cls, data: dict):
return cls(name=data["name"], value=data["value"])
def __eq__(self, other):
if not isinstance(other, MyCustomObject):
return NotImplemented
return self.name == other.name and self.value == other.value
def __repr__(self):
return f"MyCustomObject(name='{self.name}', value={self.value})"
# 2. Create an instance of your custom object
original_obj = MyCustomObject("example", 123)
print(f"Original object: {original_obj}")
# 3. Encode the object to a JSON string
# Use the JSONObjectEncoder with json.dumps
encoded_json = json.dumps(original_obj, cls=JSONObjectEncoder, indent=2)
print(f"\nEncoded JSON:\n{encoded_json}")
# 4. Decode the JSON string back to an object
# Use the JSONObjectDecoder with json.loads
decoded_obj = json.loads(encoded_json, cls=JSONObjectDecoder)
print(f"\nDecoded object: {decoded_obj}")
# 5. Verify the conversion
print(f"Objects are equal (by value): {original_obj == decoded_obj}")
print(f"Objects are identical (memory address): {original_obj is decoded_obj}")
Debug
Known issues
breakingVersion 1.0.0 introduced a significant breaking change by moving to Python 3. This means that versions prior to 1.0.0 are Python 2 compatible, while 1.0.0 and later are exclusively for Python 3.fixUpgrade your Python environment to Python 3 and update your codebase to be Python 3 compatible before upgrading to jsonconversion >= 1.0.0.
affects: <1.0.0
breakingStarting with version 1.0.2, the minimum required Python version for the library is Python 3.9. Attempting to use it with older Python 3 versions (e.g., 3.7, 3.8) will result in installation or runtime errors.fixEnsure your project's Python interpreter is version 3.9 or higher.
affects: >=1.0.2
gotchaFor custom Python objects to be serializable/deserializable by `jsonconversion`, they must inherit from `jsonconversion.JSONObject` and implement both the `to_dict()` and `from_dict()` methods. Failure to do so will result in `TypeError` during encoding or decoding.fixEnsure your custom classes follow the `JSONObject` interface by inheriting and implementing `to_dict()` (to convert to a dictionary) and a `@classmethod from_dict()` (to reconstruct from a dictionary).
affects: All versions
gotchaWhen decoding JSON strings back into custom Python objects, `jsonconversion` relies on importing the original module path stored in the JSON. If the module containing your custom `JSONObject` subclass is not discoverable within your `PYTHONPATH` during deserialization, an `ImportError` or `ModuleNotFoundError` will occur.fixEnsure that the Python environment where decoding happens has access to the modules defining your `JSONObject` subclasses (e.g., by being in the `PYTHONPATH` or properly installed).
affects: All versions
breakingThe `jsonconversion` library might not be fully compatible with Python 3.13 or newer versions, potentially leading to ImportErrors for core components like `JSONObject`. The library's support for the latest Python versions may not be guaranteed.fixUse a Python environment with a version explicitly supported by `jsonconversion`, such as Python 3.12 or older, until official support for Python 3.13+ is confirmed.
affects: All versions (when used with Python 3.13+)
Upgrade
Version history
1.2.1latest on PyPI · released Nov 12, 2025
Audit
Dependencies
numpyrequiredRequired for certain internal operations and object types.