Skip to content

Clarify compat vs enhanced modes #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
danielendler wants to merge 2 commits into from
Closed

Clarify compat vs enhanced modes #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ab95196
feat: add explicit compat mode and docs
danielendler Aug 7, 2025
c9362d8
test: add compat parity suite
danielendler Aug 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
- 🚀 **Enhanced by Default**: Main API provides smart datetime parsing and type detection automatically
- ⚡ **Dual API Strategy**: Choose stdlib compatibility (`datason.json`) or enhanced features (`datason`)
- 🛠️ **Zero Migration**: Existing `json.loads/dumps` code works immediately with optional enhancements
- 📚 **Need help choosing?** See [Two Modes: When to Use Which](docs/two-modes.md)

### 🧠 **Intelligent Processing**
- 🧠 **Smart Type Detection**: Automatically handles pandas DataFrames, NumPy arrays, datetime objects, and more
Expand Down
6 changes: 6 additions & 0 deletions datason/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,12 @@
load_typed,
loads, # Enhanced default (smart parsing, datetime support)
loads_json, # JSON compatibility (exact stdlib behavior)
save,
save_api,
save_chunked,
save_ml,
save_secure,
save_string,
stream_dump,
stream_load, # Streaming deserialization for large files
stream_save_ml,
Expand Down Expand Up @@ -228,6 +230,8 @@ def _get_version() -> str:
# Enhanced DataSON API (default recommended usage)
"dump", # Enhanced file writing with smart features
"dumps", # Enhanced serialization returning dict
"save", # Alias for dump
"save_string", # Enhanced JSON string serialization
"load", # Enhanced file reading with smart parsing
"loads", # Enhanced string parsing with smart features
"serialize", # Enhanced serialization (returns dict)
Expand Down Expand Up @@ -276,6 +280,8 @@ def _get_version() -> str:
"dump_chunked",
"stream_dump",
# File I/O Operations - Modern API Integration
"save",
"save_string",
"save_ml",
"save_secure",
"save_api",
Expand Down
25 changes: 25 additions & 0 deletions datason/api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,19 @@ def dump(obj: Any, fp: Any, **kwargs: Any) -> None:
save_ml(obj, fp, **kwargs)


def save(obj: Any, fp: Any, **kwargs: Any) -> None:
"""Enhanced file serialization alias.

This function mirrors :func:`dump` but uses a name that emphasizes
DataSON's role as an enhanced saver rather than a drop-in
replacement. Behaviour is identical to :func:`dump` and therefore
differs from :func:`json.dump` by performing type preservation and
datetime handling.
"""

dump(obj, fp, **kwargs)


def dump_json(
obj: Any,
fp: Any,
Expand Down Expand Up @@ -956,6 +969,18 @@ def dumps_json(
return dumps_json_stdlib(serialized, **json_params)


def save_string(obj: Any, **kwargs: Any) -> str:
"""Enhanced serialization to JSON string.

This is an alias for :func:`dumps_json` that highlights the
difference from :func:`json.dumps`. DataSON performs type
inference and normalization before encoding the result as a JSON
string.
"""

return dumps_json(obj, **kwargs)


# =============================================================================
# MIGRATION HELPERS - For smooth transition from old API
# =============================================================================
Expand Down
181 changes: 0 additions & 181 deletions datason/json.py
View file
Open in desktop

This file was deleted.

13 changes: 13 additions & 0 deletions datason/json/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
"""Standard library JSON compatibility module.

This package re-exports Python's built-in :mod:`json` module so that
``import datason.json as json`` provides a strict drop-in replacement.
All functions, classes, and exceptions behave exactly like the
standard library version.
"""

import json as _json
from json import * # noqa: F401,F403

__all__ = getattr(_json, "__all__", []) # type: ignore[attr-defined]
__doc__ = _json.__doc__
12 changes: 12 additions & 0 deletions docs/api/modern-deserialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ basic_data = ds.load_basic(json_data)
# Basic types only, minimal processing
```

!!! warning "Breaking behavior"
Unlike `json.loads`, `load_basic()` may convert ISO formatted
strings to :class:`datetime.datetime` objects.

### load_smart()

Intelligent deserialization with good accuracy for production use.
Expand All @@ -120,6 +124,10 @@ smart_data = ds.load_smart(json_data)
print(type(smart_data["timestamp"])) # <class 'datetime.datetime'>
```

!!! warning "Breaking behavior"
Performs aggressive type inference (datetimes, UUIDs, pandas types)
beyond what `json.loads` provides.

### load_perfect()

Perfect accuracy deserialization using templates for mission-critical applications.
Expand All @@ -143,6 +151,10 @@ template = {
perfect_data = ds.load_perfect(json_data, template)
```

!!! warning "Breaking behavior"
Requires a template and can reconstruct complex Python types; the
standard library has no equivalent.

### load_typed()

High-accuracy deserialization using embedded type metadata.
Expand Down
30 changes: 30 additions & 0 deletions docs/api/modern-serialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ Intention-revealing dump functions for different use cases and optimization need

| Function | Purpose | Best For |
|----------|---------|----------|
| `save()` | Enhanced file writer (alias of `dump`) | Smart file output |
| `save_string()` | JSON string with type inference | String output |
| `dump()` | General-purpose with composable options | Flexible workflows |
| `dump_ml()` | ML-optimized for models and tensors | Data science |
| `dump_api()` | Clean JSON for web APIs | Web development |
Expand All @@ -21,6 +23,34 @@ Intention-revealing dump functions for different use cases and optimization need

## 📦 Detailed Function Documentation

### save()

Enhanced file serialization to path or file object.

::: datason.save
options:
show_source: true
show_signature: true
show_signature_annotations: true

!!! warning "Breaking behavior"
Unlike `json.dump`, `save()` performs type preservation and datetime
conversion before writing to disk.

### save_string()

Enhanced serialization that returns a JSON string.

::: datason.save_string
options:
show_source: true
show_signature: true
show_signature_annotations: true

!!! warning "Breaking behavior"
`save_string()` applies DataSON's type inference before producing a
JSON string, while `json.dumps` only handles basic types.

### dump()

General-purpose serialization with composable options.
Expand Down
40 changes: 40 additions & 0 deletions docs/two-modes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# 🔀 Two Modes: When to Use Which

DataSON offers two distinct ways to work with JSON data:

1. **Compat Mode** – a strict drop-in replacement for Python's `json` module.
2. **Enhanced Mode** – smarter serialization with type inference and modern helpers.

Use Compat Mode when you need guaranteed parity with the standard library.
Switch to Enhanced Mode when you want DataSON's advanced features.

## Compat Mode

```diff
-import json
+import datason.json as json

data = json.loads('{"created": "2024-01-01"}')
assert isinstance(data["created"], str)
```

## Enhanced Mode

```diff
-import json
+import datason

# Smart loading with type inference
item = datason.load_smart('{"created": "2024-01-01"}')
assert item["created"].year == 2024
```

## Choosing a Mode

| Use case | Recommended mode |
|----------|-----------------|
| Legacy code expecting `json` behavior | Compat Mode |
| Need datetime parsing or complex types | Enhanced Mode |
| Migrating gradually | Start with Compat, upgrade to Enhanced |

The two modes can coexist in the same project, letting you migrate at your own pace.
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ markdown_extensions:
# Fixed navigation using files that actually exist
nav:
- Home: index.md
- Two Modes: two-modes.md

# User Guide Section
- User Guide:
Expand Down
Loading