[Python-Dev] Docs of weak stdlib modules should encourage exploration of 3rd-party alternatives

[Andrey Petrov]

Hi Pythonistas,

I've had the pleasure of speaking with Guido at PyCon and it became evident
that some of Python's included batteries are significantly lagging behind
the rapidly-evolving defacto standards of the community—specifically in
cases like urllib and urllib2, which lack important features provided by
alternatives like httplib2, requests, and my own urllib3.


Part 1:
I propose we add a snippet to the top of the documentation of specific
archaic standard modules which encourages users to investigate third-party
alternatives if they find the standard module frustrating or otherwise
lacking. These notes would target new users, including those coming from
other languages where the third-party library choices are not nearly as
amazing as they are in Python.

(For what it's worth, Guido has verbally agreed to a proposal of this
nature.)

What such a snippet might look like:

"Batteries are included with Python but sometimes they are old and
leaky—this is one of those cases. Please have a look in PyPI for more
modern alternatives provided by the Python community."

Additionally, I would like for us as a community to identify which other
standard libraries (cgi? ssl? others?) are candidates for this kind of
messaging in the official Python documentation.


Part 2:
I propose we add a new category of package identifiers such as "Topic ::
Standard Library Alternative :: {stdlib_package_name}" which authors of
libraries can tag themselves under. The documentation warning snippet will
provide a link to the appropriate PyPI query to list packages claiming to
be alternatives to the stdlib package in question.


Objections? Concerns? Improvements? What is the next step to making this
happen?

Pythonically yours,
- Andrey (on behalf of Ori Livneh, Kenneth Reitz, Brandon Rhodes, David
Wolever, and everyone else who contributed to this letter during our PyCon
sprint.)



P.S. Appendix: Here are some additional snippet alternatives that were
proposed:

> Batteries are included with Python but sometimes they are old and
leaky—this is one of those cases. Please have a look in PyPI for more
modern alternatives provided by the Python community.

> While this module has served Python programmers faithfully for many
years, there are now many powerful alternatives available as third-party
modules. To learn more about them, view the Python Package Index results
for the category "Topic :: Standard Library Alternative :: asyncore." —
[With the topic name as a hyperlink]

> This module has been identified by the community as crusty, a signal that
better alternatives exist outside the standard library. Because the Python
standard library is constained to maintain backward-compatibility, it does
not always reflect what is current or common in the Python community. If
you are not constrained to support legacy code, you may wish to browse the
Python Package Index for alternatives to this module.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20120312/bf0152c5/attachment.html>