From 6fc03ce03cd5eebd9098bb22afa4186141359e8a Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Thu, 12 Nov 2026 19:53:18 -0700 Subject: [PATCH] Say the environment wins over the setting and the key, not over the argument 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 --- README.md | 24 +++++++++++++----------- tests/test_trace_client.py | 8 ++++++++ 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f27bcfc..900e1bb 100644 --- a/README.md +++ b/README.md @@ -25,19 +25,20 @@ trace.close() ## Every event carries the program's version The third argument to `TraceClient` is the program's own version, and it is -required: a missing or blank one, one over 255 characters after trimming, or -one that is not a string, raises `ValueError`. So does a value that is not a +required. Every event the client sends — `startup`, `command`, anything +else — carries it as the tag `version`, so every event can be tied to a +release, not just `startup`. An event that passes its own `version` tag +keeps it, and the dict passed as `tags` is never modified. There is no need +to tag `startup` by hand any more. + +A missing or blank version, one over 255 characters after trimming, or one +that is not a string, raises `ValueError`. So does a value that is not a string for `base_url`, `application`, `key` or `install_id=`, naming the argument, whether or not the client ends up enabled, so a settings file that turns `version: 1.4` into a number is caught at startup. An empty value of another type (`0`, `False`, `[]`) is taken as no value, as it was before that check: no key, no installation ID, or `" is required"` for the -three positional arguments. Every event the -client sends — `startup`, `command`, -anything else — carries it as the tag `version`, so every event can be tied -to a release, not just `startup`. An event that passes its own `version` tag -keeps it, and the dict passed as `tags` is never modified. There is no need -to tag `startup` by hand any more. +three positional arguments. Before 0.3.0, the constructor took two positional arguments and only events tagged by hand carried a version. Upgrading is one argument — @@ -122,9 +123,10 @@ and costs nothing; the first that applies is the reason: `TRACE_USAGE_REPORTING=off` (also `false`, `0`, `no`; case-insensitive) or `DO_NOT_TRACK=1` (also `true`, `yes`; the [consoledonottrack.com](https://consoledonottrack.com) convention). The - constructor checks these before anything else, so they win over the - program's own setting. Any other value, or an unset variable, leaves that - setting in charge. + constructor checks these before `enabled` and the key, so they win over the + program's own setting. (It checks its arguments before either, so a bad + argument still raises `ValueError` with reporting switched off.) Any other + value, or an unset variable, leaves that setting in charge. - **The program's own setting:** `enabled=False`. - **No key** (or a blank one). diff --git a/tests/test_trace_client.py b/tests/test_trace_client.py index 1365144..2a35693 100644 --- a/tests/test_trace_client.py +++ b/tests/test_trace_client.py @@ -512,6 +512,14 @@ def test_a_value_that_is_not_a_string_is_rejected_by_the_argument_it_was_given_f self.assertEqual("%s must be a string, not %s" % (argument, type_name), str(raised.exception), "the only raising path should say which argument was wrong") + def test_arguments_are_checked_before_the_environment_opt_out(self): + with mock.patch.dict(os.environ, {"DO_NOT_TRACK": "1"}): + with self.assertRaises(ValueError, msg="a bad argument should not hide behind the opt-out") as raised: + TraceClient(self.base_url, "MyGame", 1.4, key="k") + self.assertEqual("version must be a string, not float", str(raised.exception)) + with self.assertRaises(ValueError, msg="a missing argument should not hide behind the opt-out"): + TraceClient(self.base_url, "", "1.2.3", key="k") + def test_a_rejected_key_is_not_repeated_in_the_error(self): with self.assertRaises(ValueError) as raised: TraceClient(self.base_url, "MyGame", "1.2.3", key=123456789)