Metadata-Version: 2.4
Name: jospy
Version: 0.1.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-Python: >=3.10
Project-URL: Homepage, https://github.com/veeresh-hanni/jospy
Project-URL: Documentation, https://github.com/veeresh-hanni/jospy#readme
Project-URL: Issues, https://github.com/veeresh-hanni/jospy/issues
Project-URL: Source, https://github.com/veeresh-hanni/jospy
Provides-Extra: dev
Description-Content-Type: text/markdown

jospy
=====

`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)
```

Highlights:

- `to_python()` / `from_json()` convert JSON strings, bytes, or files to Python.
- `to_json()` serializes Python data to compact or pretty JSON.
- `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)
```

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

See [docs/index.md](docs/index.md) for the full helper reference and examples.

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

Run tests:

```bash
python -m pytest
```