Skip to content

Make a falsy non-string environment value opt out - #47

Merged
dmccoystephenson merged 1 commit into
mainfrom
trace/env-nonstring-fails-closed
Nov 20, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
trace/env-nonstring-fails-closed

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • environment_opts_out() read each variable as (env.get(name) or ""), so a falsy non-string value in an explicit mapping (0, False, []) was treated as unset and left reporting on. The string "0" already opted out. The docstring has always said that "a value that is not a string -- opts out too".
  • A new _variable() helper treats only a missing (None) value as unset. Any other non-string value raises, which the existing except turns into an opt-out. String handling is byte-for-byte unchanged.
  • The environment_opts_out docstring now says explicitly that this covers 0 and False.

os.environ only ever holds strings, so the constructor's own check behaves exactly as before. Only a program that passes its own mapping (for example, settings parsed from YAML or TOML) is affected, and for that program the switch now fails closed.

Closes #46

Test plan

  • New test test_a_value_that_is_not_a_string_opts_out_even_when_it_is_empty covers 0, False, [], 0.0, b"", 1 and True for both variables, and checks that None still counts as unset.
  • Stash-and-run: the new test FAILS with the fix stashed and PASSES with it restored.
  • python3 -m unittest passes locally on Python 3.8.10: 86 tests, OK.
  • CI matrix (3.8 / 3.10 / 3.12) is green.

trace-client-java

No change is needed in Java. Its environment map is Map<String, String>, so a non-string value cannot reach it. The accepted values, the disabled_reason strings and the wire format are unchanged, and the version is not bumped.

Deferred

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

environment_opts_out() read each variable as `(env.get(name) or "")`, so
a 0, False or [] in an explicit mapping counted as unset and left
reporting on, while the string "0" opted out. Only a missing (None) value
now counts as unset; any other non-string opts out, as the docstring
already promised.

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

Copy link
Copy Markdown
Member Author

Self-review rubric (the review was performed inline during a Gardener session, https://github.com/Stephenson-Software/gardener):

  • Scope: PASS. Only trace_client/trace_client.py (fix and docstring) and tests/test_trace_client.py (one new test) are modified, with 25 insertions and 4 deletions.
  • Tests-new: PASS. No new public name was added. The private _variable is exercised through environment_opts_out by the new test and by every existing environment test.
  • Tests-fix: PASS. Stash-and-run was confirmed: test_a_value_that_is_not_a_string_opts_out_even_when_it_is_empty FAILS with the fix stashed and PASSES with it restored (local Python 3.8.10).
  • Sibling structure / renames: PASS. No new files and no renames.
  • Docs: PASS. The environment_opts_out docstring now names 0/False. The README's "Turning it off" section describes os.environ, which only holds strings, so it remains accurate.
  • Issue resolution: PASS. The (env.get(name) or "") reads named in environment_opts_out() fails open for a falsy non-string value (0, False) in an explicit mapping #46 are both replaced.
  • CI: PASS. test (3.8), test (3.10) and test (3.12) are green on the PR head.
  • Stdlib-only: PASS. No imports were added and pyproject.toml is untouched.
  • Py3.8 floor: PASS. test (3.8) is green.
  • Never-raises / never-blocks: PASS. The TypeError raised by _variable is only reachable inside the existing try/except Exception in environment_opts_out, and report() is untouched.
  • Log level: PASS. No _LOG calls were added.
  • Version agreement: PASS. The version is unchanged at 0.5.0 everywhere, and no release bump is included.
  • Exports: PASS. _variable is private and is not added to __all__.
  • Java parity noted: PASS. The PR body states that no Java change is needed (Map<String, String>).

Observation for the owner: trace_client/trace_client.py — _variable now treats DO_NOT_TRACK=0 given as an int in an explicit mapping as an opt-out, whereas the string "0" means "track". This is the fail-closed reading the docstring already promised for non-strings and matches the 0.5.0 direction. It is flagged here because it is the one input whose result flips from "on" to "off".


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit dee6086 into main Nov 20, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the trace/env-nonstring-fails-closed branch November 20, 2026 06:45
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.

environment_opts_out() fails open for a falsy non-string value (0, False) in an explicit mapping

1 participant