Python C 확장 : 문서를위한 메소드 서명?

StackOverflow https://stackoverflow.com/questions/1104823

문제

나는 C 확장을 작성하고 있으며 내 방법의 서명을 내성을 위해 볼 수있게하고 싶습니다.

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 (타임 아웃, 플래그 = 없음)

이걸 할 수 있나요? 어떻게?

도움이 되었습니까?

해결책

이와 같은 것에 대해 알아내는 일반적인 접근 방식은 "소스 사용"입니다.

기본적으로 Python의 표준 모듈은 가능한 경우 그러한 기능을 사용한다고 가정합니다. 소스를보고 (예를 들어 여기)는 도움이되지만 실제로 표준 모듈조차 자동 출력 후 프로토 타입을 추가합니다. 이와 같이:

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

업스트림이 그러한 기능을 사용하지 않기 때문에 그것이 존재하지 않는다고 가정합니다. :-)

좋아, 방금 현재 Python3k 소스를 확인했는데 이것이 여전히 그렇습니다. 그 서명은 생성됩니다 pydoc.py 여기에 파이썬 소스에서 : pydoc.py. 1260 행에서 시작하는 관련 발췌 :

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

Destpect.Iftunction check 컨트리가 요청 된 객체가 Python 함수인지 확인하십시오. 그러나 C 구현 기능은 내장 된 것으로 간주되므로 항상 얻을 수 있습니다. name(...) 출력으로.

다른 팁

7 년이 지났습니다 그러나 C- 확장 기능 및 클래스의 서명을 포함시킬 수 있습니다..

파이썬 자체는 다음을 사용합니다 논쟁 클리닉 서명을 동적으로 생성합니다. 그런 다음 일부 역학은 a를 만듭니다 __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.
[...]

이 함수의 문서화는 정의됩니다 이 파일.

이것을 깨닫는 것이 중요합니다 Python <3.4에는 불가능합니다 그리고 몇 가지 규칙을 따라야합니다.

  • 포함해야합니다 --\n\n 서명 정의 라인 후.

  • 서명은 docstring의 첫 번째 줄에 있어야합니다.

  • 서명은 유효해야합니다 foo(a, b=1, c) 기본값으로 인수 후 위치 인수를 정의 할 수 없기 때문에 실패합니다.

  • 하나의 서명 만 제공 할 수 있습니다. 따라서 다음과 같은 것을 사용하는 경우 작동하지 않습니다.

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

Narrative documentation
라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top