tessl/pypi-pyfury

Blazingly fast multi-language serialization framework powered by JIT and zero-copy

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Serialization

Name: tessl/pypi-pyfury
Author: tessl

Primary serialization operations for converting Python objects to/from binary format with optional reference tracking and circular reference support. PyFury provides both Python-native and cross-language serialization modes.

Capabilities

Fury Serialization Engine

The main serialization engine that handles object conversion with configurable language modes and security options.

class Fury:
    def __init__(
        self,
        language: Language = Language.XLANG,
        ref_tracking: bool = False,
        require_class_registration: bool = True,
    ):
        """
        Create a Fury serialization engine.

        Args:
            language: Serialization language mode (XLANG for cross-language, JAVA for Java compat)
            ref_tracking: Enable reference tracking for circular/shared objects
            require_class_registration: Require class registration for security (recommended)
        """

    def serialize(
        self,
        obj,
        buffer: Buffer = None,
        buffer_callback=None,
        unsupported_callback=None,
    ) -> Union[Buffer, bytes]:
        """
        Serialize a Python object to binary format.

        Args:
            obj: Object to serialize
            buffer: Optional buffer to write to (auto-allocated if None)
            buffer_callback: Callback for handling buffer objects
            unsupported_callback: Callback for handling unsupported types

        Returns:
            Serialized binary data as Buffer or bytes
        """

    def deserialize(
        self,
        buffer: Union[Buffer, bytes],
        buffers: Iterable = None,
        unsupported_objects: Iterable = None,
    ):
        """
        Deserialize binary data back to Python object.

        Args:
            buffer: Binary data to deserialize
            buffers: Additional buffers for zero-copy deserialization
            unsupported_objects: Objects to handle unsupported types

        Returns:
            Deserialized Python object
        """

Language Modes

PyFury supports different serialization modes for various compatibility requirements.

class Language(enum.Enum):
    XLANG = 0  # Cross-language mode for multi-language compatibility
    JAVA = 1   # Java-compatible mode for JVM interop

Usage Examples

Basic Serialization

import pyfury

# Create Fury instance
fury = pyfury.Fury()

# Serialize and deserialize simple objects
data = {"key": "value", "number": 42}
serialized = fury.serialize(data)
restored = fury.deserialize(serialized)

Cross-Language Serialization

import pyfury
from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int

# Enable cross-language mode with reference tracking
fury = pyfury.Fury(language=pyfury.Language.XLANG, ref_tracking=True)
fury.register_class(Person, type_tag="example.Person")

person = Person("Alice", 30)
serialized = fury.serialize(person)

# This data can be deserialized by Java/JavaScript/Go Fury implementations
restored = fury.deserialize(serialized)

Reference Tracking

import pyfury

# Enable reference tracking for circular references
fury = pyfury.Fury(ref_tracking=True)

# Create objects with shared references
obj1 = {"shared_data": [1, 2, 3]}
obj2 = {"ref1": obj1, "ref2": obj1}  # Both reference same object

serialized = fury.serialize(obj2)
restored = fury.deserialize(serialized)

# Shared references are preserved
assert restored["ref1"] is restored["ref2"]

Complex Object Serialization

import pyfury
from typing import List
from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int
    hobbies: List[str]

fury = pyfury.Fury()
fury.register_class(User)

# Serialize complex object
user = User("Alice", 30, ["reading", "swimming"])
user_bytes = fury.serialize(user)

# Deserialize
restored_user = fury.deserialize(user_bytes)

Opaque Objects

PyFury handles opaque objects for cross-language scenarios where types aren't registered on both sides.

class OpaqueObject:
    def __init__(self, type_id: int, data: bytes):
        """
        Represents an object that couldn't be deserialized due to missing type info.

        Args:
            type_id: Type identifier from the serialization metadata
            data: Raw serialized data of the object
        """

Buffer Operations

Direct buffer operations for advanced use cases and memory optimization.

import pyfury

fury = pyfury.Fury()

# Use pre-allocated buffer
buffer = pyfury.Buffer.allocate(1024)
result = fury.serialize(my_object, buffer=buffer)

# Deserialize from buffer
restored = fury.deserialize(result)

Class Registration

import pyfury

fury = pyfury.Fury()

# Register class with auto-generated ID
fury.register_class(MyClass)

# Register with specific type tag for cross-language compatibility
fury.register_class(MyClass, type_tag="com.example.MyClass")

# Register with specific class ID
fury.register_class(MyClass, class_id=100)

Performance Considerations

Reference Tracking: Only enable when dealing with circular references or shared objects
Language Mode: Use XLANG for cross-language compatibility, omit for Python-only scenarios
Class Registration: Keep enabled for security; pre-register all classes for best performance
Buffer Reuse: Pass the same Buffer instance across multiple serialize() calls to reduce allocations

Error Handling

import pyfury

fury = pyfury.Fury()

try:
    data = fury.serialize(some_object)
    restored = fury.deserialize(data)
except pyfury.FuryError as e:
    print(f"Serialization error: {e}")
except pyfury.ClassNotCompatibleError as e:
    print(f"Class compatibility error: {e}")

Handling Unsupported Types

PyFury provides callbacks for handling types that cannot be serialized directly.

import pyfury

def buffer_callback(obj):
    """Handle buffer objects during serialization."""
    if hasattr(obj, 'to_buffer'):
        return obj.to_buffer()
    return None

def unsupported_callback(obj):
    """Handle unsupported objects during serialization."""
    # Custom logic for unsupported types
    return obj

fury = pyfury.Fury()
serialized = fury.serialize(
    my_object,
    buffer_callback=buffer_callback,
    unsupported_callback=unsupported_callback
)

Install with Tessl CLI