Skip to content

Say the environment wins over the setting and the key, not over the argument checks - #40

Merged
dmccoystephenson merged 1 commit into
mainfrom
trace/readme-version-and-optout-order
Nov 13, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
trace/readme-version-and-optout-order

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

A documentation accuracy sweep (no open issue was implementable this cycle) found two drifts in README.md:

  • "Turning it off" said the opt-out variables are checked "before anything else". In TraceClient.__init__ the argument checks (non-string values, blank required arguments, overlong version or install_id) run before environment_opts_out(), so DO_NOT_TRACK=1 does not stop TraceClient(url, "app", 1.4, key="k") from raising ValueError. The sentence now says the environment is checked before enabled and the key, and that the arguments are checked before either. A test, test_arguments_are_checked_before_the_environment_opt_out, locks that order in. The existing non-string test only covered enabled=False.
  • "Every event carries the program's version" had lost its order. The sentence about argument validation added in Name the argument when the constructor is given a non-string #35 and Say that an empty value of another type still means no value #39 was inserted between "the version is required" and "carries it as the tag version". As a result, "it" read as referring to the empty value, and the line wrapping was ragged. The paragraph is split in two: the tagging behaviour comes first, then the validation rules. No wording about behaviour changed.

No production code changed. No Java-visible behaviour changed, so trace-client-java needs no matching change.

Skipped issues

Test plan

  • python3 -m unittest: 77 tests run, OK (local, Python 3.8)
  • New test passes against the current constructor
  • CI test (3.8), test (3.10), test (3.12) green

No tracking issue. The gap was found during a documentation sweep.

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

…rgument checks

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>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (posted as a plain comment rather than a formal review):

  • Scope: PASS. Only README.md (the two drifted passages) and tests/test_trace_client.py (one test for the newly documented order) are touched. Net diff: 2 files, +21/-11.
  • Tests-new: PASS (not applicable). No new public name was added. The one new test covers the README's new claim.
  • Tests-fix: PASS (not applicable). No production code changed. The new test is characterization of TraceClient.__init__ lines 167–178 running before environment_opts_out() at line 193.
  • Sibling structure / renames: PASS. No new files and no renamed identifiers.
  • Docs: PASS. "Turning it off" now matches the constructor's order. The class docstring ("checks ... before it looks at enabled") was already accurate and is unchanged. The version section's two paragraphs keep every behavioural statement they had before, only reordered.
  • Issue resolution: PASS (not applicable). No Closes. The version tag is added even when it pushes an event past MAX_TAGS #16 is deferred with its reason stated in the PR body.
  • CI: PASS. test (3.8), test (3.10) and test (3.12) are green on the PR head (run 43355264860).
  • Stdlib-only: PASS. No new imports.
  • Py3.8 floor: PASS. test (3.8) is green.
  • Never-raises / never-blocks: PASS (not applicable). report, close and _send are untouched.
  • Log level: PASS (not applicable). No _LOG calls were added.
  • Version agreement: PASS. No version string was touched.
  • Exports: PASS (not applicable). No new public names.
  • Java parity noted: PASS. The PR body states that no Java-visible behaviour changed.

Judgment call flagged: README.md:127. The parenthetical repeats a fact the version section already states ("whether or not the client ends up enabled"). It is kept because "Turning it off" is where a reader checks precedence, and "before anything else" was the inaccurate phrase there.

No do-not-auto-merge paths are touched (no workflow, pyproject.toml, version string, wire format, opt-out values or LICENSE changes).

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 7e4d185 into main Nov 13, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the trace/readme-version-and-optout-order branch November 13, 2026 02:55
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