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

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


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