📥 Modern API: Deserialization Functions

Progressive complexity load functions for different accuracy and performance needs, including file I/O variants.

🎯 Progressive Complexity Approach

Function	Success Rate	Speed	Best For
load_basic()	60-70%	⚡⚡⚡	Quick exploration
load_smart()	80-90%	⚡⚡	Production use
load_perfect()	100%	⚡	Mission-critical
load_typed()	95%	⚡⚡	Metadata-driven
FILE OPERATIONS
load_smart_file()	80-90%	⚡⚡	File-based production
load_perfect_file()	100%	⚡	File-based critical

📦 Detailed Function Documentation

load_basic()

Fast, basic deserialization for exploration and testing.

datason.load_basic(data: Any, **kwargs: Any) -> Any

Basic deserialization using heuristics only.

Uses simple heuristics to reconstruct Python objects from serialized data. Fast but with limited type fidelity - suitable for exploration and non-critical applications.

Success rate: ~60-70% for complex objects Speed: Fastest Use case: Data exploration, simple objects

Parameters:

Name	Type	Description	Default
data	Any	Serialized data to deserialize	required
**kwargs	Any	Additional options (parse_dates, parse_uuids, etc.)	{}

Returns:

Type	Description
Any	Deserialized Python object

Example

serialized = {"numbers": [1, 2, 3], "text": "hello"} result = load_basic(serialized)

Works well for simple structures

Source code in datason/api.py

def load_basic(data: Any, **kwargs: Any) -> Any:
    """Basic deserialization using heuristics only.

    Uses simple heuristics to reconstruct Python objects from serialized data.
    Fast but with limited type fidelity - suitable for exploration and
    non-critical applications.

    Success rate: ~60-70% for complex objects
    Speed: Fastest
    Use case: Data exploration, simple objects

    Args:
        data: Serialized data to deserialize
        **kwargs: Additional options (parse_dates, parse_uuids, etc.)

    Returns:
        Deserialized Python object

    Example:
        >>> serialized = {"numbers": [1, 2, 3], "text": "hello"}
        >>> result = load_basic(serialized)
        >>> # Works well for simple structures
    """
    return deserialize(data, **kwargs)

Quick Exploration Example:

# Fast loading for data exploration
json_data = '{"values": [1, 2, 3], "timestamp": "2024-01-01T12:00:00"}'
basic_data = ds.load_basic(json_data)
# Basic types only, minimal processing

load_smart()

Intelligent deserialization with good accuracy for production use.

datason.load_smart(data: Any, config: Optional[SerializationConfig] = None, **kwargs: Any) -> Any

Smart deserialization with auto-detection and heuristics.

Combines automatic type detection with heuristic fallbacks. Good balance of accuracy and performance for most use cases.

Success rate: ~80-90% for complex objects Speed: Moderate Use case: General purpose, production data processing

Parameters:

Name	Type	Description	Default
data	Any	Serialized data to deserialize	required
config	Optional[SerializationConfig]	Configuration for deserialization behavior	None
**kwargs	Any	Additional options	{}

Returns:

Type	Description
Any	Deserialized Python object with improved type fidelity

Example

serialized = dump_api(complex_object) result = load_smart(serialized)

Better type reconstruction than load_basic

Source code in datason/api.py

def load_smart(data: Any, config: Optional[SerializationConfig] = None, **kwargs: Any) -> Any:
    """Smart deserialization with auto-detection and heuristics.

    Combines automatic type detection with heuristic fallbacks.
    Good balance of accuracy and performance for most use cases.

    Success rate: ~80-90% for complex objects
    Speed: Moderate
    Use case: General purpose, production data processing

    Args:
        data: Serialized data to deserialize
        config: Configuration for deserialization behavior
        **kwargs: Additional options

    Returns:
        Deserialized Python object with improved type fidelity

    Example:
        >>> serialized = dump_api(complex_object)
        >>> result = load_smart(serialized)
        >>> # Better type reconstruction than load_basic
    """
    if config is None:
        config = SerializationConfig(auto_detect_types=True)
    return deserialize_fast(data, config=config, **kwargs)

Production Example:

# Intelligent type detection for production
smart_data = ds.load_smart(json_data)
print(type(smart_data["timestamp"]))  # <class 'datetime.datetime'>

load_perfect()

Perfect accuracy deserialization using templates for mission-critical applications.

datason.load_perfect(data: Any, template: Any, **kwargs: Any) -> Any

Perfect deserialization using template matching.

Uses a template object to achieve 100% accurate reconstruction. Requires you to provide the structure/type information but guarantees perfect fidelity.

Success rate: 100% when template matches data Speed: Fast (direct template matching) Use case: Critical applications, ML model loading, exact reconstruction

