Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `"<argument> 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 —
Expand Down Expand Up @@ -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).

Expand Down
8 changes: 8 additions & 0 deletions tests/test_trace_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading