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

Joao S. O. Bueno jsbueno at python.org.br
Mon Apr 15 18:45:34 CEST 2013

On 15 April 2013 13:31, Eli Bendersky <eliben at gmail.com> wrote:

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).

+1

It is a problem I was met with when building extensions as well - when one would like to keep the C parts to a minimum and dynamically populate de doc-strings from another source with a Python script, for example.

Eli

Python-Dev mailing list Python-Dev at python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/jsbueno%40python.org.br

More information about the Python-Dev mailing list