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

[R. David Murray]

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