Skip to content

Say that an empty value of another type still means no value - #39

Merged
dmccoystephenson merged 1 commit into
mainfrom
trace/doc-empty-non-string-arguments
Nov 12, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
trace/doc-empty-non-string-arguments

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • A documentation accuracy sweep (Stage A) was run against trace_client/trace_client.py, pyproject.toml, trace_client/__init__.py and .github/workflows/build.yml.
  • One drift was found. README.md ("Every event carries the program's version") and the TraceClient.__init__ docstring both said that any non-string base_url, application, version, key or install_id raises a ValueError naming the argument. The type check is if given and not isinstance(given, str), so an empty value of another type (0, False, []) is let through and keeps its old meaning: no key (disabled_reason == "no key"), no installation ID, or "<argument> is required" for the positional arguments. That behavior is deliberate and pinned by test_an_empty_value_of_another_type_keeps_its_old_meaning, so the docs were corrected and the code was left alone.
  • Everything else in the Phase 7 table was checked against source and matched: the promises table (256 capacity, 5 s timeout, DEBUG on trace), the opt-out values and precedence, the disabled_reason strings, the wire format (endpoint, headers, omission rules, 201, no redirects, User-Agent), the Building section vs. the CI matrix, and the version string in all five places (0.4.2).

No tracking issue: the gap was found during the triage sweep.

Skipped issue: #16 was not picked. It is still blocked on an owner decision about the MAX_TAGS cap and on a coordinated change in trace-client-java.

trace-client-java: no change needed. This PR only touches docs, and no Java-visible behavior changed.

Test plan

  • python3 -m compileall -q trace_client tests
  • python3 -m unittest (Python 3.8.10 locally): ran 76 tests, OK
  • CI test (3.8), test (3.10), test (3.12) green

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

The README and the constructor docstring said any non-string base_url,
application, version, key or install_id raises a ValueError naming the
argument. An empty one (0, False, []) does not: it keeps its old meaning,
as test_an_empty_value_of_another_type_keeps_its_old_meaning pins down.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (performed inline in the same session; not an independent review):

  • Scope: PASS. Only README.md and one docstring in trace_client/trace_client.py are modified, and both correct the same claim.
  • Tests-new: PASS (n/a). No new public names were added.
  • Tests-fix: PASS (n/a). This is not a bug fix. The documented behavior is already pinned by test_an_empty_value_of_another_type_keeps_its_old_meaning (tests/test_trace_client.py:520), and the docs were brought in line with that test.
  • Sibling structure / renames: PASS (n/a). No new files and no renames.
  • Docs: PASS. The README paragraph and the __init__ docstring now say the same thing, and the Phase 7 table was re-swept with no other drift found.
  • Issue resolution: PASS (n/a). No Closes; the gap was found during triage.
  • CI: PASS. test (3.8), test (3.10) and test (3.12) are green on head 800e7de.
  • Stdlib-only: PASS. No import lines changed.
  • Py3.8 floor: PASS. test (3.8) is green.
  • Never-raises / never-blocks: PASS (n/a). No executable code changed.
  • Log level: PASS (n/a). No _LOG calls were added.
  • Version agreement: PASS. 0.4.2 is unchanged in all five places.
  • Exports: PASS (n/a).
  • Java parity noted: PASS. The PR body says no Java-visible behavior changed.

Judgment note: README.md:33 — "as it was before that check" relies on the reader knowing that the type check was added in 0.4.x. It was kept short on purpose. The concrete outcomes (no key, no ID, " is required") carry the meaning without it.

Do-not-auto-merge paths: none matched. pyproject.toml, the version string, the wire format, the opt-out values and the workflows are all untouched.

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


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit ce5f8a8 into main Nov 12, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the trace/doc-empty-non-string-arguments branch November 12, 2026 02:47
dmccoystephenson added a commit that referenced this pull request Nov 13, 2026
…rgument checks (#40)

The README said the constructor checks the opt-out variables "before
anything else", but it checks its arguments first: a bad one raises
ValueError even with DO_NOT_TRACK=1. Say so, and lock it in with a test.

Also put the version section's first paragraph back in order: the sentence
saying every event carries the version as a tag had drifted behind the
argument checks added in #35 and #39, leaving its "it" pointing at the
wrong thing.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant