or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

advanced-classes.md backend-system.md core-serialization.md extensions.md handler-system.md index.md

tile.json

tessl/pypi-jsonpickle

Python library for encoding/decoding any Python object to/from JSON

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/jsonpickle@4.1.x

To install, run

npx @tessl/cli install tessl/pypi-jsonpickle@4.1.0

jsonpickle

A Python library for encoding/decoding any Python object to/from JSON format. jsonpickle builds upon existing JSON encoders (simplejson, json, ujson) and provides comprehensive support for complex Python objects including custom classes, numpy arrays, pandas dataframes, and other objects that cannot be directly serialized to JSON.

Security Warning: jsonpickle is not secure. Only unpickle data you trust. It can execute arbitrary code during unpickling, similar to Python's pickle module.

Package Information

Package Name: jsonpickle
Language: Python
Installation: pip install jsonpickle
Documentation: https://jsonpickle.readthedocs.io/

Core Imports

import jsonpickle

For advanced usage:

from jsonpickle import Pickler, Unpickler, register, unregister
from jsonpickle.backend import JSONBackend

Basic Usage

import jsonpickle

# Define a custom class
class Thing:
    def __init__(self, name):
        self.name = name

obj = Thing('Awesome')

# Encode to JSON string
json_string = jsonpickle.encode(obj)

# Decode back to Python object
restored_obj = jsonpickle.decode(json_string)

assert obj.name == restored_obj.name

For one-way serialization (no restoration capability):

# Create simpler JSON without restoration metadata
oneway = jsonpickle.encode(obj, unpicklable=False)
result = jsonpickle.decode(oneway)
assert obj.name == result['name'] == 'Awesome'

Architecture

jsonpickle uses a modular architecture with several key components:

Pickler/Unpickler: Core serialization and deserialization engines with extensive configuration options
Handlers Registry: Extensible system for custom type serialization with built-in handlers for common types
Backend System: Pluggable JSON encoder/decoder backends (json, simplejson, ujson) with fallback support
Tag System: Internal metadata tags for object type preservation and reference handling

This design allows jsonpickle to handle arbitrary Python objects while maintaining compatibility with multiple JSON backends and providing security controls for safe deserialization.

Capabilities

Core Serialization Functions

Essential encode/decode functions for converting Python objects to/from JSON strings, with extensive configuration options for controlling serialization behavior.

def encode(
    value,
    unpicklable=True,
    make_refs=True,
    keys=False,
    max_depth=None,
    reset=True,
    backend=None,
    warn=False,
    context=None,
    max_iter=None,
    use_decimal=False,
    numeric_keys=False,
    use_base85=False,
    fail_safe=None,
    indent=None,
    separators=None,
    include_properties=False,
    handle_readonly=False,
) -> str

def decode(
    string,
    backend=None,
    context=None,
    keys=False,
    reset=True,
    safe=True,
    classes=None,
    v1_decode=False,
    on_missing='ignore',
    handle_readonly=False,
) -> any

# JSON compatibility aliases
dumps = encode
loads = decode

Core Serialization

Advanced Pickler and Unpickler Classes

Low-level serialization classes providing fine-grained control over the encoding/decoding process, including state management and reusability.

class Pickler:
    def __init__(self, **options): ...
    def reset(self): ...
    def flatten(self, obj): ...

class Unpickler:
    def __init__(self, **options): ...
    def reset(self): ...
    def restore(self, obj): ...
    def register_classes(self, classes): ...

Advanced Classes

Handler Management System

Extensible system for registering custom serialization handlers for specific types, allowing you to control how particular objects are encoded and decoded.

def register(cls, handler=None, base=False): ...
def unregister(cls): ...

class BaseHandler:
    def __init__(self, context): ...
    def flatten(self, obj, data): ...
    def restore(self, data): ...

Handler System

Backend Management

Pluggable JSON encoder/decoder backend system supporting multiple JSON libraries with configuration options and fallback mechanisms.

class JSONBackend:
    def encode(self, obj): ...
    def decode(self, s): ...
    def load_backend(self, name): ...
    def set_preferred_backend(self, name): ...
    def set_encoder_options(self, name, **options): ...
    def set_decoder_options(self, name, **options): ...

# Module-level backend functions (exported to jsonpickle namespace)
def set_preferred_backend(name): ...
def set_encoder_options(name, **options): ...
def set_decoder_options(name, **options): ...
def load_backend(name): ...
def remove_backend(name): ...
def enable_fallthrough(enable): ...

Backend System

Extension Modules

Built-in extensions for popular Python libraries including numpy, pandas, GMPY, and YAML integration.

# NumPy extension
from jsonpickle.ext import numpy
numpy.register_handlers()
numpy.unregister_handlers()

# Pandas extension  
from jsonpickle.ext import pandas
pandas.register_handlers()
pandas.unregister_handlers()

# GMPY extension
from jsonpickle.ext import gmpy
gmpy.register_handlers()
gmpy.unregister_handlers()

# YAML backend
from jsonpickle.ext import yaml
yaml.register()

Extensions

Types

# Core exception class
class ClassNotFoundError(BaseException):
    """Raised when a class cannot be found during unpickling"""
    pass

# Version information
__version__: str