Skip to main content

paperjson

Paper-thin JSON serialization/deserialization for Python dataclasses. Easy to extend for custom classes.

Overview

paperjson recursively serializes dataclass fields to JSON and reconstructs them on deserialization. Fields with types like datetime, Path, Decimal, or any other non-JSON-native type are automatically handled.

Automatic stringification: When the serializer encounters a type it doesn't explicitly know about, it calls str() on the value and attempts a round-trip test — it calls Type(str_value) and checks whether the result equals the original. If the round-trip succeeds, str() is auto-registered for that type, so subsequent calls skip the check. If the round-trip fails, a TypeError is raised telling you to register a custom serializer.

You can always override the fallback by registering explicit serializers and deserializers for your own types (see Custom type support).

Usage

There are two ways to add to_json() / from_json() to a dataclass:

1A. Inherit from PaperJsonBase

Inheriting from PaperJsonBase gives full type-checker / LSP support — your editor will suggest to_json() and from_json():

from dataclasses import dataclass
import paperjson

@dataclass
class User(paperjson.PaperJsonBase):
    name: str
    email: str

user = User(name="Alice", email="alice@example.com")
print(user.to_json())
# {"name": "Alice", "email": "alice@example.com"}

restored = User.from_json(user.to_json())
print(restored == user)
# True

This is similar to Pydantic BaseModel. But! You might not wish to add a base to your class.

1B. Use the @serdes decorator

Decorate any dataclass to inject the methods at runtime. It works identically, but type checkers can't see to_json() / from_json():

from dataclasses import dataclass
import paperjson

@paperjson.serdes
@dataclass
class User:
    name: str
    email: str

user = User(name="Alice", email="alice@example.com")
print(user.to_json())  # type: ignore
# {"name": "Alice", "email": "alice@example.com"}

2. Type annotations with PaperJsonProtocol

Use PaperProtocol in function signatures to accept anything that has to_json() / from_json() — whether it inherits from PaperJsonBase or was decorated:

from typing import Any
import paperjson

def dump(obj: paperjson.PaperJsonProtocol[Any]) -> str:
    return obj.to_json(indent=2)

def load(cls: type[paperjson.PaperJsonProtocol[Any]], data: str) -> Any:
    return cls.from_json(data)

3. Custom type support

Register serializers and deserializers for any type that stringification can't handle, or when you need explicit control over the JSON representation.

from decimal import Decimal

import paperjson


@paperjson.register_serializer(Decimal)
def _(val: Decimal) -> str:
    return str(val)


@paperjson.register_deserializer(Decimal)
def _(val: str) -> Decimal:
    return Decimal(val)

Note: For a type like Decimal, the automatic stringification would actually succeed (d == Decimal(str(d)) == True), but registering explicitly is clearer.

4. Worked example

from datetime import datetime, timezone
from pathlib import Path
from dataclasses import dataclass

import paperjson


@dataclass
class Address(paperjson.PaperJsonBase):
    line1: str
    line2: str
    city: str
    st: str
    zip: str


@paperjson.serdes
@dataclass
class User():
    name: str
    dob: datetime
    email: str
    homedir: Path
    mail: Address


obj = User(
    name="Alice",
    dob=datetime.now(timezone.utc),
    email="alice@example.com",
    homedir=Path.home(),
    mail=Address("123 Main St", "", "Springfield", "IL", "62701"),
)

json_str = obj.to_json()
restored = User.from_json(json_str)

Output dataclasses are identical to those created:

>>> print(restored)
User(name='Alice', dob=datetime.datetime(2026, 5, 19, 4, 50, 7, 485835, tzinfo=datetime.timezone.utc), email='alice@example.com', homedir=PosixPath('/home/alice'), mail=Address(line1='123 Main St', line2='', city='Springfield', st='IL', zip='62701'))
>>> obj == restored
True

Metadata

Release files for paperjson 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for paperjson 0.2.0
File Size Uploaded Provenance Actions
paperjson-0.2.0.tar.gz 5.1 kB With provenance Details for paperjson-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for paperjson 0.2.0
File Interpreter ABI Platform Actions
paperjson-0.2.0-py3-none-any.whl Python 3 none any Details for paperjson-0.2.0-py3-none-any.whl

Total release size: 11.8 kB

Release files / paperjson-0.2.0.tar.gz

Download URL paperjson-0.2.0.tar.gz
Size 5.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1b6c25a722ae5efd9925ae71593bd89d4d43c90befefef53c4b3b2540e47ed04
BLAKE2b-256 checksum
How to use checksums
4455a712036847f85ba6ddbf6e983876c0f7e0156c861093eba68878f85c608f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 21, 2026.

Transparency log

Release files / paperjson-0.2.0-py3-none-any.whl

Download URL paperjson-0.2.0-py3-none-any.whl
Size 6.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3502c55205f9d27e60b92d56520435c20c22288c89bd5897407bf8ee1f3a56dd
BLAKE2b-256 checksum
How to use checksums
16f363507dafa4fa3248dd7b3935c7445e6085cbb5421d7608ca502ffc7f4345
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 21, 2026.

Transparency log

Security for paperjson 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for paperjson-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page