[Python-Dev] Sharing docstrings between the Python and C implementations of a module
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.
> 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).
Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
More information about the Python-Dev