jsons

library1.6.3pypypi✓ verified 23d ago

Jsons is a Python library designed for seamlessly serializing complex Python objects (including dataclasses, attrs, and POPOs) to JSON (dicts or strings) and deserializing them back. It aims for minimal effort, requiring no modifications to your objects, and is highly customizable and extendable. The current version is 1.6.3, and it maintains an active release cadence with several minor updates per year addressing features and bug fixes.

serialization

pip install jsons

github ↗package ↗

INSTALL

IMPORT

SIG · JSONS

jsons

serializationpythonv1.6.3

Install

1.6s avg

Import

141ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.6.3 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.150s · 19MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.132s · 19MB

17MB installed

● package 17MB

Code

Verified usage

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

jsons

✓ import jsons

The primary library functionality is accessed directly via the 'jsons' module.

This quickstart demonstrates how to define a dataclass and use `jsons.dump()` to serialize an instance into a dictionary and `jsons.load()` to deserialize it back. It also includes an example with nested objects and lists, showcasing `jsons`'s ability to handle complex type hints.

import jsons from dataclasses import dataclass from datetime import datetime, timezone import os @dataclass class Person: name: str birthday: datetime email: str = os.environ.get('USER_EMAIL', 'default@example.com') # Example data birthday_guido = datetime(1956, 1, 31, 12, 0, tzinfo=timezone.utc) p = Person('Guido van Rossum', birthday_guido) # Serialization to a dictionary out_dict = jsons.dump(p) print(f"Serialized dict: {out_dict}") # Deserialization from a dictionary back to an object p2 = jsons.load(out_dict, Person) print(f"Deserialized object: {p2}") assert p == p2 # Example with a list of custom objects @dataclass class Pet: name: str species: str @dataclass class Owner: name: str pets: list[Pet] o = Owner('Alice', [Pet('Rex', 'dog'), Pet('Whiskers', 'cat')]) owner_dict = jsons.dump(o) print(f"Serialized owner: {owner_dict}") o2 = jsons.load(owner_dict, Owner) print(f"Deserialized owner: {o2}") assert o == o2

Debug

Known issues

gotchaDo not confuse `jsons` with Python's built-in `json` module. While `json` handles basic types, `jsons` is designed for direct serialization/deserialization of complex Python objects (like dataclasses, attrs, and custom classes) without manual encoding/decoding for types like `datetime` or custom objects.

fix

Use `import jsons` for object-oriented serialization and `import json` for raw JSON string/file manipulation. `jsons` handles conversion of `datetime` objects by default.

affects: All versions

breakingIn `jsons` v1.5.0, microseconds are no longer stripped by default when serializing `datetime` objects. This changes the output format for datetimes if your application previously relied on microseconds being removed.

fix

If you require microseconds to be stripped, you may need to configure a custom serializer for `datetime` objects or preprocess your data before serialization.

affects: >=1.5.0

gotchaPrior to v1.6.3, `jsons` could unintentionally parse a string into a `datetime` object during deserialization, leading to incorrect type assignments.

fix

Upgrade to `jsons` v1.6.3 or newer. If upgrading is not possible, ensure that string fields are explicitly typed or validate deserialized objects to catch unexpected `datetime` instances.

affects: <1.6.3

gotchaPrior to v1.6.1, `IntEnums` were not serialized with their names even when `use_enum_name=True` was intended, potentially serializing by value instead. Named tuples also had issues with `typing.get_type_hints`, affecting future annotations.

fix

Upgrade to `jsons` v1.6.1 or newer to ensure correct `IntEnum` serialization with `use_enum_name=True` and proper type hint resolution for named tuples.

affects: <1.6.1

Errors

Common errors & fixes

jsons.exceptions.DeserializationError: Invalid type: "<SomeType>", only arguments of the following types are allowed: str, int, float, bool, list, tuple, set, dict, NoneType.

This error occurs when `jsons.load` tries to deserialize a value for a field whose type hint specifies a custom object (e.g., a `bson.ObjectId` or another complex type), but `jsons` does not have a default deserializer registered for that specific custom type and no custom deserializer was explicitly provided.

fix

Register a custom deserializer for the problematic type using `jsons.set_deserializer`. For example, for a custom `MyClass`, you would define `jsons.set_deserializer(my_deserializer_function, MyClass)`.

UserWarning: Failed to dump attribute "<attribute_name>" of object of type "<ClassName>". Reason: 'NoneType' object is not callable. Ignoring the attribute.

This warning is emitted by `jsons.dump` when it encounters an attribute (often in a dataclass with an `Optional` type hint, like `int | None`) that has a value of `None`, and during its internal processing, it attempts to call `None` as if it were a function or method, leading to a `NoneType` object not callable error. It indicates `jsons` is struggling to process an `Optional` field with a `None` value in a specific context but proceeds by ignoring the attribute.

fix

While `jsons` attempts to handle this gracefully, for explicit control, ensure `Optional[Type]` (e.g., `Optional[int]`) from the `typing` module is used for optional fields. You can also suppress this warning using `jsons.suppress_warnings(True)` or prevent `None` attributes from being dumped with `jsons.dump(obj, strip_nones=True)`.

TypeError: Object of type <CustomClass> is not JSON serializable

Although `jsons` is designed to seamlessly serialize complex Python objects, this `TypeError` typically arises if a developer inadvertently uses the standard `json.dumps()` function (from Python's built-in `json` module) instead of `jsons.dump()`, or if a very specific custom type (without a registered serializer) is encountered by `jsons` itself during serialization.

fix

Always use `jsons.dump()` for serializing custom Python objects with the `jsons` library. If a particular custom class still causes this error even with `jsons.dump()`, register a custom serializer for that type using `jsons.set_serializer(my_serializer_function, CustomClass)`.

Upgrade

Version history

1.6.3latest on PyPI · released Jun 9, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ramonhagenaars/jsons ↗

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