Metadata-Version: 2.4
Name: py-jsoneasy
Version: 0.0.5
Summary: A lightweight, dependency-free Python library for JSON Array - read, write, compress incrementally with ease
Author-email: rmoralespp <rmoralespp@gmail.com>
Project-URL: source, https://github.com/rmoralespp/jsoneasy
Project-URL: homepage, https://github.com/rmoralespp/jsoneasy
Project-URL: changelog, https://github.com/rmoralespp/jsoneasy/blob/main/CHANGELOG.md
Project-URL: issues, https://github.com/rmoralespp/jsoneasy/issues
Project-URL: documentation, https://rmoralespp.github.io/jsoneasy/
Keywords: json,gzip,bzip2,xz,zip,tar,utilities,serialization,deserialization
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Classifier: Topic :: File Formats :: JSON
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <strong>jsoneasy</strong>
</p>

<p align="center">
  <em>A lightweight, dependency-free Python library for JSON Array — read, write, compress incrementally with ease</em>
</p>

<p align="center">
  <a href="https://pypi.python.org/pypi/py-jsoneasy"><img src="https://img.shields.io/pypi/v/py-jsoneasy.svg" alt="PyPI version"></a>
  <a href="https://github.com/rmoralespp/jsoneasy"><img src="https://img.shields.io/pypi/pyversions/jsoneasy.svg" alt="Python versions"></a>
  <a href="https://github.com/rmoralespp/jsoneasy/actions?query=event%3Arelease+workflow%3ACI"><img src="https://github.com/rmoralespp/jsoneasy/workflows/CI/badge.svg" alt="CI"></a>
  <a href="https://app.codecov.io/gh/rmoralespp/jsoneasy"><img src="https://codecov.io/gh/rmoralespp/jsoneasy/branch/main/graph/badge.svg" alt="Coverage"></a>
  <a href="https://github.com/rmoralespp/jsoneasy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rmoralespp/jsoneasy.svg" alt="License"></a>
  <a href="https://pepy.tech/project/jsoneasy"><img src="https://pepy.tech/badge/py-jsoneasy" alt="Downloads"></a>
</p>

<p align="center">
  <a href="https://rmoralespp.github.io/jsoneasy/">Documentation</a>
  ·
  <a href="https://github.com/rmoralespp/jsoneasy/blob/main/CHANGELOG.md">Changelog</a>
  ·
  <a href="https://github.com/rmoralespp/jsoneasy/issues">Issues</a>
</p>

---

**jsoneasy** provides a simple, Pythonic API for working with JSON Arrays in a memory-efficient way.

It follows the conventions of Python's standard `json` module — if you know `json.dump` and `json.load`,
you already know how to use **jsoneasy**.

