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:

pip install -e ".[dev]"

Basic usage:

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:

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:

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:

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 locally for the full helper reference and examples.

Read the Docs setup notes live in docs/readthedocs.md.

Development

Run tests:

python -m pytest

Build the package:

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