Skip to main content

For serializing Python objects to JSON (dicts) and back

Project description

Python versions Downloads PyPI version Code Coverage Scrutinizer Code Quality

  • Turn Python objects into dicts or (json)strings
  • No changes required to your objects
  • Easily customizable and extendable

💗 this lib? Leave a ★ and tell your colleagues!

Example of a model to serialize:

>>> @dataclass
... class Person:
...    name: str
...    birthday: datetime
>>> p = Person('Guido van Rossum', birthday_guido)

Example of using jsons to serialize:

>>> out = jsons.dump(p)
>>> out
{'birthday': '1956-01-31T12:00:00Z', 'name': 'Guido van Rossum'}

Example of using jsons to deserialize:

>>> p2 = jsons.load(out, Person)
>>> p2
Person(name='Guido van Rossum', birthday=datetime.datetime(1956, 1, 31, 12, 0, tzinfo=datetime.timezone.utc))


pip install jsons


import jsons

some_instance = jsons.load(some_dict, SomeClass)  # Deserialization
some_dict = jsons.dump(some_instance)  # Serialization

In some cases, you have instances that contain other instances that need (de)serialization, for instance with lists or dicts. You can use the typing classes for this as is demonstrated below.

from typing import List, Tuple
import jsons

# For more complex deserialization with generic types, use the typing module
list_of_tuples = jsons.load(some_dict, List[Tuple[AClass, AnotherClass]])

(For more examples, see the FAQ)



Recent updates


  • Bugfix: ZoneInfo failed to dump if attached to a datetime.


  • Feature: Support for ZoneInfo on Python3.9+.
  • Change: microseconds are no longer stripped by default (thanks to pietrodn).


  • Bugfix: get_origin did not work with python3.9+ parameterized collections (e.g. dict[str, str]).


  • Bugfix: Types of attributes that are not in the constructor were not properly looked for. See issue #128.


  • Feature: DefaultDicts can now be deserialized.
  • Feature: Dicts with any (hashable) key can now be dumped and loaded.
  • Feature: Suppress specific warnings.
  • Bugfix: Loading a verbose-serialized object in a list could sometimes deserialize that object as a parent class.
  • Bugfix: Unwanted stringification of NoneValues is now prevented in Optionals and Unions with NoneType.
  • Bugfix: Fixed a bug with postponed annotations and dataclasses. See also Issue34776.
  • Bugfix: Types of attributes that are not in the constructor are now looked for in annotations.


  • Bugfix: Fixed bug where classmethods were included in the serialized result.


  • Feature: Added warn_on_fail parameter to default_list_deserializer that allows to continue deserialization upon errors.
  • Feature: Added transform that can transform an object to an object of another type.
  • Feature: Added serializer and deserializer for pathlib.Path (thanks to alexmirrington).
  • Change: When loading a list fails, the error message now points to the failing index.
  • Bugfix: Fixed bug when dumping an object with an innerclass.


  • Bugfix: Fixed bug with postponed typehints (PEP-563).
  • Bugfix: Loading an invalid value targeting an optional did not raise.
  • Bugfix: Loading a dict did not properly pass key_transformers.
  • Bugfix: Loading a namedtuple did not properly use key_transformers.
  • Bugfix: Utilized __annotations__ in favor _field_types because of deprecation as of 3.8.


  • Feature: Added __version__ which can be imported from jsons
  • Bugfix: Dumping a tuple with ellipsis failed in strict mode.


  • Feature: Added a serializer for Union types.
  • Change: Exceptions are more clear upon deserialization failure (thanks to haluzpav).
  • Change: You can no longer announce a class with a custom name.
  • Bugfix: Fixed dumping optional attributes.
  • Bugfix: Dataclasses inheriting from JsonSerializable always dumped their attributes as if in strict mode.


  • Feature: Added strict parameter to dump to indicate that dumping a certain cls will ignore any extra data.
  • Feature: When using dump(obj, cls=x), x can now be any class (previously, only a class with __slots__).
  • Feature: Support for dumping Decimal (thanks to herdigiorgi).
  • Feature: Primitives are now cast if possible when dumping (e.g. dump(5, str)).
  • Feature: Dumping iterables with generic types (e.g. dump(obj, List[str])) will now dump with respect to that types (if strict)
  • Feature: The default_dict serializer now optionally accepts types: Optional[Dict[str, type]].
  • Change: Improved performance when dumping using strict=True (up to 4 times faster!).
  • Bugfix: set_validator with multiple types did not work.


  • Feature: Added a serializer/deserializer for time.
  • Feature: Added a serializer/deserializer for timezone.
  • Feature: Added a serializer/deserializer for timedelta.
  • Feature: Added a serializer/deserializer for date.
  • Bugfix: Dumping verbose did not store the types of dicts (Dict[K, V]).
  • Bugfix: Loading with List (no generic type) failed.
  • Bugfix: Loading with Dict (no generic type) failed.
  • Bugfix: Loading with Tuple (no generic type) failed.


Special thanks to the following contributors of code, discussions or suggestions:

pietrodn, georgeharker, aecay, bibz, thijss, alexmirrington, tirkarthi, marksomething, herdigiorgi, jochembroekhoff, robinklaassen, ahmetkucuk, casparjespersen, cypreess, gastlich, jmolinski, haluzpav, finetuned89

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jsons, version 1.5.1
Filename, size File type Python version Upload date Hashes
Filename, size jsons-1.5.1-py3-none-any.whl (60.3 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page