or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

class-integration.mdconfiguration.mdcore-serialization.mdcustomization.mdindex.mdkey-transformation.mdtype-system.md
tile.json

tessl/pypi-jsons

A comprehensive Python library for serializing and deserializing Python objects to and from JSON (dictionaries) with minimal code changes required.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jsons@1.6.x

To install, run

npx @tessl/cli install tessl/pypi-jsons@1.6.0

index.mddocs/

jsons

A comprehensive Python library for serializing and deserializing Python objects to and from JSON (dictionaries) with minimal code changes required. The jsons package provides automatic conversion of complex Python objects including dataclasses, attrs classes, and Plain Old Python Objects (POPOs) to JSON-compatible dictionaries and back, with intelligent type inference and customizable serialization/deserialization behavior. It handles complex nested structures, generic types from the typing module, and provides extensive support for built-in Python types including datetime objects, pathlib.Path, Decimal, Enum, Union types, and various collections.

Package Information

  • Package Name: jsons
  • Language: Python
  • Installation: pip install jsons

Core Imports

import jsons
from jsons import JsonSerializable

The primary import provides access to all core serialization functions (dump, load), while JsonSerializable offers a class-based approach for objects that need built-in JSON capabilities.

Basic Usage

import jsons
from dataclasses import dataclass

# Define a dataclass
@dataclass
class Car:
    color: str
    model: str

@dataclass  
class Person:
    name: str
    car: Car

# Create objects
car = Car("red", "Toyota")
person = Person("John", car)

# Serialize to JSON-compatible dict
person_dict = jsons.dump(person)
print(person_dict)
# {'name': 'John', 'car': {'color': 'red', 'model': 'Toyota'}}

# Deserialize back to object
person_restored = jsons.load(person_dict, Person)
print(person_restored.name)  # "John"
print(person_restored.car.color)  # "red"

For classes without dataclass decorators, use type hints for custom types:

import jsons

class Car:
    def __init__(self, color: str):
        self.color = color

class Person:
    def __init__(self, car: Car, name: str):
        self.car = car
        self.name = name

# Usage is identical
car = Car("blue")  
person = Person(car, "Jane")
person_dict = jsons.dump(person)
person_restored = jsons.load(person_dict, Person)

Alternative class-based approach using JsonSerializable:

import jsons
from jsons import JsonSerializable

class Person(JsonSerializable):
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

person = Person("Alice", 30)

# Serialize using property
person_dict = person.json
print(person_dict)  # {'name': 'Alice', 'age': 30}

# Deserialize using class method
person_restored = Person.from_json(person_dict)
print(person_restored.name)  # "Alice"

Capabilities

Core Serialization

Primary functions for converting Python objects to JSON-compatible formats and back. Handles automatic type detection, nested objects, and custom serialization logic.

def dump(obj, cls=None, *, strict=False, **kwargs): ...
def dumps(obj, cls=None, *, strict=False, **kwargs): ...  
def dumpb(obj, cls=None, *, strict=False, **kwargs): ...
def load(json_obj, cls=None, *, strict=False, **kwargs): ...
def loads(s, cls=None, *, strict=False, **kwargs): ...
def loadb(b, cls=None, *, strict=False, **kwargs): ...

Class Integration

Base classes and utilities for integrating JSON serialization directly into your Python classes. Provides JsonSerializable base class with built-in json property and from_json class method.

class JsonSerializable:
    @property
    def json(self): ...
    @classmethod  
    def from_json(cls, json_obj, **kwargs): ...
    @classmethod
    def fork(cls, name=None): ...
    @classmethod
    def with_dump(cls, fork=False, **kwargs): ...
    @classmethod
    def with_load(cls, fork=False, **kwargs): ...

Type System

Comprehensive support for Python's type system including built-in types, collections, datetime objects, Enum types, Union types, and custom objects. Provides default serializers and deserializers for all common Python types.

# Built-in type support for:
# - Primitives: str, int, float, bool, None
# - Collections: list, tuple, dict, set, frozenset  
# - Date/Time: datetime, date, time, timezone, timedelta
# - Other: Decimal, UUID, complex, Enum, pathlib.Path

Customization

Extensible serializer and deserializer system for handling custom types and modifying default behavior. Includes serializer registration, validation, and key transformation utilities.

def set_serializer(func, cls, high_prio=True, **kwargs): ...
def get_serializer(cls, **kwargs): ...
def set_deserializer(func, cls, high_prio=True, **kwargs): ...
def get_deserializer(cls, **kwargs): ...
def set_validator(func, cls, **kwargs): ...
def get_validator(cls, **kwargs): ...

Key Transformation

Utilities for transforming dictionary keys between different naming conventions (camelCase, snake_case, PascalCase, lisp-case).

def camelcase(str_): ...
def snakecase(str_): ...  
def pascalcase(str_): ...
def lispcase(str_): ...

Configuration & Control

Advanced configuration options including fork management for separate serializer configurations, warning control, verbosity settings, and object transformation.

def fork(fork_inst=StateHolder, name=None): ...
def transform(obj, cls, *, mapper=None, **kwargs): ...
def suppress_warnings(do_suppress=True, **kwargs): ...
def suppress_warning(code, **kwargs): ...
def validate(obj, cls, **kwargs): ...