NumpyEncoder

0.3.2 · active · verified Thu Apr 16

NumpyEncoder is a Python JSON encoder designed to seamlessly handle various NumPy data types, including `ndarray`, `np.number`, `np.datetime64`, and more, which are not natively supported by Python's standard `json` module. It extends `json.JSONEncoder` to provide a plug-and-play solution for serializing data structures containing NumPy objects into JSON strings. The current version is 0.3.2, with releases occurring periodically to maintain compatibility with evolving NumPy versions.

Common errors

```
TypeError: Object of type ndarray is not JSON serializable
```
cause The Python `json` module does not inherently know how to convert NumPy arrays (`numpy.ndarray`) into a JSON-compatible format.

fix Use `NumpyEncoder` when calling `json.dumps()`: `json.dumps(your_data, cls=NumpyEncoder)`. This will convert `np.ndarray` objects to Python lists.
```
TypeError: Object of type int64 is not JSON serializable
```
cause NumPy's scalar types (e.g., `np.int64`, `np.float32`, `np.bool_`) are distinct from Python's native `int`, `float`, or `bool` types and are not directly serializable by the standard `json` module.

fix Pass `cls=NumpyEncoder` to `json.dumps()`. `NumpyEncoder` handles these scalar NumPy types by converting them to their equivalent Python native types.
```
AttributeError: module 'numpy' has no attribute 'type'
```
cause This error occurs in `numpyencoder` when an older version of `numpyencoder` is used with a newer NumPy version (specifically, NumPy 2.0 changed some internal type handling). The `numpy.type` attribute was likely removed or changed.

fix Upgrade `numpyencoder` to version 0.3.0 or higher, which includes specific fixes for NumPy 2.0 compatibility.

Warnings

breaking NumpyEncoder versions prior to 0.3.0 are not fully compatible with NumPy 2.0.0 due to significant breaking changes in NumPy's API, ABI, and type promotion rules.
Fix: Upgrade `numpyencoder` to version 0.3.0 or higher to ensure compatibility with `numpy>=2.0.0`. It is also recommended to review NumPy's 2.0 migration guide for other code adjustments.
gotcha Converting NumPy data types (especially floats) to JSON can lead to a loss of precision, as JSON numbers typically follow IEEE 754 double-precision floating-point format. While `numpyencoder` aims for fidelity, critical applications requiring exact precision might consider alternative serialization formats like HDF5 or `.npy`.
Fix: Be aware of potential precision loss when serializing floating-point NumPy data. For maximum precision, consider using formats like HDF5 (e.g., `h5py`) or NumPy's native binary format (`np.save`, `np.load`) for storing numerical arrays.
deprecated NumPy 2.0 introduced deprecations for certain type aliases and internal behaviors. While `numpyencoder` v0.3.2 includes updates to handle these gracefully, relying on deprecated NumPy features directly in your code might lead to future compatibility issues.
Fix: Ensure your NumPy usage adheres to the official NumPy 2.0 migration guide, avoiding deprecated types or patterns, even if `numpyencoder` temporarily supports them for backward compatibility.

Install

pip install numpyencoder Install stable version

Imports

NumpyEncoder
```
from numpyencoder import NumpyEncoder
```

Quickstart

This quickstart demonstrates how to use `NumpyEncoder` to serialize a dictionary containing various NumPy data types (an array, a scalar integer, and a datetime object) into a JSON string. The `cls=NumpyEncoder` argument passed to `json.dumps` ensures that NumPy objects are correctly converted into JSON-serializable Python native types.

import json
import numpy as np
from numpyencoder import NumpyEncoder

# Example with a NumPy array and scalar
numpy_data = {
    'array_field': np.array([0, 1.5, 2, 3]),
    'scalar_field': np.int64(123),
    'datetime_field': np.datetime64('2023-01-01T12:00:00')
}

# Serialize the data using NumpyEncoder
json_output = json.dumps(numpy_data, cls=NumpyEncoder, indent=2)
print(json_output)

# The output will convert numpy types to native Python types (lists, int, string for datetime)
expected_output_fragment = '"array_field": [
    0.0,
    1.5,
    2.0,
    3.0
  ],
  "scalar_field": 123,
  "datetime_field": "2023-01-01T12:00:00"'

view raw JSON →