Python >> Python Program >  >> Python

Python C-tillägg:metodsignaturer för dokumentation?

Det har gått 7 år men du kan inkludera signaturen för C-extension funktion och klasser .

Python själv använder Argument Clinic för att dynamiskt generera signaturer. Sedan skapar en del mekaniker en __text_signature__ och detta kan introspekteras (till exempel med help ). @MartijnPieters förklarade denna process ganska bra i det här svaret.

Du kanske faktiskt får argumentkliniken från python och gör det på ett dynamiskt sätt men jag föredrar det manuella sättet:Lägga till signaturen i docstringen:

I ditt fall:

PyDoc_STRVAR(
    foo_doc,
    "foo(timeout, flags=None, /)\n"
    "--\n"
    "\n"
    "Great example function\n"
    "Arguments: (timeout, flags=None)\n"
    "Doc blahblah doc doc doc.");

Jag använde mig mycket av detta i mitt paket:iteration_utilities/src . Så för att visa att det fungerar använder jag en av C-extensionsfunktionerna som exponeras av detta paket:

>>> from iteration_utilities import minmax
>>> help(minmax)
Help on built-in function minmax in module iteration_utilities._cfuncs:

minmax(iterable, /, key, default)
    Computes the minimum and maximum values in one-pass using only
    ``1.5*len(iterable)`` comparisons. Recipe based on the snippet
    of Raymond Hettinger ([0]_) but significantly modified.

    Parameters
    ----------
    iterable : iterable
        The `iterable` for which to calculate the minimum and maximum.
[...]

Dokstringen för den här funktionen är definierad som denna fil.

Det är viktigt att inse att detta inte är möjligt för python <3.4 och du måste följa några regler:

  • Du måste inkludera --\n\n efter signaturdefinitionsraden.

  • Signaturen måste finnas på den första raden i dokumentsträngen.

  • Signaturen måste vara giltig, dvs foo(a, b=1, c) misslyckas eftersom det inte är möjligt att definiera positionsargument efter argument med standard.

  • Du kan bara tillhandahålla en signatur. Så det fungerar inte om du använder något som:

    foo(a)
    foo(x, a, b)
    --
    
    Narrative documentation
    

Mitt vanliga sätt att ta reda på saker som detta är:"använd källan".

I grund och botten skulle jag anta att standardmodulerna för python skulle använda en sådan funktion när den är tillgänglig. Att titta på källan (till exempel här) borde hjälpa, men faktiskt till och med standardmodulerna lägger till prototypen efter den automatiska utmatningen. Så här:

[email protected]:~$ python2.6
>>> import fcntl
>>> help(fcntl.flock)
flock(...)
    flock(fd, operation)

    Perform the lock operation op on file descriptor fd.  See the Unix [...]

Så eftersom upstream inte använder en sådan funktion, skulle jag anta att den inte finns där. :-)

Okej, jag kollade precis aktuella python3k-källor och så är det fortfarande. Den signaturen genereras i pydoc.py i pythonkällorna här:pydoc.py. Relevant utdrag som börjar på rad 1260:

        if inspect.isfunction(object):
            args, varargs, varkw, defaults = inspect.getargspec(object)
            ...
        else:
            argspec = '(...)'

inspect.isfunction kontrollerar om objektet som dokumentationen efterfrågas för är en Python-funktion. Men C-implementerade funktioner anses vara inbyggda, därför får du alltid name(...) som utgång.