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

Nick Coghlan ncoghlan at gmail.com
Mon Apr 15 12:45:23 CEST 2013

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

Cheers, Nick.

-- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia

More information about the Python-Dev mailing list