From e18b2cc9fa43967b028566671add029ee0bab426 Mon Sep 17 00:00:00 2001
From: itamarst <>
Date: Fri, 5 Mar 2021 22:03:01 +0000
Subject: [PATCH] Document the -b flag

[Imported from Trac: page Python3, version 79]
---
 Python3.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/Python3.md b/Python3.md
index 72ef51e..1131357 100644
--- a/Python3.md
+++ b/Python3.md
@@ -178,4 +178,16 @@ The interim solution will likely be dicts that enforce key type to be only bytes
 
 ## Avoid massive changes
 
-Sometimes it's easier to be a little more lenient in input (support both unicode and bytes), or to change some type to unicode, instead of having to change hundreds of lines of code from unicode to bytes when porting. When to do so is a judgement call, but if you are changing massive amounts of code to have `b""` prefix _and_ byteness isn't important, consider alternative approaches.
\ No newline at end of file
+Sometimes it's easier to be a little more lenient in input (support both unicode and bytes), or to change some type to unicode, instead of having to change hundreds of lines of code from unicode to bytes when porting. When to do so is a judgement call, but if you are changing massive amounts of code to have `b""` prefix _and_ byteness isn't important, consider alternative approaches.
+
+## Catching string/bytes issues
+
+The following can cause bugs and aren't always caught in tests:
+
+* `str(some_bytes)` (used to return `"hello"`, now returns `"b'hello'"`)
+* `"%s" % (some_bytes,)`
+* `some_bytes == some_unicode`
+
+Python 3 has a `-b` command line flag for `python` that turns these into warnings. In the test runner you can then setup a warnings filter that turns those into exceptions for the package being ported (3rd party packages might do this too, and don't want to fail tests because of them). This helps catch bugs that wouldn't be caught otherwise. The cost is that you also need to fix all the logging messages that do this, but ... that's probably worth it.
+
+tox.ini setup for Python 3 now has this setup for Tahoe-LAFS, so if you get [BytesWarning](BytesWarning) as exception that's what's going on. For debugging purposes it can be useful to disable the exceptions and just look at the warnings; warnings don't fail the tests, so you can grep for them from tests output, sort and uniquify and then fix them in one go.
\ No newline at end of file