Install & Compatibility
Where this runs
tested against v0.4.4 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.041s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.035s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
json
✓ from json_encoder import json
Provides the primary `dumps` and `loads` functions, enhanced with singledispatch.
use_json_library
✓ from json_encoder import use_json_library
Used to globally configure the underlying JSON library (e.g., simplejson, ujson).
json_encoder.register
✓ from json_encoder.encoder import json_encoder
@json_encoder.register(MyCustomType)
Decorator for registering custom serialization functions for specific types.
This quickstart demonstrates how to use `json-encoder` for basic data types that are typically not JSON-serializable (like `datetime`, `Decimal`, `UUID`), and how to register a custom serialization function for your own classes using the `singledispatch` decorator. It also shows how to optionally switch the underlying JSON library.
from datetime import datetime, date
from decimal import Decimal
from fractions import Fraction
from uuid import UUID
from json_encoder import json
from json_encoder import use_json_library
from json_encoder.encoder import json_encoder
# Optionally configure a specific JSON backend (e.g., ujson if installed)
try:
import ujson
use_json_library(ujson)
print("Using ujson backend")
except ImportError:
print("ujson not found, using default json backend")
# 1. Basic usage with built-in enhanced types
data = {
'now': datetime.now(),
'today': date.today(),
'money': Decimal('123.45'),
'id': UUID('12345678-1234-5678-1234-567812345678'),
'value': 1.23 # will be handled as Decimal due to float parsing
}
encoded_data = json.dumps(data, indent=2)
print("\nEncoded data with default handlers:")
print(encoded_data)
# 2. Registering a custom type handler using singledispatch
class MyCustomType:
def __init__(self, name, value):
self.name = name
self.value = value
@json_encoder.register(MyCustomType)
def encode_my_custom_type(obj: MyCustomType):
return {
'custom_name': obj.name,
'custom_value': obj.value,
'type_info': 'MyCustomType serialized'
}
custom_data = {'item': MyCustomType('test', 100)}
encoded_custom_data = json.dumps(custom_data, indent=2)
print("\nEncoded data with custom type handler:")
print(encoded_custom_data)
# 3. Example for Fraction (from PyPI docs)
@json_encoder.register(Fraction)
def encode_fraction(obj: Fraction):
return float(obj)
fraction_data = {'ratio': Fraction(1, 3)}
encoded_fraction = json.dumps(fraction_data, indent=2)
print("\nEncoded Fraction:")
print(encoded_fraction)
Debug
Known issues
gotchaThe `json-encoder` library uses a `singledispatch` pattern for serialization, which differs from the standard library's `json.JSONEncoder` subclassing approach. Users accustomed to `json.dumps(obj, cls=MyEncoder)` should instead register handlers using `@json_encoder.register`.fixUse the `@json_encoder.register(Type)` decorator to define custom serialization logic for specific types instead of subclassing `JSONEncoder`.
affects: 0.4.4 and earlier
deprecatedThe project's PyPI metadata lists its 'Development Status' as '3 - Alpha' and the last release was in September 2016. While functional for its intended purpose, it may not be actively maintained or receive updates for new Python features or critical bug fixes.fixEvaluate the stability and feature set against your project's requirements. For new projects, consider if a more actively maintained library or a custom `JSONEncoder` solution in the standard library is more suitable, or be prepared to fork and maintain the library yourself.
affects: 0.4.4 and earlier
gotchaThe PyPI classifiers explicitly list support for Python 2.7 and 3.5. While it might work on newer Python versions, explicit compatibility beyond 3.5 is not guaranteed or tested by the project maintainers due to its maintenance status.fixTest thoroughly on your target Python version. For critical applications on Python > 3.5, consider alternative solutions or contribute to the project's maintenance to ensure compatibility.
affects: 0.4.4 and earlier
Errors
Common errors & fixes
TypeError: Object of type <YourType> is not JSON serializable
You are trying to serialize an object whose type (`<YourType>`) does not have a registered serialization function with `json-encoder`.
fixRegister a serialization function for `YourType` using the `@json_encoder.register(<YourType>)` decorator. For example:
`from json_encoder.encoder import json_encoder`
`@json_encoder.register(YourType)`
`def encode_your_type(obj: YourType):`
`return {'value': str(obj)}` json.dumps is not using my preferred JSON library (e.g., ujson or simplejson).
By default, `json-encoder` attempts to use `simplejson` if available, then falls back to the standard `json` library. Your preferred library might not be installed or explicitly configured.
fixEnsure your desired JSON library (e.g., `ujson`) is installed (`pip install ujson`), then explicitly configure `json-encoder` to use it:
`from json_encoder import use_json_library`
`import ujson # or simplejson`
`use_json_library(ujson)`
Upgrade
Version history
0.4.4latest on PyPI · released Sep 18, 2016
Audit
Dependencies
No dependency data recorded yet.