पायथन सी एक्सटेंशन: दस्तावेज़ीकरण के लिए विधि हस्ताक्षर?

Question

मैं सी एक्सटेंशन लिख रहा हूं, और मैं आत्मनिरीक्षण के लिए दृश्यमान तरीकों का हस्ताक्षर बनाना चाहता हूं।

static PyObject* foo(PyObject *self, PyObject *args) { 

    /* blabla [...] */ 

} 

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

static PyMethodDef methods[] = { 
    {"foo", foo, METH_VARARGS, foo_doc}, 
    {NULL}, 
}; 

PyMODINIT_FUNC init_myexample(void) { 
    (void) Py_InitModule3("_myexample", methods, "a simple example module"); 
} 

अब

अगर मैं मॉड्यूल लोड और इसकी मदद को देखो (यह निर्माण ... के बाद):

>>> import _myexample 
>>> help(_myexample) 

मैं मिल जाएगा:

Help on module _myexample: 

NAME 
    _myexample - a simple example module 

FILE 
    /path/to/module/_myexample.so 

FUNCTIONS 
    foo(...) 
     Great example function 
     Arguments: (timeout, flags=None) 
     Doc blahblah doc doc doc. 

मैं होना चाहते हैं और भी विशिष्ट और foo (...)foo (टाइमआउट, झंडे = कोई नहीं)

को प्रतिस्थापित करने में सक्षम हो

क्या मैं यह कर सकता हूं? कैसे?

Answer 1

इस तरह की चीजों के बारे में जानने के लिए मेरा सामान्य दृष्टिकोण यह है: "स्रोत का उपयोग करें"।

असल में, मुझे लगता है कि पाइथन के मानक मॉड्यूल उपलब्ध होने पर ऐसी सुविधा का उपयोग करेंगे। स्रोत (for example here) को देखकर मदद करनी चाहिए, लेकिन वास्तव में मानक मॉड्यूल स्वचालित आउटपुट के बाद प्रोटोटाइप जोड़ते हैं। इस तरह:

torsten@pulsar:~$ python2.6 
>>> import fcntl 
>>> help(fcntl.flock) 
flock(...) 
    flock(fd, operation) 

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

तो नदी के ऊपर इस तरह के एक सुविधा का उपयोग नहीं कर रहा है के रूप में, मैं यह मान लेगा यह वहाँ नहीं है। :-)

ठीक है, मैंने अभी वर्तमान पायथन 3k स्रोतों की जांच की है और यह अभी भी मामला है। यह हस्ताक्षर यहां पाइथन स्रोतों में pydoc.py में उत्पन्न होता है: pydoc.py। लाइन 1260 में प्रासंगिक अंश शुरू:

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

inspect.isfunction जांच करता है कि वस्तु प्रलेखन के लिए अनुरोध किया गया है एक अजगर कार्य है। लेकिन सी लागू कार्यों को बिल्टिन माना जाता है, इसलिए आपको आउटपुट के रूप में हमेशा name(...) मिल जाएगा।

Answer 2

यह 7 साल रहा है लेकिन आप सी-एक्सटेंशन फ़ंक्शन और कक्षा के लिए हस्ताक्षर शामिल कर सकते हैं।

पायथन स्वयं गतिशील रूप से हस्ताक्षर उत्पन्न करने के लिए Argument Clinic का उपयोग करता है। फिर कुछ यांत्रिकी __text_signature__ बनाते हैं और यह आत्मनिरीक्षण किया जा सकता है (उदाहरण के लिए help के साथ)। @MartijnPieters ने this answer में इस प्रक्रिया को काफी अच्छी तरह से समझाया।

आप वास्तव में अजगर से तर्क क्लिनिक मिल सकता है और एक गतिशील फैशन में यह कर, लेकिन मैं मैनुअल तरीका पसंद करते हैं:

आपके मामले में:

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

मैं docstring को हस्ताक्षर जोड़ना मेरे पैकेज में इसका भारी उपयोग किया: iteration_utilities/src। तो प्रदर्शित करने के लिए यह काम करता है कि मैं सी-विस्तार इस पैकेज द्वारा उजागर कार्यों में से एक का उपयोग करें:

>>> 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. 
[...] 

इस कार्य के लिए docstring this file परिभाषित किया गया है।

यह एहसास है कि इस अजगर < 3.4 के लिए संभव नहीं है महत्वपूर्ण है और आप कुछ नियमों का पालन करने की जरूरत है:

• आप --\n\n हस्ताक्षर परिभाषा पंक्ति के बाद शामिल करना होगा।

• हस्ताक्षर डॉकस्ट्रिंग की पहली पंक्ति में होना चाहिए।

• हस्ताक्षर मान्य होना चाहिए, यानी foo(a, b=1, c) विफल रहता है क्योंकि डिफ़ॉल्ट रूप से तर्क के बाद स्थितित्मक तर्क परिभाषित करना संभव नहीं है।

• आप केवल एक हस्ताक्षर प्रदान कर सकते हैं। तो यह है अगर आप की तरह कुछ का उपयोग काम नहीं करता:

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