Write Deterministic JSON for Local CLI Reports

Batu Lab Notes · Batu

Unstable serialization can create noisy diffs and brittle golden-output comparisons. Define a report policy for indentation, object-key ordering, character encoding, numeric values, array order, and trailing newlines.

Quick answer

For repeatable report files, use fixed indentation, sort object keys, preserve a defined array order, write UTF-8 with LF line endings, and reject non-finite numbers. Check bytes when exact output formatting is part of your CLI contract.

Runnable example

Save this as write_report.py in a temporary working directory. It creates or overwrites report.json in that directory. The filenames inside the report are synthetic strings; the script does not read those files. Run:

python3 write_report.py
import json
from pathlib import Path


def write_report(path: Path, report: dict) -> None:
    rendered = json.dumps(
        report,
        indent=2,
        sort_keys=True,
        ensure_ascii=False,
        allow_nan=False,
    )

    with path.open("w", encoding="utf-8", newline="\n") as output:
        output.write(rendered)
        output.write("\n")


report = {
    "summary": {"warnings": 1, "files_checked": 3},
    "tool": "local-report",
    "findings": [
        {"path": "README.md", "status": "ok"},
        {"path": ".env", "status": "warning"},
    ],
}

write_report(Path("report.json"), report)
print("Wrote report.json")

Expected output

The command prints:

Wrote report.json

The resulting report.json is:

{
  "findings": [
    {
      "path": "README.md",
      "status": "ok"
    },
    {
      "path": ".env",
      "status": "warning"
    }
  ],
  "summary": {
    "files_checked": 3,
    "warnings": 1
  },
  "tool": "local-report"
}

The file ends with one newline after the closing brace.

Serialization policy

  • indent=2 fixes the pretty-printed layout.
  • sort_keys=True sorts dictionary keys, reducing differences caused only by construction order.
  • ensure_ascii=False preserves non-ASCII characters when the file is written as UTF-8.
  • allow_nan=False raises ValueError for NaN, Infinity, and -Infinity, which are outside strict JSON.
  • newline="\n" and the explicit final "\n" establish the intended line-ending and trailing-newline policy.

Python documents these json options and their behavior in the standard-library reference. [1]

Golden-output fixture

If formatting is part of the CLI contract, compare complete bytes. Create tests/fixtures/report.expected.json, copy the expected JSON shown above, and save it as UTF-8 with LF line endings and one final newline. Then run this check from the working directory:

from pathlib import Path

actual = Path("report.json").read_bytes()
expected = Path("tests/fixtures/report.expected.json").read_bytes()

assert actual == expected

This comparison checks the complete encoded result, including key order, indentation, line endings, and the trailing newline. A text reader may normalize line endings; a byte comparison keeps that difference visible. Review a fixture update against the intended output rather than replacing it automatically when a test fails.

Limits

  • Sorting dictionary keys does not sort arrays. Define array order in the report schema, and sort records only when their order has no semantic meaning.
  • JSON consumers should not depend on object-member order for data semantics, even when stable ordering is useful for readable diffs.
  • Use consistent string keys when relying on sorted output.
  • Exact-text fixtures will change when the serialization policy changes; review such changes intentionally.
  • allow_nan=False rejects non-finite floating-point values but does not validate the broader meaning or quality of the report.
  • This is a report-formatting policy, not a cross-language canonical JSON format for cryptographic signatures. Keep the schema, serializer settings and runtime under review.
  • Writing is not atomic and the full report is built in memory. A failed write can leave a partial file. Large reports or crash-safe persistence need a different storage design.

Related guide

Use the bounded Python text-file comparison guide when you need a readable diff after a byte comparison fails. Avoid sharing a report diff before checking it for private data.

Sources

[1] Python Software Foundation, “json — JSON encoder and decoder,” verified source packet retrieved 2026-09-08. The reference documents indent, sort_keys, ensure_ascii, allow_nan, separators, output ordering, and JSON serialization behavior.

[2] Python documentation: Path.open and file access.

[3] Python documentation: open encoding, newline handling and write mode.

Disclosure: Prepared with AI assistance. The example and expected output were independently checked with synthetic data on Python 3.14.7 on 8 September 2026. This validates the stated cases, not every possible input or operating system.

Comments

Post a Comment

Popular posts from this blog

Compare Two Text Files in Python Without Modifying Them

Batu Lab Notes · Batu When comparing two versions of a configuration or notes file, “are they the same?” is only the first question. The bytes may be identical, the visible text may be equal despite different line endings, or the content may contain a real change. For small UTF-8 text files, Python’s standard library can show these distinctions without writing to either input. Quick answer For small, stable UTF-8 files, read bounded bytes, compare them first, then decode and produce a bounded unified diff. Decide explicitly whether newline differences matter. Keep both inputs read-only and review the diff for private data before sharing it. Set a limit before reading Loading an input of unknown size directly into memory is a poor default. This example checks both sizes with Path.stat() , then performs a bounded read and applies a 256 KiB limit per file. It rejects directories and other non-regular paths. If reading raises OSError , the result includes the exception ty...
Read more

Seven CSV Quality Checks to Run Before Importing Data

Batu Lab Notes · Batu A CSV file is not ready for import merely because it opens. The wrong delimiter can collapse an entire row into one column. An unexpected encoding can damage non-ASCII characters. A repeated identifier can overwrite an existing record in the destination. A short, read-only check makes these problems visible before data reaches a spreadsheet or application. Quick answer Before importing a CSV, set its encoding and delimiter, validate the exact header and every row width, distinguish empty IDs, duplicate IDs, and duplicate rows, and keep the check read-only. 1. Specify the encoding Python may open a text file with the platform’s default encoding, which can differ across machines. If the expected encoding is UTF-8, encoding="utf-8-sig" is a practical choice: it reads ordinary UTF-8 and skips an optional UTF-8 byte order mark at the start. If decoding fails, verify the source application’s export settings instead of silently trying unrelat...
Read more

Explain why SQLite transactions cannot make an HTTP call atomic

Direct answer A SQLite transaction can atomically commit database statements handled by that connection. It cannot include an HTTP service in the same commit protocol. The example commits an outbox row first, then simulates a network failure. The durable row remains pending , which is exactly the information a later delivery worker needs instead of pretending both actions succeeded or failed together. The edge case is failure after the database commit but before remote acknowledgement. Retrying then requires an idempotency design owned by the remote endpoint or a stable request key; it is not supplied by SQLite’s COMMIT . Conversely, sending the request before storing a durable intent can leave no local evidence when the process stops. This demonstration intentionally does not make an HTTP request, implement an outbox dispatcher, or prove delivery exactly once. It shows the boundary that must be designed around. Use transactions to protect the local state transition, and test remote...
Read more