Documentation

For example:

_imagedata is a string containing the raw image data. (image.py)

or

_audiodata is a string containing the raw audio data. (audio.py)

So the programmer thinks, "how can it be a 'string' and 'raw' at the same time?" Then the programmer notices the parameter for encoding and the language saying "the default encoding is Base64" and thinks, "ah, ok, that's how it could be a string!" (though it's still a little bit squirrelly to use the word "raw" to describe encoded data).

But then the reader sees the future tense in "... which will perform the actual encoding..." and thinks, "no, the argument must really be for binary data."

And then the programmer notices the parallel language in text.py:

_text is the string for this message object.

and starts to wonder: "huh, maybe all of these are expecting bytes." But then the programmer's code blows up when it tries to go with that theory (still no help from the documentation).

So in desperation, the programmer starts to dig into the actual code to find out what's done for each of these subclasses. And that journey leads to the conclusion that "string" in this package means one thing for some of the classes and something different for others.

Can't we just say "bytes" when we mean bytes, and reserve the use of the word "string" to mean what it's supposed to mean in the only versions of Python which are actually officially supported? 😆

Linked PRs

• gh-101021: Document binary parameters as bytes #101024
• [3.11] gh-101021: Document binary parameters as bytes (GH-101024) #101043
• [3.10] gh-101021: Document binary parameters as bytes (GH-101024). #101052