{"id":4067,"library":"jsons","title":"Jsons","description":"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.","status":"active","version":"1.6.3","language":"en","source_language":"en","source_url":"https://github.com/ramonhagenaars/jsons","tags":["serialization","deserialization","json","dataclasses","attrs","types","type-hints"],"install":[{"cmd":"pip install jsons","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"The primary library functionality is accessed directly via the 'jsons' module.","symbol":"jsons","correct":"import jsons"}],"quickstart":{"code":"import jsons\nfrom dataclasses import dataclass\nfrom datetime import datetime, timezone\nimport os\n\n@dataclass\nclass Person:\n    name: str\n    birthday: datetime\n    email: str = os.environ.get('USER_EMAIL', 'default@example.com')\n\n# Example data\nbirthday_guido = datetime(1956, 1, 31, 12, 0, tzinfo=timezone.utc)\np = Person('Guido van Rossum', birthday_guido)\n\n# Serialization to a dictionary\nout_dict = jsons.dump(p)\nprint(f\"Serialized dict: {out_dict}\")\n\n# Deserialization from a dictionary back to an object\np2 = jsons.load(out_dict, Person)\nprint(f\"Deserialized object: {p2}\")\nassert p == p2\n\n# Example with a list of custom objects\n@dataclass\nclass Pet:\n    name: str\n    species: str\n\n@dataclass\nclass Owner:\n    name: str\n    pets: list[Pet]\n\no = Owner('Alice', [Pet('Rex', 'dog'), Pet('Whiskers', 'cat')])\nowner_dict = jsons.dump(o)\nprint(f\"Serialized owner: {owner_dict}\")\n\no2 = jsons.load(owner_dict, Owner)\nprint(f\"Deserialized owner: {o2}\")\nassert o == o2","lang":"python","description":"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."},"warnings":[{"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.","message":"Do 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"In `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.","severity":"breaking","affected_versions":">=1.5.0"},{"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.","message":"Prior to v1.6.3, `jsons` could unintentionally parse a string into a `datetime` object during deserialization, leading to incorrect type assignments.","severity":"gotcha","affected_versions":"<1.6.3"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<1.6.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}