The documentation occasionally contains a link to the source code for a module in the stdlib. See for instance http://docs.python.org/library/urlparse.html and http://docs.python.org/library/collections.html , or many others.

With a quick perusal, I couldn't immediately guess as to which ones managed to have one and which ones don't, but it'd be convenient to have a link in as many places as possible, which is certainly more than we have now. (See e.g. http://docs.python.org/library/json.html and http://docs.python.org/library/itertools.html and many others for examples of pages that lack a link).

Perhaps putting it in a more conspicuous but still consistent location would be reasonable (the sidebar?).

Hi Julian, thanks for your interest in improving Python and welcome!  It is Raymond who initially added these links, and I helped porting them between versions.  The criterion can be read in the commit message: “Provide links to Python source in a handful of cases where the source is a generally helpful adjunct to the docs” (from http://hg.python.org/cpython/rev/fdd3681b1439/).  Not all modules have source code that is easy or helpful to read; not all modules have Python source code (itertools doesn’t).  I think Raymond is not willing to add links for all modules, but if you have a list of specific names which would benefit from source links, I’m sure he will consider them.

Here's first a quick list from one pass over the docs. I've attempted to limit myself to a few like you've suggested, though I'll wait for confirmation that Raymond is not willing to simply add them to everything once we're at it :).

http://docs.python.org/library/difflib.html
http://docs.python.org/library/stringio.html
http://docs.python.org/library/codecs.html
http://docs.python.org/library/stringprep.html
http://docs.python.org/library/datetime.html
http://docs.python.org/library/math.html
http://docs.python.org/library/cmath.html
http://docs.python.org/library/decimal.html
http://docs.python.org/library/itertools.html
http://docs.python.org/library/os.path.html
http://docs.python.org/library/csv.html
http://docs.python.org/library/configparser.html
http://docs.python.org/library/logging.html
http://docs.python.org/library/getpass.html
http://docs.python.org/library/json.html
http://docs.python.org/library/urllib2.html
http://docs.python.org/library/unittest.html
http://docs.python.org/library/code.html

When I hit the docs to diagnose a problem, it's usually to take a quick look, and then to hit the source code to read that too, since most of the stuff that's in general use is common enough for me to know how it works in a general sense, so the source code is typically where I go pretty quickly after reading what the docs have to say.

It's not a huge deal obviously, hg.python.com is not the furthest thing away. Just seems convenient, especially since like I said a lot of the other ones I peek at already have links.


As for non-python modules, I really would like to say that linking to C source sounds just as reasonable to me, a little C never killed anyone :), but I don't want to push my luck, so I'll stick with whatever I can get here I guess (I know I put some non-python modules on the list).

There are usually two cases that lead me to check the code:
1) The documentation is incomplete, not clear, missing, or plain wrong;
2) I want to check how something is implemented, mostly just out of curiosity;

Regarding the first case, in theory the docs should be informative and correct enough to not require you to go and check the code.  If they aren't you can report issues and we can improve it.
The second case applies to pretty much any module.  Linking to the code might also expose some internal details that should be just ignored by the user.  The code in some modules is also pretty old and might be a "bad" example (because it doesn't use modern conventions).
Some of the modules you listed are actually packages, so that would require to link to several files.

Well, if there's opposition I don't know how strongly I feel about this then, but I generally agree with you Ezio, if there's an occasion where 1) applies fixing the docs is certainly reasonable. If I'm checking the source though, it's not necessarily since the documentation is unclear, just that it's often easier to read code than English.

But, I guess if no one else feels it'd be helpful feel free to close this then.

Here's a patch for some of Julian's suggested modules.  I went through Julian's list and included code links for the ones that a) weren't packages or only written in C, b) only had one Python file (which excluded os.path = posixpath.py/ntpath.py) and c) had docstrings or comments that seemed useful.

datetime and difflib in particular have very good comments (and they're both by Tim Peters).  Possibly controversial: for CSV the patch links to both csv.py and _csv.c; for decimal it links to decimal.py and _decimal.c.  We could exclude these two.

+1 on amk’s patch.  I trust his selection of modules, and linking to C module sources can be an interesting experiment.

Without actually looking, I am skeptical of _decimal.c as I expect the code to be highly technical. But maybe it has more helpful comments than I expect. But I am willing to let the person pushing decide. I am overall in favor of linking to python sources.

difflib I know should be linked. tokenize.py (not in the patch) probably should be linked eventually, but only after the docstrings (and doc) are fixed a bit. I will think about it after that is done.

Terry: yes, the code for _decimal.c doesn't look especially helpful.  (_csv.c is a bit more straightforward, but still isn't highly commented.) The problem is that decimal.py does have long docstrings & discussions, so it's certainly useful.  Is it inconsistent to not link to all the relevant files?  Or is it better to only link to source files that we consider helpful?

With rare exceptions*, my inclination is to only link .py files anyway. Those apply to all implementations that use them as is. Any Python programmer can read them and maybe learn something. The C files only apply to CPython. The possible existence of a _modname accelerator is evident in the Python file. So I suggest applying without the .c links.

*Non-module examples: yesterday on python-list, someone referenced comments in dictobject.c to explain seemingly peculiar behavior. I believe listobject.c has Tim's long comment on .sort.

Agreed with Terry.  Some Python modules are just wrappers for C modules, but datetime.py is standalone so we can dispense with the link to _datetime.c.

New changeset bc107f5faedc by Andrew Kuchling in branch 'default':
#13437: link to the source code for a few more modules
http://hg.python.org/cpython/rev/bc107f5faedc