🔧 Modern API: Utility Functions

Helper functions for JSON compatibility, API discovery, and assistance.

🎯 Function Overview

Function	Purpose	Best For
dumps() / loads()	JSON module compatibility	Drop-in replacement
help_api()	Interactive guidance	Learning and discovery
get_api_info()	API metadata	Programmatic access

📦 Detailed Function Documentation

dumps() / loads()

JSON module compatibility with intelligent type handling.

datason.dumps(obj: Any, **kwargs: Any) -> Any

Enhanced serialization returning dict (DataSON's smart default).

This is DataSON's enhanced API that returns a dict with smart type handling, datetime parsing, ML support, and other advanced features.

For JSON string output or stdlib compatibility, use datason.json.dumps() or dumps_json().

Parameters:

Name	Type	Description	Default
obj	Any	Object to serialize	required
**kwargs	Any	DataSON configuration options	{}

Returns:

Type	Description
Any	Serialized dict with enhanced type handling

Examples:

>>> obj = {"timestamp": datetime.now(), "data": [1, 2, 3]}
>>> result = dumps(obj)  # Returns dict with smart datetime handling

>>> # For JSON string compatibility:
>>> import datason.json as json
>>> json_str = json.dumps(obj)  # Returns JSON string

Source code in datason/api.py

def dumps(obj: Any, **kwargs: Any) -> Any:
    """Enhanced serialization returning dict (DataSON's smart default).

    This is DataSON's enhanced API that returns a dict with smart type handling,
    datetime parsing, ML support, and other advanced features.

    For JSON string output or stdlib compatibility, use datason.json.dumps() or dumps_json().

    Args:
        obj: Object to serialize
        **kwargs: DataSON configuration options

    Returns:
        Serialized dict with enhanced type handling

    Examples:
        >>> obj = {"timestamp": datetime.now(), "data": [1, 2, 3]}
        >>> result = dumps(obj)  # Returns dict with smart datetime handling

        >>> # For JSON string compatibility:
        >>> import datason.json as json
        >>> json_str = json.dumps(obj)  # Returns JSON string
    """
    # Use enhanced serialization with smart defaults
    return serialize(obj, **kwargs)

datason.loads(s: str, **kwargs: Any) -> Any

Enhanced JSON string deserialization (DataSON's smart default).

This provides smart deserialization with datetime parsing, type reconstruction, and other DataSON enhancements. For stdlib json.loads() compatibility, use datason.json.loads() or loads_json().

Parameters:

Name	Type	Description	Default
s	str	JSON string to deserialize	required
**kwargs	Any	DataSON configuration options	{}

Returns:

Type	Description
Any	Deserialized Python object with enhanced type handling

Example

json_str = '{"timestamp": "2024-01-01T00:00:00Z", "data": [1, 2, 3]}' result = loads(json_str) # Smart parsing with datetime handling

For JSON compatibility:

import datason.json as json result = json.loads(json_str) # Exact json.loads() behavior

Source code in datason/api.py

def loads(s: str, **kwargs: Any) -> Any:
    """Enhanced JSON string deserialization (DataSON's smart default).

    This provides smart deserialization with datetime parsing, type reconstruction,
    and other DataSON enhancements. For stdlib json.loads() compatibility,
    use datason.json.loads() or loads_json().

    Args:
        s: JSON string to deserialize
        **kwargs: DataSON configuration options

    Returns:
        Deserialized Python object with enhanced type handling

    Example:
        >>> json_str = '{"timestamp": "2024-01-01T00:00:00Z", "data": [1, 2, 3]}'
        >>> result = loads(json_str)  # Smart parsing with datetime handling

        >>> # For JSON compatibility:
        >>> import datason.json as json
        >>> result = json.loads(json_str)  # Exact json.loads() behavior
    """
    # Use DataSON's native string parsing to avoid double processing
    # Parse with DataSON's JSON compatibility layer, then enhance with smart processing
    from .json import loads as loads_json

    data = loads_json(s)
    return load_smart(data, **kwargs)

JSON Compatibility Example:

import datason as ds
from datetime import datetime
import numpy as np

# Drop-in replacement for json.dumps/loads
data = {
    "timestamp": datetime.now(),
    "array": np.array([1, 2, 3]),
    "value": 42.5
}

# Like json.dumps() but with type intelligence
json_string = ds.dumps(data)

# Like json.loads() but with type restoration
restored = ds.loads(json_string)
print(type(restored["timestamp"]))  # <class 'datetime.datetime'>
print(type(restored["array"]))      # <class 'numpy.ndarray'>

help_api()

Interactive API guidance and recommendations.

datason.help_api() -> Dict[str, Any]

Get help on choosing the right API function.

Returns:

Type	Description
Dict[str, Any]	Dictionary with API guidance and function recommendations

Example

help_info = help_api() print(help_info['recommendations'])

Source code in datason/api.py

def help_api() -> Dict[str, Any]:
    """Get help on choosing the right API function.

    Returns:
        Dictionary with API guidance and function recommendations

    Example:
        >>> help_info = help_api()
        >>> print(help_info['recommendations'])
    """
    return {
        "serialization": {
            "basic": {"function": "dump()", "use_case": "General purpose serialization", "example": "dump(data)"},
            "ml_optimized": {
                "function": "dump_ml()",
                "use_case": "ML models, tensors, NumPy arrays",
                "example": "dump_ml(sklearn_model)",
            },
            "api_safe": {
                "function": "dump_api()",
                "use_case": "Web APIs, clean JSON output",
                "example": "dump_api(response_data)",
            },
            "secure": {
                "function": "dump_secure()",
                "use_case": "Sensitive data with PII redaction",
                "example": "dump_secure(user_data, redact_pii=True)",
            },
            "performance": {
                "function": "dump_fast()",
                "use_case": "High-throughput scenarios",
                "example": "dump_fast(large_dataset)",
            },
            "chunked": {
                "function": "dump_chunked()",
                "use_case": "Very large objects, memory efficiency",
                "example": "dump_chunked(huge_list, chunk_size=1000)",
            },
        },
        "deserialization": {
            "basic": {
                "function": "load_basic()",
                "success_rate": "60-70%",
                "speed": "Fastest",
                "use_case": "Simple objects, data exploration",
            },
            "smart": {
                "function": "load_smart()",
                "success_rate": "80-90%",
                "speed": "Moderate",
                "use_case": "General purpose, production data",
            },
            "perfect": {
                "function": "load_perfect()",
                "success_rate": "100%",
                "speed": "Fast",
                "use_case": "Critical applications, requires template",
                "example": "load_perfect(data, template)",
            },
            "typed": {
                "function": "load_typed()",
                "success_rate": "95%",
                "speed": "Fast",
                "use_case": "When metadata available",
            },
        },
        "file_operations": {
            "save_ml": {
                "function": "save_ml()",
                "use_case": "ML models/data to JSON/JSONL files",
                "examples": [
                    "save_ml(model, 'model.json')    # Single JSON object",
                    "save_ml(model, 'model.jsonl')   # Multiple JSONL objects",
                    "save_ml(model, 'model.txt', format='json')  # Explicit format",
                ],
            },
            "save_secure": {
                "function": "save_secure()",
                "use_case": "Secure JSON/JSONL with redaction",
                "examples": [
                    "save_secure(data, 'secure.json', redact_pii=True)",
                    "save_secure(data, 'secure.jsonl', redact_pii=True)",
                ],
            },
            "load_file": {
                "function": "load_smart_file()",
                "use_case": "Smart loading from JSON/JSONL files",
                "examples": [
                    "list(load_smart_file('data.json'))",
                    "list(load_smart_file('data.jsonl'))",
                    "list(load_smart_file('data.txt', format='json'))",
                ],
            },
        },
        "recommendations": [
            "For ML workflows: save_ml() + load_perfect_file() with template",
            "For APIs: save_api() + load_smart_file()",
            "For sensitive data: save_secure() + load_smart_file()",
            "For exploration: dump() + load_basic()",
            "For production: save_ml() + load_smart_file()",
        ],
    }

Interactive Guidance Example:

# Get personalized function recommendations
ds.help_api()

# Output example:
# 🎯 datason API Guide
#
# SERIALIZATION (Dump Functions):
# • dump() - General purpose serialization
# • dump_ml() - ML models, tensors, NumPy arrays
# • dump_api() - Web APIs, clean JSON output
# • dump_secure() - Sensitive data with PII redaction
#
# DESERIALIZATION (Load Functions):
# • load_basic() - 60-70% success, fastest (exploration)
# • load_smart() - 80-90% success, moderate speed (production)
# • load_perfect() - 100% success, requires template (critical)

# Get help for specific categories
ds.help_api("dump")      # Focus on serialization
ds.help_api("load")      # Focus on deserialization
ds.help_api("security")  # Focus on security features

get_api_info()

Comprehensive API metadata and feature information.

datason.get_api_info() -> Dict[str, Any]

Get information about the modern API.

Returns:

Type	Description
Dict[str, Any]	Dictionary with API version and feature information

Source code in datason/api.py

def get_api_info() -> Dict[str, Any]:
    """Get information about the modern API.

    Returns:
        Dictionary with API version and feature information
    """
    return {
        "api_version": "modern",
        "phase": "3",
        "features": {
            "intention_revealing_names": True,
            "compositional_utilities": True,
            "domain_specific_convenience": True,
            "progressive_complexity": True,
            "backward_compatibility": True,
            "file_operations": True,
        },
        "dump_functions": ["dump", "dump_ml", "dump_api", "dump_secure", "dump_fast", "dump_chunked", "stream_dump"],
        "load_functions": ["load_basic", "load_smart", "load_perfect", "load_typed"],
        "file_functions": ["save_ml", "save_secure", "save_api", "load_smart_file", "load_perfect_file"],
        "convenience": ["loads", "dumps"],
        "help": ["help_api", "get_api_info"],
    }

API Metadata Example:

# Get comprehensive API information
api_info = ds.get_api_info()

print("Available functions:")
print("Dump functions:", api_info['dump_functions'])
print("Load functions:", api_info['load_functions'])
print("Utility functions:", api_info['utility_functions'])

print("\nRecommendations:")
print("For ML workflows:", api_info['recommendations']['ml'])
print("For web APIs:", api_info['recommendations']['web'])
print("For security:", api_info['recommendations']['security'])

# Explore capabilities
print("\nFeatures:")
print("Supported types:", api_info['features']['supported_types'])
print("Security features:", api_info['features']['security'])
print("Performance features:", api_info['features']['performance'])

# Version and compatibility info
print("\nVersion info:")
print("API version:", api_info['version']['api'])
print("Package version:", api_info['version']['package'])
print("Compatibility:", api_info['compatibility'])

🔍 API Discovery Workflow

Learning the API

# Step 1: Get overview
ds.help_api()

# Step 2: Get detailed information
info = ds.get_api_info()

# Step 3: Explore specific areas
ds.help_api("ml")        # ML-specific guidance
ds.help_api("security")  # Security-specific guidance

# Step 4: Use the functions
data = ds.dump_ml(model_data)    # Based on guidance
loaded = ds.load_smart(data)     # Progressive complexity

Integration Patterns

# JSON module migration
import json
import datason as ds

# Replace json with datason for better type handling
# Old: json.dumps(data)
# New: ds.dumps(data)

# Old: json.loads(json_string)  
# New: ds.loads(json_string)

# Benefits: automatic type preservation
original = {"date": datetime.now(), "array": np.array([1, 2, 3])}
restored = ds.loads(ds.dumps(original))
# Types are preserved automatically!

📚 Development Workflow Integration

Interactive Development

# In Jupyter notebooks or interactive development
def explore_data(data):
    # Get recommendations
    ds.help_api()

    # Serialize with appropriate function
    if "model" in str(type(data)):
        return ds.dump_ml(data)
    elif "sensitive" in data:
        return ds.dump_secure(data)
    else:
        return ds.dump(data)

# Programmatic API selection
info = ds.get_api_info()
best_function = info['recommendations']['for_data_type'](type(my_data))

Documentation and Onboarding

# For new team members
def onboard_developer():
    print("Welcome to datason!")
    ds.help_api()

    print("\nDetailed API information:")
    info = ds.get_api_info()
    print(f"Available functions: {len(info['all_functions'])}")
    print(f"Supported data types: {info['features']['supported_types']}")

    print("\nTry these examples:")
    print("ds.dump_ml(model_data)  # For ML workflows")
    print("ds.dump_api(response)   # For web APIs")
    print("ds.load_smart(json)     # For production loading")

🔗 Related Documentation

• Modern API Overview - Complete modern API guide
• Serialization Functions - Dump functions
• Deserialization Functions - Load functions
• Quick Start Guide - Getting started tutorial