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

[Eli Bendersky]

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>