[dmccoystephenson]

Summary

Stage A documentation accuracy sweep. The README's "The wire format" section and the report() docstring were checked against _json, _with_version and report(); three behaviors the code has (each already covered by a test) were undocumented:

• value is omitted not only when absent but also when NaN or ±infinity (_json; test_json_drops_nan_and_none_tags, test_json_drops_infinite_values_but_keeps_zero).
• A tag whose key or value is None is left out, and other keys/values are sent as strings (_with_version, _json).
• An event with a blank name is not sent at all (report(); test_report_ignores_a_blank_name).

The rest of the sweep (promises table, "Turning it off", constructor/install-ID docs, module headers, pyproject.toml, "Building" vs. build.yml) found no drift.

No code behavior changed; the only edit to trace_client/trace_client.py is the report() docstring. No Java-visible behavior changed, so trace-client-java needs no matching change.

Test plan

• python3 -m unittest: ran 67 tests, OK, locally
• CI Build green on 3.8 / 3.10 / 3.12

No tracking issue: the gap was found during triage. #16 was skipped again because it still waits on an owner decision about the MAX_TAGS cap and needs a coordinated trace-client-java change. The README sentence "tags always holds at least version" was left as is for that reason.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (head 999871a, CI run 40076138281):

• Scope: PASS — only README.md (wire-format paragraph) and the report() docstring in trace_client/trace_client.py are changed; no code lines.
• Tests-new: PASS (not applicable) — no new public names.
• Tests-fix: PASS (not applicable) — docs-only, no bug fix.
• Sibling structure / renames: PASS (not applicable) — no new files, no renames.
• Docs: PASS — each new claim was checked against source: NaN/±inf value omission (_json, line 352; test_json_drops_infinite_values_but_keeps_zero), None key/value tags left out and others stringified (_with_version, _json; test_json_drops_nan_and_none_tags), blank name not sent (report(); test_report_ignores_a_blank_name).
• Issue resolution: PASS (not applicable) — no Closes; The version tag is added even when it pushes an event past MAX_TAGS #16 left open on purpose.
• CI: PASS — test (3.8), test (3.10), test (3.12) green on the head SHA.
• Stdlib-only / Py3.8 floor / never-raises / log level / exports: PASS — no imports, logging or code paths touched; 3.8 job green.
• Version agreement: PASS — no version string touched (0.4.1 in all five places).
• Java parity noted: PASS — the PR body says no Java-visible behavior changed.

Finding fixed during review:

• trace_client/trace_client.py:248 — the first wording ("A blank name is dropped; so is a NaN or infinite value") could be read as dropping the whole event for a NaN value. The code only omits the field, so it was reworded in 1aae4f0 to "is left out of the event". An empty commit (999871a) then re-triggered CI, because the push of 1aae4f0 did not start a run.

Docs-only change, verified against source and green CI; ready to merge.

This review comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson