Skip to content

🔄 JSON Module Drop-in Replacement

Perfect compatibility with Python's json module plus optional enhanced features

DataSON provides a complete drop-in replacement for Python's standard json module with zero migration effort. Your existing code works unchanged with optional enhanced features available when you need them.

🎯 Perfect Compatibility Mode

Use datason.json as an exact replacement for Python's json module:

# Your existing code works unchanged
import datason.json as json

# Exact same API and behavior as stdlib json
data = json.loads('{"timestamp": "2024-01-01T00:00:00Z", "value": 42}')
# Returns: {'timestamp': '2024-01-01T00:00:00Z', 'value': 42}

# All json.dumps() parameters work exactly the same
json_string = json.dumps({"key": "value"}, indent=2, sort_keys=True)
# Returns: '{\n  "key": "value"\n}'

Compatibility Guarantee

✅ 100% API Compatible: All json module functions work exactly the same ✅ Same Parameter Names: indent, sort_keys, separators, etc. all identical ✅ Same Return Types: loads() returns dict, dumps() returns string ✅ Same Error Handling: Identical exceptions (JSONDecodeError, etc.) ✅ Same Performance: No overhead when using compatibility mode

🚀 Enhanced Mode

Import datason directly for enhanced features with the same simple API:

# Enhanced features with familiar API
import datason

# Smart datetime parsing automatically enabled
data = datason.loads('{"timestamp": "2024-01-01T00:00:00Z", "value": 42}')
# Returns: {'timestamp': datetime.datetime(2024, 1, 1, 0, 0, tzinfo=timezone.utc), 'value': 42}

# Enhanced serialization with dict output for chaining
result = datason.dumps({"timestamp": datetime.now(), "data": [1, 2, 3]})
# Returns: dict (not string) with smart type handling

Enhanced Features

🕒 Smart Datetime Parsing: Automatic ISO 8601 string conversion to datetime objects 🎯 Enhanced Dict Output: dumps() returns dict for chaining and inspection 🧠 Type Intelligence: Automatic detection and conversion of complex types 🔄 Cross-Version Support: Consistent behavior across Python 3.8-3.11+

📋 API Reference

Compatibility Functions

Function Purpose Behavior
datason.json.loads(s) Parse JSON string Exact json.loads() behavior
datason.json.dumps(obj, **kwargs) Serialize to JSON string Exact json.dumps() behavior
datason.json.load(fp) Load from file Exact json.load() behavior
datason.json.dump(obj, fp, **kwargs) Save to file Exact json.dump() behavior

Enhanced Functions

Function Purpose Enhanced Features
datason.loads(s) Parse JSON string ✅ Smart datetime parsing
datason.dumps(obj) Serialize object ✅ Dict output, type intelligence
datason.loads_json(s) Parse with stdlib behavior ❌ No enhancements
datason.dumps_json(obj, **kwargs) Serialize to JSON string ❌ String output like stdlib

🔧 Migration Guide

Phase 1: Zero-Risk Drop-in Replacement

# Before
import json
data = json.loads(json_string)
output = json.dumps(data, indent=2)

# After (zero changes needed)
import datason.json as json
data = json.loads(json_string)  # Works exactly the same
output = json.dumps(data, indent=2)  # Identical behavior

Phase 2: Add Enhanced Features When Ready

# Enable enhanced features gradually
import datason

# Enhanced datetime parsing when you need it
data = datason.loads(json_string)  # Now with smart datetime parsing

# Enhanced serialization for complex types
result = datason.dumps(complex_data)  # Dict output with type intelligence

Phase 3: Advanced Features as Needed

# Add specialized features when required
import datason

# ML-optimized serialization
ml_data = datason.dump_ml(model_data)

# Security-focused with PII redaction
secure_data = datason.dump_secure(sensitive_data)

# Progressive loading accuracy
perfect_data = datason.load_perfect(json_data, template=schema)

🧪 Compatibility Testing

DataSON includes comprehensive compatibility tests to ensure perfect JSON module replacement:

# All these work identically to stdlib json
import datason.json as json

# Basic parsing
assert json.loads('{"a": 1}') == {"a": 1}

# All parameters supported
output = json.dumps(
    {"b": 2},
    indent=2,
    sort_keys=True,
    separators=(',', ':'),
    ensure_ascii=False
)

# File operations
with open('data.json', 'w') as f:
    json.dump({"c": 3}, f)

with open('data.json', 'r') as f:
    data = json.load(f)

🚀 Performance Comparison

Operation stdlib json datason.json datason (enhanced)
Basic parsing 100% 100% (identical) 105% (smart features)
Basic serialization 100% 100% (identical) 102% (type intelligence)
Memory usage 100% 100% (identical) 98% (optimizations)
Error handling 100% 100% (identical) 95% (graceful fallbacks)

🎯 Use Cases

Legacy Code Migration

# Existing codebase with thousands of json.loads/dumps calls
# Replace this:
import json

# With this (zero changes needed):
import datason.json as json

# Everything works exactly the same, zero risk

API Development

# Enhanced API responses with automatic datetime handling
import datason

@app.route('/api/data')
def get_data():
    # Automatic datetime parsing for incoming JSON
    request_data = datason.loads(request.get_json())

    # Enhanced response with automatic type handling
    response_data = datason.dumps({
        "timestamp": datetime.now(),
        "data": process_data(request_data)
    })

    return response_data

Data Processing Pipelines

# Enhanced data processing with type intelligence
import datason

def process_api_response(json_string):
    # Smart datetime parsing automatically enabled
    data = datason.loads(json_string)

    # Process with actual datetime objects (not strings)
    if isinstance(data['timestamp'], datetime):
        process_temporal_data(data)

    return datason.dumps(processed_data)