Parameters:

Name	Type	Description	Default
data	Any	Serialized data to deserialize	required
template	Any	Template object showing expected structure/types	required
**kwargs	Any	Additional options	{}

Returns:

Type	Description
Any	Perfectly reconstructed Python object matching template

Example

original = MyComplexClass(...) serialized = dump_ml(original) template = MyComplexClass.get_template() # or original itself result = load_perfect(serialized, template)

Guaranteed perfect reconstruction

Source code in datason/api.py

def load_perfect(data: Any, template: Any, **kwargs: Any) -> Any:
    """Perfect deserialization using template matching.

    Uses a template object to achieve 100% accurate reconstruction.
    Requires you to provide the structure/type information but
    guarantees perfect fidelity.

    Success rate: 100% when template matches data
    Speed: Fast (direct template matching)
    Use case: Critical applications, ML model loading, exact reconstruction

    Args:
        data: Serialized data to deserialize
        template: Template object showing expected structure/types
        **kwargs: Additional options

    Returns:
        Perfectly reconstructed Python object matching template

    Example:
        >>> original = MyComplexClass(...)
        >>> serialized = dump_ml(original)
        >>> template = MyComplexClass.get_template()  # or original itself
        >>> result = load_perfect(serialized, template)
        >>> # Guaranteed perfect reconstruction
    """
    return deserialize_with_template(data, template, **kwargs)

Mission-Critical Example:

# Define expected structure
template = {
    "values": [int],
    "timestamp": datetime,
    "metadata": {"version": float}
}

# 100% reliable restoration
perfect_data = ds.load_perfect(json_data, template)

load_typed()

High-accuracy deserialization using embedded type metadata.

datason.load_typed(data: Any, config: Optional[SerializationConfig] = None, **kwargs: Any) -> Any

Metadata-based type reconstruction.

Uses embedded type metadata from serialization to reconstruct objects. Requires data was serialized with type information preserved.

Success rate: ~95% when metadata available Speed: Fast (direct metadata lookup) Use case: When you control both serialization and deserialization

Parameters:

Name	Type	Description	Default
data	Any	Serialized data with embedded type metadata	required
config	Optional[SerializationConfig]	Configuration for type reconstruction	None
**kwargs	Any	Additional options	{}

Returns:

Type	Description
Any	Type-accurate deserialized Python object

Example

Works best with datason-serialized data

serialized = dump(original_object) # Preserves type info result = load_typed(serialized)

High fidelity reconstruction using embedded metadata

Source code in datason/api.py

def load_typed(data: Any, config: Optional[SerializationConfig] = None, **kwargs: Any) -> Any:
    """Metadata-based type reconstruction.

    Uses embedded type metadata from serialization to reconstruct objects.
    Requires data was serialized with type information preserved.

    Success rate: ~95% when metadata available
    Speed: Fast (direct metadata lookup)
    Use case: When you control both serialization and deserialization

    Args:
        data: Serialized data with embedded type metadata
        config: Configuration for type reconstruction
        **kwargs: Additional options

    Returns:
        Type-accurate deserialized Python object

    Example:
        >>> # Works best with datason-serialized data
        >>> serialized = dump(original_object)  # Preserves type info
        >>> result = load_typed(serialized)
        >>> # High fidelity reconstruction using embedded metadata
    """
    if config is None:
        config = get_strict_config()  # Use strict config for best type preservation
    return deserialize_fast(data, config=config, **kwargs)

Metadata-Driven Example:

# Use embedded type information
typed_data = ds.load_typed(data_with_types)
# Uses metadata for accurate restoration

🗃️ File Operations Functions

load_smart_file()

Smart file loading with automatic format detection and good accuracy.

datason.load_smart_file(path: Union[str, Path], *, format: Optional[str] = None, **kwargs: Any) -> Iterator[Any]

Load data from JSON/JSONL file using smart deserialization.

Good balance of accuracy and performance for most use cases. Success rate: ~80-90% for complex objects.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	Input file path	required
format	Optional[str]	Explicit format ('json' or 'jsonl'), auto-detected if None	None
**kwargs	Any	Additional deserialization options	{}

Returns:

Type	Description
Iterator[Any]	Iterator of deserialized objects

Examples:

>>> # Load from JSONL (yields each line)
>>> for item in load_smart_file("data.jsonl"):
...     process(item)
>>>
>>> # Load from JSON (yields each item in array, or single item)
>>> for item in load_smart_file("data.json"):
...     process(item)
>>>
>>> # Or load all at once
>>> data = list(load_smart_file("data.jsonl"))

Source code in datason/api.py

