numpyencoder

library0.3.2pypypi✓ verified 84d ago

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.

serialization data

pip install numpyencoder

github ↗package ↗

INSTALL

IMPORT

SIG · NUMPYENCODER

numpyencoder

serializationpythonv0.3.2

Install

3.7s avg

Import

271ms

Disk

90MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.2 · 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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.268s · 90.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.7s · import 0.273s · 86MB

90MB installed

● package 90MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NumpyEncoder

✓ from numpyencoder import NumpyEncoder

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"'

Debug

Known issues

breakingNumpyEncoder 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.

affects: <0.3.0

gotchaConverting 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.

affects: All versions

deprecatedNumPy 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.

affects: All versions, specifically with `numpy>=2.0.0`

Errors

Common errors & fixes

TypeError: Object of type ndarray is not JSON serializable

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

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'

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.

Upgrade

Version history

0.3.2latest on PyPI · released Jul 15, 2025

Audit

Dependencies

numpyrequiredCore functionality relies on NumPy data types.

packagingrequiredUsed for dependency management and setup in recent versions (>=0.3.2).

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/hmallen/numpyencoder ↗

packagehttps://pypi.org/project/numpyencoder/ ↗