Metadata-Version: 2.5
Name: iidict
Version: 0.0.1
Summary: JSON helpers for the messy cases: sets, datetimes, Decimals, streams.
Project-URL: Homepage, https://github.com/lqxnjk/iidict
Project-URL: Source, https://github.com/lqxnjk/iidict
Author: lqxnjk
License: MIT
License-File: LICENSE
Keywords: datetime,decimal,deserialize,json,serialize,stream
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# iidict

`json.dumps` refuses sets, datetimes, Decimals and most custom objects. `iidict`
normalizes them first, and can also **stream** a large JSON file into objects
without loading it whole.

## Install

```console
pip install iidict
```

## Usage

```python
from datetime import datetime
from decimal import Decimal

from iidict import IIDict

IIDict.dumps({"tags": {"a", "b"}, "at": datetime(2026, 10, 23), "price": Decimal("1.50")})
# '{"tags": ["a", "b"], "at": "2026-10-23 00:00:00", "price": 1.5}'

IIDict.dumps({"a": 1}, n_string=False)        # -> bytes
IIDict.dumps({"a": 1}, n_indent=2)           # pretty printed

IIDict.loads('{"a": 1}')                     # {'a': 1}
```

### Streaming

`iter_loads` walks a **top-level JSON object** one key/value pair at a time, so
a multi-gigabyte file never has to fit in memory:

```python
for key, value in IIDict.iter_loads("huge.json"):
    store(key, value)
```

The top level must be an object (`{...}`). A top-level array raises
`ValueError` rather than silently yielding nothing — use `loads` for those.

`dump_iter` writes the same shape out through an already open file handle:

```python
with open("out.json", "w", encoding="utf-8") as handle:
    IIDict.dump_iter(records, handle)
```

### Normalization

`fmt` rewrites arbitrary objects into JSON-compatible ones:

| Input | Output |
| --- | --- |
| `set` / `frozenset` | `list` |
| `datetime` / `date` / `time` | `"YYYY-MM-DD HH:MM:SS"` style string |
| `Decimal` | number (`float`) |
| object with `__dict__` | its `__dict__` |

## API

| Method | Description |
| --- | --- |
| `dumps(data, string=True, indent=None)` | Serialize, tolerating non-JSON types |
| `loads(data)` | Deserialize `str` or `bytes` |
| `iter_loads(path, chunk=64 KiB)` | Stream `(key, value)` pairs of a top-level object |
| `dump_iter(data, dst)` | Write a top-level object to an open file handle |
| `fmt(data)` | Recursively normalize to JSON-compatible types |

Unrecognized objects fall back to `str(obj)` **and log a warning** rather than
failing the whole serialization silently.

## License

MIT
