[Python-Dev] Sharing docstrings between the Python and C implementations of a module (original) (raw)

Eli Bendersky eliben at gmail.com
Mon Apr 15 18:31:40 CEST 2013

On Mon, Apr 15, 2013 at 3:45 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:

On Mon, Apr 15, 2013 at 8:17 PM, Maciej Fijalkowski <fijall at gmail.com> wrote: > On Mon, Apr 15, 2013 at 9:56 AM, David Lam <david.k.lam1 at gmail.com> wrote: >> 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.

It's actually even worse than that - if a subclass overrides a method, it has to completely duplicate the docstring, even if the original docstring was still valid. So, for example, ABCs can't provide docstrings for abstract methods. So yeah, we end up not only duplicating between the C and Python versions, but sometimes we end up duplicating between different subclasses as well (datetime.datetime, datetime.date and datetime.time are the worst offenders here). I like the idea of at least adding a test that checks the Python docstring and the C docstring are the same in the duplicated cases - that should be a lot easier than adjusting the build process to let the C version use the Python docstrings or vice-versa (even the argument clinic DSL in PEP 434 doesn't try to achieve that - it just tries to cut down on the duplication within the C code itself).

Would it make sense to think about adding this in the scope of the argument clinic work, or is it too unrelated? This seems like a commonly needed thing for large parts of the stdlib (where the C accelerator overrides Python code).

Eli -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20130415/4ce45314/attachment.html>

More information about the Python-Dev mailing list