tessl/pypi-jsonpickle

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

—

Pending

Overview

Eval results

Files

Handler Management System

Name: tessl/pypi-jsonpickle
Author: tessl

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

Capabilities

Handler Registration

def register(cls, handler=None, base=False):
    """
    Register a handler for objects of type cls.
    
    Parameters:
    - cls: The class/type to register a handler for
    - handler: Handler instance or class (if None, cls must be a handler)
    - base: If True, also handle subclasses of cls
    """

def unregister(cls):
    """
    Remove the handler registered for objects of type cls.
    
    Parameters:
    - cls: The class/type to unregister
    """

Usage Example:

import jsonpickle
from jsonpickle.handlers import BaseHandler

# Custom handler for a specific type
class CustomObjectHandler(BaseHandler):
    def flatten(self, obj, data):
        data['custom_field'] = obj.special_attribute
        return data
    
    def restore(self, data):
        obj = self.context.restore(data, reset=False)
        return obj

# Register the handler
jsonpickle.register(CustomObject, CustomObjectHandler)

# Use with base=True to handle subclasses too
jsonpickle.register(BaseCustomObject, CustomObjectHandler, base=True)

# Unregister when no longer needed
jsonpickle.unregister(CustomObject)

Base Handler Class

Base class for implementing custom serialization handlers.

class BaseHandler:
    def __init__(self, context):
        """
        Initialize handler with pickler/unpickler context.
        
        Parameters:
        - context: Active Pickler or Unpickler instance
        """
        
    def flatten(self, obj, data):
        """
        Convert object to JSON-serializable form during encoding.
        
        Parameters:
        - obj: Object being serialized
        - data: Dictionary to populate with serializable data
        
        Returns:
        Updated data dictionary
        """
        
    def restore(self, data):
        """
        Restore object from JSON data during decoding.
        
        Parameters:
        - data: Dictionary containing object data
        
        Returns:
        Restored Python object
        """

Implementation Example:

import jsonpickle
from jsonpickle.handlers import BaseHandler
import datetime

class DateTimeHandler(BaseHandler):
    def flatten(self, obj, data):
        # Convert datetime to ISO format string
        data['iso_format'] = obj.isoformat()
        return data
    
    def restore(self, data):
        # Restore datetime from ISO format
        return datetime.datetime.fromisoformat(data['iso_format'])

# Register the custom datetime handler
jsonpickle.register(datetime.datetime, DateTimeHandler)

# Test the handler
dt = datetime.datetime.now()
json_str = jsonpickle.encode(dt)
restored_dt = jsonpickle.decode(json_str)

Built-in Handlers

jsonpickle includes built-in handlers for common Python types.

# Built-in handler classes (examples)
class ArrayHandler(BaseHandler):
    """Handler for array.array objects"""
    
class DatetimeHandler(BaseHandler):
    """Handler for datetime objects"""
    
class RegexHandler(BaseHandler):
    """Handler for compiled regex patterns"""
    
class QueueHandler(BaseHandler):
    """Handler for queue objects"""
    
class UUIDHandler(BaseHandler):
    """Handler for UUID objects"""
    
class LockHandler(BaseHandler):
    """Handler for threading lock objects"""
    
class TextIOHandler(BaseHandler):
    """Handler for text I/O objects"""

These are automatically registered when jsonpickle is imported.

Registry Access

Access the global handler registry for inspection and management.

# Registry management functions
def get(cls):
    """Get the handler registered for a specific class"""
    
# Registry class
class Registry:
    def get(self, cls):
        """Get handler for type"""
        
    def register(self, cls, handler, base=False):
        """Register handler for type"""
        
    def unregister(self, cls):
        """Remove handler for type"""

Registry Usage Example:

from jsonpickle.handlers import registry, get

# Check if a handler is registered
handler = get(datetime.datetime)
if handler:
    print(f"Handler registered: {handler}")

# Access registry directly
all_handlers = registry._handlers  # Internal access

Custom Handler Patterns

Simple Value Transformation

class SimpleHandler(BaseHandler):
    def flatten(self, obj, data):
        data['value'] = str(obj)  # Convert to string
        return data
        
    def restore(self, data):
        return MyClass(data['value'])  # Reconstruct from string

Complex Object Handling

class ComplexHandler(BaseHandler):
    def flatten(self, obj, data):
        # Handle complex nested objects
        data['config'] = self.context.flatten(obj.config, reset=False)
        data['items'] = [self.context.flatten(item, reset=False) for item in obj.items]
        return data
        
    def restore(self, data):
        # Restore complex nested structure
        config = self.context.restore(data['config'], reset=False)
        items = [self.context.restore(item, reset=False) for item in data['items']]
        return ComplexObject(config, items)

Conditional Handling

class ConditionalHandler(BaseHandler):
    def flatten(self, obj, data):
        if hasattr(obj, 'special_method'):
            data['special_data'] = obj.special_method()
        else:
            data['regular_data'] = obj.get_data()
        return data
        
    def restore(self, data):
        if 'special_data' in data:
            return SpecialObject.from_special_data(data['special_data'])
        else:
            return RegularObject.from_data(data['regular_data'])

Handler Best Practices

Error Handling: Always handle potential errors in flatten/restore methods
Context Usage: Use self.context for recursive serialization of nested objects
Reset Parameter: Use reset=False when calling context methods from handlers
Type Checking: Validate data types in restore methods
Versioning: Consider version compatibility when designing handlers
Performance: Cache expensive computations where possible