[Python-Dev] Sharing docstrings between the Python and C implementations of a module

David Lam david.k.lam1 at gmail.com
Mon Apr 15 09:56:07 CEST 2013

Recently I helped out on issue16954 which involved filling in docstrings
for methods and classes in ElementTree.py

While doing so, I tried to test my work in the interpreter like this...

    >>> from xml.etree.ElementTree import Element
    >>> help(Element)

...but found that help() showed nothing but empty strings!

After some debugging, I found that the culprit was the
 `from _elementtree import *` near the bottom of the module.

Not wanting to copy & paste docstrings around,  I thought one solution
might be to just reassign Element.__doc__ with the right docstring.
But, it seems that you can't do that for C extensions:

    >>> from _elementtree import Element as cElement
    >>> cElement.__doc__ = 'correct docstring'
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: can't set attributes of built-in/extension type


Q.  Is there way to maintain the same docstring without
    resorting to copying and pasting it in two places?

I tried to find an example in the source which addressed this, but
found that the docstrings in similar cases to be largely duplicated.
For instance, _datetimemodule.c, decimal_.c and _json.c all seem to
exhibit this docstring copy and pastage.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130415/67f2843e/attachment.html>

More information about the Python-Dev mailing list