I have recently completed a pretty thorough survey of library
documentation for Python 3.0 in conjunction with an update I'm making to
my book. This issue is not so much a bug as a documentation request.

For all of the library modules related to network programming, it would
be extremely useful to be much very explicit about what methods work
with strings and what methods requires byte. So many of these modules
operate on small fragments of data (e.g., send a request, add a header,
parse a query string, etc.). Sometimes using a string is okay,
sometimes it's not and sadly, it's not often predictable. Part of the
problem is that the documentation has been written for a Python 2 world
where text strings and binary data were interchangeable.

Anyways, this request minimally covers these modules:

  ftplib
  smtplib
  nntplib
  http.\*
  urllib.\*
  xmlrpc.\*
  socketserver
  asynchat
  asyncore

If there is interest, I can submit more detailed notes from my own work,
but I'm not sure how the documentation maintainer would want this.
Separate issue for each? Added as comments here? Please advise.

I'd be happy with comments on this bug. I can't promise that I'll have
the time to review everything, but the more specific the remarks are,
the easier it's for me to update the docs.

Thanks for your efforts!

David, I think that a list of notes posted here is ok, can you still
provide them?

As my opinion, Adding them as comments here is better as we can see the
same kind of issues all at once.

If David doesn't answer I'd close this issue. A year passed since the
first message and several bugs have been probably fixed already.

Hi Ezio, let us not close the issue. Waiting for David Beazley's patch
is okay or even looking at specific modules pointed out from the point
of str vs bytes interfaces and if any docs can be improved, we can
improve them. If we determine there is none, then we can close it as fixed.

An apology on the delay. Things have been rather hectic.

Regarding a patch, I don't really have a patch so much as a suggested
procedure. Basically, I'm suggesting that the maintainers of the
library documentation simply do a quick survey of network related
modules and make it clear that many of the operations work on "byte
strings" and not "strings." In Python 2.X, you could get away with
being a little sloppy, but in Python 3, the bytes/strings distinction
becomes much more prominent.

If I have time, I might be able to make a specific patch, but it
probably wouldn't be until after PyCON sometime.

I stumbled upon this issue and I feel similarly about the documentation for a particular module, ftplib. I think that the documentation is a bit too concise and assumes that the reader in an expert in the protocol when the point of the module is to abstract out such details.

For example, for the error documentation, the exceptions are only explained by the error code the server can return to trigger them. So, while the explanation of error_perm, for example, should say something about permissions, it just says "raised when an error code in the range 500–599 is received." This is particularly unclear for those with no knowledge of the internals of the protocol.

Also, in the documentation for RetrLines(), the documentation mentions the options LIST, NLST, and MLSD without explaining what they are. I know that when I first started using ftplib I had to experiment with each option to determine what they do, and I think it would be better if this was clear in the docs from the start.

I can propose a patch to the documentation if needed.

Rafe, thank you for your message and willingness to contribute. I feel what you’re reporting is another bug: the original report talks about bytes/str confusion only, not about the simplicity of the APIs. Could you open another bug with component “Documentation” and add orsenthil to the nosy list? Thanks in advance.

Thanks Eric, I think you're right. I'll do that.

I believe 3.2 has many code and doc improvements with respect to bytes/string usage. So it is hard to know what is still needed.

I think the way for anyone to advance this is to review just one of the modules listed and either report here that all is ok or open another issue just for that module and give a reference here.