[Python-Dev] Sharing docstrings between the Python and C implementations of a module
Maciej Fijalkowski
fijall at gmail.com
Mon Apr 15 12:17:39 CEST 2013
On Mon, Apr 15, 2013 at 9:56 AM, David Lam <david.k.lam1 at gmail.com> wrote:
> 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
> 'xml.etree.ElementTree.Element'
>
> ---
>
> 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.
>
Hi
NumPy uses a hack to deal with this problem. It has a small C function
that would mutate the docstring under your feet. Personally I would
prefer some sort of tagging in C source that can copy-paste stuff
instead, honestly. It does sound like a good idea to share docstrings.
Seems also relatively trivial to write a test that checks that they
stay the same.
Cheers,
fijal
More information about the Python-Dev
mailing list