Metadata-Version: 2.4
Name: jospy
Version: 0.2.0
Summary: JSON helpers for Python REST API developers.
Keywords: json,rest,api,serialization,payload
Author: Veeresh Hanni
Author-email: Veeresh Hanni <veereshhanni347@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: build>=1.2 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: twine>=5 ; extra == 'dev'
Requires-Dist: myst-parser>=4 ; extra == 'docs'
Requires-Dist: sphinx>=8 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3 ; extra == 'docs'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/Veeresh-Hanni/jospy
Project-URL: Documentation, https://jospy.readthedocs.io/
Project-URL: Issues, https://github.com/Veeresh-Hanni/jospy/issues
Project-URL: Source, https://github.com/Veeresh-Hanni/jospy
Provides-Extra: dev
Provides-Extra: docs
Description-Content-Type: text/markdown

jospy
=====

[![Documentation Status](https://readthedocs.org/projects/jospy/badge/?version=latest)](https://jospy.readthedocs.io/en/latest/?badge=latest)

`jospy` is a small Python utility package for JSON payloads and REST API
responses. It uses Python's built-in `json` module and adds a friendlier layer
for common backend work: JSON to Python, Python to JSON, null handling, default
filling, filtering, nested paths, and response envelopes.

Install it locally while developing:

```bash
pip install -e ".[dev]"
```

Basic usage:

```python
from jospy import api_response, fill, filter_data, null, to_json, to_python

payload = to_python('{"name": "Ada", "email": null}')
payload = fill(payload, {"active": True, "email": "unknown@example.com"})

public_payload = filter_data(payload, exclude=["password"], drop_nulls=True)
body = to_json(api_response(public_payload, message="ok"), pretty=True)
```

Chainable data layer:

```python
from jospy import data

users = [
    {"id": 1, "name": "Ada", "team": "api", "email": None, "password": "secret"},
    {"id": 2, "name": "Grace", "team": "infra", "email": "g@example.com"},
]

body = (
    data(users)
    .where(team="api")
    .filter(exclude=["password"], drop_nulls=True)
    .api_response(message="ok")
    .to_json(pretty=True)
)
```

Highlights:

- `to_python()` / `from_json()` convert JSON strings, bytes, or files to Python.
- `to_json()` serializes Python data to compact or pretty JSON.
- `data()` creates a chainable data layer for `.fill().filter().api_response()`.
- `null()` returns `None` with no arguments, or checks if values are `None`.
- `fill()` recursively fills missing or `None` fields with defaults.
- `filter_data()` filters dictionaries or lists by fields, predicates, and nulls.
- `pick()` / `omit()` are quick field-selection helpers.
- `get_path()` / `set_path()` work with nested dot paths like `user.email`.
- `api_response()` and `paginated()` create consistent REST API response shapes.

REST API example:

```python
from jospy import api_response, paginated


def get_user_response(user):
    return api_response(user, message="User loaded")


def list_users_response(users, page=1):
    return paginated(users, page=page, per_page=25)
```

Nested data example:

```python
from jospy import data

payload = (
    data({})
    .set("user.profile.email", "ada@example.com")
    .set("user.active", True)
)

email = payload.get("user.profile.email").unwrap()
```

Documentation
-------------

Read the hosted docs at <https://jospy.readthedocs.io/> or see
[docs/index.md](docs/index.md) locally for the full helper reference and
examples.

Read the Docs setup notes live in [docs/readthedocs.md](docs/readthedocs.md).

Development
-----------

Run tests:

```bash
python -m pytest
```

Build the package:

```bash
python -m build
python -m twine check dist/*
```