def load_smart_file(path: Union[str, Path], *, format: Optional[str] = None, **kwargs: Any) -> Iterator[Any]:
    """Load data from JSON/JSONL file using smart deserialization.

    Good balance of accuracy and performance for most use cases.
    Success rate: ~80-90% for complex objects.

    Args:
        path: Input file path
        format: Explicit format ('json' or 'jsonl'), auto-detected if None
        **kwargs: Additional deserialization options

    Returns:
        Iterator of deserialized objects

    Examples:
        >>> # Load from JSONL (yields each line)
        >>> for item in load_smart_file("data.jsonl"):
        ...     process(item)
        >>>
        >>> # Load from JSON (yields each item in array, or single item)
        >>> for item in load_smart_file("data.json"):
        ...     process(item)
        >>>
        >>> # Or load all at once
        >>> data = list(load_smart_file("data.jsonl"))
    """
    config = SerializationConfig(auto_detect_types=True)
    for raw_item in _load_from_file(path, config, format):
        yield load_smart(raw_item, config, **kwargs)

File-Based Production Example:

# Automatic format detection (.json, .jsonl, .gz)
data = ds.load_smart_file("experiment.json")
jsonl_data = ds.load_smart_file("training_logs.jsonl")
compressed_data = ds.load_smart_file("model.json.gz")

# Smart type reconstruction for production use
ml_data = ds.load_smart_file("model_checkpoint.json")

load_perfect_file()

Perfect file loading using templates for mission-critical applications.

datason.load_perfect_file(path: Union[str, Path], template: Any, *, format: Optional[str] = None, **kwargs: Any) -> Iterator[Any]

Load data from JSON/JSONL file using perfect template-based deserialization.

Uses template for 100% accurate reconstruction. Success rate: 100% when template matches data.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	Input file path	required
template	Any	Template object showing expected structure/types	required
format	Optional[str]	Explicit format ('json' or 'jsonl'), auto-detected if None	None
**kwargs	Any	Additional template options	{}

Returns:

Type	Description
Iterator[Any]	Iterator of perfectly reconstructed objects

Examples:

>>> template = {"weights": np.array([0.0]), "epoch": 0}
>>>
>>> # Perfect loading from JSONL
>>> for item in load_perfect_file("training.jsonl", template):
...     assert isinstance(item["weights"], np.ndarray)
>>>
>>> # Perfect loading from JSON
>>> for item in load_perfect_file("training.json", template):
...     assert isinstance(item["weights"], np.ndarray)

Source code in datason/api.py

def load_perfect_file(
    path: Union[str, Path], template: Any, *, format: Optional[str] = None, **kwargs: Any
) -> Iterator[Any]:
    """Load data from JSON/JSONL file using perfect template-based deserialization.

    Uses template for 100% accurate reconstruction.
    Success rate: 100% when template matches data.

    Args:
        path: Input file path
        template: Template object showing expected structure/types
        format: Explicit format ('json' or 'jsonl'), auto-detected if None
        **kwargs: Additional template options

    Returns:
        Iterator of perfectly reconstructed objects

    Examples:
        >>> template = {"weights": np.array([0.0]), "epoch": 0}
        >>>
        >>> # Perfect loading from JSONL
        >>> for item in load_perfect_file("training.jsonl", template):
        ...     assert isinstance(item["weights"], np.ndarray)
        >>>
        >>> # Perfect loading from JSON
        >>> for item in load_perfect_file("training.json", template):
        ...     assert isinstance(item["weights"], np.ndarray)
    """
    for raw_item in _load_from_file(path, format=format):
        yield load_perfect(raw_item, template, **kwargs)

File-Based Critical Example:

import torch
import numpy as np

# Define expected ML structure
ml_template = {
    "model": torch.nn.Linear(10, 1),
    "weights": torch.randn(100, 50),
    "features": np.random.random((1000, 20)),
    "metadata": {"accuracy": 0.0}
}

# 100% reliable ML reconstruction from file
perfect_ml = ds.load_perfect_file("experiment.json", ml_template)

# Works with JSONL files too
for item in ds.load_perfect_file("training_log.jsonl", ml_template):
    process_item(item)

🔄 Choosing the Right Load Function

Decision Matrix

# Choose based on your needs:

# Exploration phase - speed matters most
data = ds.load_basic(json_string)

# Development/testing - good balance
data = ds.load_smart(json_string)  

# Production - reliability critical
data = ds.load_perfect(json_string, template)

# Has embedded types - leverage metadata
data = ds.load_typed(json_string)

🔗 Related Documentation

• Serialization Functions - Corresponding dump functions
• Template System - Creating templates for perfect loading
• Modern API Overview - Complete modern API guide