Skip to main content

tallipoika

A stable son (Finnish: tallipoika) — a JSON Canonicalization Scheme (JCS) implementation conforming to RFC 8785.

Requires Python 3.11 or later.

Install

pip install tallipoika

For a faster JSON parser on large input (msgspec-backed; parsing only, canonicalization is unaffected), install the fast-parse extra:

pip install 'tallipoika[fast-parse]'

Manual

The man page provides the CLI reference (man tallipoika after placing the file on your MANPATH):

mkdir -p ~/.local/share/man/man1
cp docs/man/tallipoika.1 ~/.local/share/man/man1/

Quickstart

Run tallipoika with no arguments for a usage summary, or tallipoika --version to check the installed version.

The library function for canonical JSON is canonicalize:

from tallipoika.api import canonicalize

result = canonicalize({"b": 2, "a": 1})
# b'{"a":2,"b":1}'

To serialize without key sorting, use serialize:

from tallipoika.api import serialize

result = serialize({"b": 2, "a": 1})
# b'{"b":2,"a":1}'

The command line tool reads JSON from a file or stdin and writes to a file or stdout:

tallipoika --in-path input.json --out-path output.json
echo '{"b":2,"a":1}' | tallipoika
# {"a":2,"b":1}

RFC 8785 compliance

tallipoika implements the JSON Canonicalization Scheme (JCS) defined by RFC 8785:

  • UTF-8 output: all output is UTF-8 encoded bytes.
  • No whitespace: no indentation, no spaces around : or ,.
  • Key sort by UTF-16BE byte order: object keys are sorted by their UTF-16BE encoding, which matches the ES6 String.prototype.localeCompare ordering used by JCS-compliant implementations.
  • ES6 §7.1.12.1 number serialization: floats are serialized using the shortest representation that round-trips through the ES6 number parsing algorithm.
  • NaN and Infinity rejected: allow_nan=False by default per RFC 8785 §3.2.2.3.
  • Control character escaping: code points U+0000–U+001F are escaped as \uXXXX.
  • Unicode passthrough: non-ASCII characters above U+001F pass through verbatim (ensure_ascii=False by default).

API

canonicalize(obj, utf8=True) -> bytes

Produce RFC 8785 JCS-canonical JSON for obj. Raises ValueError for NaN or Infinity float values. Raises TypeError for non-serializable objects.

serialize(obj, utf8=True) -> bytes

Produce JSON without key sorting; all other RFC 8785 rules (number format, control-character escaping, no whitespace) still apply.

canonicalize_to(obj, fp) -> None and serialize_to(obj, fp) -> None

Write the same bytes as canonicalize(obj) or serialize(obj) to the binary file object fp (anything with write(bytes)), in batches as they are encoded, without building the whole result: for large documents this lowers the memory peak by about a third. An error (NaN, a non-serializable value) can surface after earlier batches were written, so write to a temporary file and keep it only on success when all or nothing matters.

from tallipoika.api import canonicalize_to

with open('output.json', 'wb') as fp:
    canonicalize_to({"b": 2, "a": 1}, fp)

JSONEncoder

The underlying encoder class with JCS defaults:

from tallipoika.api import JSONEncoder

encoder = JSONEncoder(sort_keys=True)
output = encoder.encode({"b": 2, "a": 1})
# '{"a":2,"b":1}'

Constructor keyword arguments and their JCS defaults:

Argument JCS default Description
skipkeys False Skip non-string keys instead of raising TypeError
ensure_ascii False Escape non-ASCII; disabled for Unicode passthrough
check_circular True Raise ValueError on circular references
allow_nan False Reject NaN/Infinity per RFC 8785 §3.2.2.3
sort_keys True Sort object keys by UTF-16BE byte order
indent None No indentation
separators (',', ':') No whitespace around , or :
default None Custom serializer for non-standard types

CLI

tallipoika [--in-path PATH] [--out-path PATH] [--serialize-only] [--no-fast-parse] [--no-streaming] [--version]
Option Default Description
--in-path PATH stdin Input JSON file; also accepted as positional argument
--out-path PATH stdout Output path; UTF-8 bytes to the file or to stdout
--serialize-only off Serialize only — do not sort keys
--no-fast-parse off Disable the msgspec fast parser (if installed); use json instead
--no-streaming off Build the whole result, then write it: more memory, all-or-nothing stdout
--version, -V — Print version string and exit

Design and requirements

Document Identifier File
Software Requirements Specification TAL-SRS-001 docs/requirements/srs/
Software Design Description TAL-SDD-001 docs/design/sdd/

Both documents follow the MIL-STD-498 DID structure.

Bug Tracker

Any feature requests or bug reports shall go to the todos of tallipoika.

Primary Source repository

The main source of tallipoika is on a mountain in Central Switzerland under configuration control (fossil).

Contributions

If you like to share small changes under the repositories license please kindly do so by sending a patchset. You can send such a patchset per email using git send-email.

Support

Please kindly submit issues at https://todo.sr.ht/~sthagen/tallipoika or write plain text email to ~sthagen/tallipoika@lists.sr.ht to support. Thanks.

Security Policy

See SECURITY.md for the security policy.

Changes

See docs/releases/ for release summaries and docs/releases/changes/ for the detailed change log.

Coverage

The test suite maintains high branch coverage (≥97%). The HTML report (if generated) is in site/coverage/.

SBOM

Runtime dependency information is published in docs/sbom/ in SPDX 3.0 (JSON-LD) and CycloneDX 1.6 (JSON) formats. See docs/sbom/README.md for the component inventory and validation guide.

Metadata

Release files for tallipoika 2026.11.7

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

Source distribution (sdist)

Source distribution for tallipoika 2026.11.7
File Size Uploaded Provenance Actions
tallipoika-2026.11.7.tar.gz 52.8 kB Without provenance Details for tallipoika-2026.11.7.tar.gz

Built distribution (wheel)

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

Total release size: 76.5 kB

Release files / tallipoika-2026.11.7.tar.gz

Download URL tallipoika-2026.11.7.tar.gz
Size 52.8 kB
Tags Source
SHA-256 checksum
How to use checksums
df8ab2b88bd6435afeef5d1040206686b3fc99a67e7d27f3a915dbe84eceeadf
BLAKE2b-256 checksum
How to use checksums
331b2bd52cf4261b6845b01bc1e9247d0574d760497303ea7e719c6975cba25f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Release files / tallipoika-2026.11.7-py3-none-any.whl

Download URL tallipoika-2026.11.7-py3-none-any.whl
Size 23.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
423249fd7ff2839884fbe7c5aac694430519d5d69c607129677853f3677cddfb
BLAKE2b-256 checksum
How to use checksums
fc10967161a419770fd9616773b2e740b90f71ad648b6ee2636eec35cc0a2bac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.5

Security for tallipoika 2026.11.7

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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