[Python-Dev] Byte/text documentation improvements (was: PEP 460 reboot) (original) (raw)

R. David Murray rdmurray at bitdance.com
Tue Jan 14 21:03:36 CET 2014

On Tue, 14 Jan 2014 11:43:16 -0800, "Jim J. Jewett" <jimjjewett at gmail.com> wrote:

Greg Ewing replied:

>> ... ASCII compatible binary data is a >> subset of arbitrary binary data. I wrote: > But in terms of explaining the text model, that > separation is important enough that > (2) It may be worth creating a virtual > split in the documentation. (rough sketch below) Ethan likes the idea, but points out that the term "Virtual" is confusing here. Alas, I'm not sure what the correct term is. In addition to "Go for it!" / "Don't waste your time", I'm looking for advice on: (A) What word should I use instead of "Virtual"? Imaginary? Pretend?

Notional.

(B) Would it be good/bad/at least make the docs easier to create an actual class (or alias)?

I don't have an opinion on this, but if you make it real class then "notional" would no longer work. I guess you'd just call it an alias in that case.

(C) Same question for a pair of classes provided only in the documentation, like example code.

Bad. Refer to it via a glossary item ref or a section ref.

(D) What about an abstract class, or several?

e.g., replacing the XXX TODO of collections.abc.ByteString with separate abstract classes for ByteSequence, String, ByteString, and ASCIIByteString? (ByteString already includes any bytes or bytearray instance, so backward compatibility means the String suffix isn't sufficient for an opt-in-by-instances class.)

What's the difference between ByteString and ByteSequence? Or maybe I'm asking the difference between ByteString and ASCIIByteString?

So the only concrete classes would be ASCIIByteStrings....that might work. It would give us something to call that argument type in, eg, the binascii docs. Not to mention a formal definition of what methods a Python byte type needs to support.

--David

More information about the Python-Dev mailing list