Fully compliant with the [json](https://json.org/) specifications.

## Features

| Feature                           | Description                                                                 |
|-----------------------------------|-----------------------------------------------------------------------------|
| 🌎 **Familiar API**               | Interface similar to the standard `json` module (`dump`, `load`)            |
| ⚡ **Streaming by default**        | Read and write incrementally via iterators, keeping memory usage low        |
| 🗜️ **Built-in compression**      | Transparent support for `gzip`, `bzip2`, and `xz`                           |
| 📦 **Archive support**            | Read and write `ZIP` and `TAR` archives (`.tar.gz`, `.tar.bz2`, `.tar.xz`)  |
| 📥 **Load from URLs**             | Pass a URL directly to `load()` or `load_archive()`                         |
| 🚀 **Customizable serialization** | Extend via standard `JSONEncoder`/`JSONDecoder` subclasses and extra kwargs |
| 🐍 **Zero dependencies**          | Uses only the Python standard library — nothing else                        |

## Installation

```bash
pip install py-jsoneasy
```

> Requires **Python 3.8+**. No external dependencies.

## Quick Start

### Write

```python
import jsoneasy

data = [
    {"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]},
    {"name": "May", "wins": []},
]

jsoneasy.dump(data, "players.json")
```

### Read

```python
import jsoneasy

for item in jsoneasy.load("players.json"):
    print(item)
```

### Read from a URL

```python
import jsoneasy

for item in jsoneasy.load("https://restcountries.com/v3.1/all?fields=name,capital"):
    print(item)
```

### Compressed files

The compression format is determined automatically — by file extension when writing,
and by [magic numbers](https://en.wikipedia.org/wiki/List_of_file_signatures) when reading
if the file extension is not recognized:

```python
import jsoneasy

data = [{"key": "value"}]

jsoneasy.dump(data, "file.json.gz")  # gzip
jsoneasy.dump(data, "file.json.bz2")  # bzip2
jsoneasy.dump(data, "file.json.xz")  # xz

for item in jsoneasy.load("file.json.gz"):
    print(item)
```

### Archives (ZIP / TAR)

```python
import jsoneasy

# Write multiple files into an archive
data = [
    ("users.json", [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]),
    ("orders.json", [{"id": 1, "total": 99.90}, {"id": 2, "total": 45.00}]),
]
jsoneasy.dump_archive("data.zip", data)

# Read them back from the archive
for filename, items in jsoneasy.load_archive("data.zip", pattern="*.json"):
    print(f"--- {filename} ---")
    for item in items:
        print(item)
```

### Multiple output files

```python
import jsoneasy

data = [
    ("file1.json", [{"name": "Alice"}, {"name": "Bob"}]),
    ("file2.json", [{"name": "Charlie"}]),
    ("file1.json", [{"name": "Eve"}]),  # appended to file1.json
]

jsoneasy.dump_fork(data)
```

## API Overview

### Reading

| Function                            | Description                                 |
|-------------------------------------|---------------------------------------------|
| `jsoneasy.load(source, **kw)`       | Read from a file, URL, or file-like object  |
| `jsoneasy.load_archive(file, **kw)` | Unpack JSON files from a ZIP or TAR archive |

> [!TIP]
> All **read** functions accept `cls` and `**kwargs` for custom deserialization (forwarded to `json.JSONDecoder`).

### Writing

| Function                                  | Description                                        |
|-------------------------------------------|----------------------------------------------------|
| `jsoneasy.dump(iterable, file, **kw)`     | Write objects to a JSON file                       |
| `jsoneasy.dump_fork(paths, **kw)`         | Write to multiple JSON files at once               |
| `jsoneasy.dump_archive(path, data, **kw)` | Pack multiple JSON files into a ZIP or TAR archive |

> [!TIP]
> All **write** functions accept `cls` and `**kwargs` for custom serialization (forwarded to `json.JSONEncoder`).

For complete parameter documentation, see the [full docs →](https://rmoralespp.github.io/jsoneasy/)

## Custom Serialization

Extra keyword arguments are forwarded to the underlying `json.JSONEncoder` / `json.JSONDecoder`.
You can also pass a custom `cls` subclass for full control:

```python
import jsoneasy

data = [{"name": "Alice", "score": 9.5}, {"name": "Bob", "score": 7.2}]

jsoneasy.dump(data, "compact.json", separators=(",", ":"))  # compact output
jsoneasy.dump(data, "sorted.json", sort_keys=True)  # deterministic keys
jsoneasy.dump(data, "pretty.json", indent=2)  # indented output
```

## Supported Formats

| Type        | Extensions                               |
|-------------|------------------------------------------|
| Plain       | `.json`                                  |
| Compressed  | `.json.gz`, `.json.bz2`, `.json.xz`      |
| ZIP archive | `.zip`                                   |
| TAR archive | `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz` |

> When reading, if the file extension is not recognized, **jsoneasy** falls back to
> [magic-number detection](https://en.wikipedia.org/wiki/List_of_file_signatures)
> to identify the compression format automatically.

## Contributing

```bash
# Install dev dependencies
pip install --group=test --upgrade

# Run tests
python -m pytest tests/
python -m pytest tests/ --cov  # run with coverage reporting

# Lint
pip install --group=lint --upgrade
ruff check .

# Docs
pip install --group=doc --upgrade

# zensical usage: https://zensical.org/docs/usage/
zensical build 
zensical serve
```

## License

MIT — see [LICENSE](LICENSE) for details.
