تمديد Python C: توقيعات الأسلوب للوثائق؟

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.

أود أن أكون أكثر تحديدا وتكون قادرة على استبدال فو (...) بواسطة فو (مهلة، أعلام = لا شيء)

هل يمكنني فعل هذا؟ كيف؟

Answer 1

نهجي المعتاد لمعرفة أشياء مثل هذا هو: "استخدم المصدر".

في الأساس، أفترض أن الوحدات القياسية لبثون ستستخدم مثل هذه الميزة عند توفرها. النظر في المصدر (على سبيل المثال هنا) يجب أن يساعد، ولكن في الواقع حتى الوحدات القياسية تضيف النموذج الأولي بعد الإخراج التلقائي. مثله:

Torsten @ Pulsar: ~ $ python2.6 >>> استيراد fcntl >> مساعدة (fcntl.flock) قطيع (...) القطيع (fd، العملية) أداء عملية القفل OP على ملف واصف FD. انظر UNIX [...

لذلك لأن المنبع لا يستخدم مثل هذه الميزة، أود أن أفترض أنها ليست موجودة. :-)

حسنا، لقد فحصت للتو مصادر PYTHON3K الحالية وهذا هو الحال. هذا التوقيع يتم إنشاؤه في pydoc.py في مصادر بيثون هنا: pydoc.py.. وبعد مقتطفات ذات صلة تبدأ في السطر 1260:

 إذا تم تفتيشه.

فحص الشيكات إذا كان الكائن يتم طلب الوثائق هو وظيفة بيثون. لكن وظائف C تنفذ تعتبر مبداثة، وبالتالي ستحصل دائما name(...) كما الإخراج.

Answer 2

لقد كان 7 سنوات ولكن يمكنك تضمين توقيع وظيفة وظائف C-Extension.

بيثون نفسه يستخدم عيادة الحجة لإنشاء التواقيع ديناميكيا. ثم بعض الميكانيكا تنشئ __text_signature__ وهذا يمكن ربطه (على سبيل المثال مع help). شرح martijnpieters هذه العملية جيدا هذه الإجابة.

قد تحصل في الواقع على عيادة الوسائط من Python وتفعلها بطريقة ديناميكية ولكني أفضل الطريقة اليدوية: إضافة التوقيع إلى DocString:

في حالتك:

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

لقد استخدمت كثيفة هذا في الحزمة الخاصة بي: iteration_utilities/src. وبعد لذلك لإظهار أنه يعمل، أستخدم إحدى وظائف تمديد C تتعرض له هذه الحزمة:

>>> 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 لهذه الوظيفة هذا الملف.

من المهم أن ندرك أن هذا غير ممكن لبثيون <3.4 وتحتاج إلى اتباع بعض القواعد:

• تحتاج إلى تضمين --\n\n بعد خط تعريف التوقيع.

• يجب أن يكون التوقيع في السطر الأول من DocString.

• يجب أن يكون التوقيع صالحا، أي foo(a, b=1, c) فشل لأنه من الممكن تحديد الحجج الموضعية بعد الوسائط ذات الافتراضي.

• يمكنك فقط توفير توقيع واحد. لذلك لا يعمل إذا كنت تستخدم شيئا مثل:

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