Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- assignee: docs@python -> rhettinger nosy: +eric.araujo, rhettinger versions: +Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

Julian Berman <Julian+Python.org@GrayVines.com> added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

Changes by Terry J. Reedy <tjreedy@udel.edu>: ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

A.M. Kuchling added the comment: 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. ---------- nosy: +akuchling Added file: http://bugs.python.org/file34499/13437-patch.txt _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

Terry J. Reedy added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

Terry J. Reedy added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________