Документирование с помощью методов Python Sphinx, которые имеют параметры по умолчанию с объектами дозорного?

Question

Если вы хотите, чтобы люди могли вызывать некоторые методы, используя None, вы должны использовать объект sentinel при определении метода.

 _sentinel = object()
 def foo(param1=_sentinel):
     ...

Это позволит вам позвонить foo(param1=None) и иметь возможность различать вызовы, подобные foo().

Проблема заключается в том, что когда Sphinx документирует метод, оннапишет что-то вроде

mymodule.foo(param1=<object object at 0x108c1a520>)

Как я могу убедить Sphinx иметь удобный для пользователя вывод этих функций?

Примечание. Представьте себе, как выглядят документы, если у вас есть 3-4 параметра, использующихдозорный подход.

Answer 1

Это можно сделать, указав сигнатуру функции в директиве autodoc вручную, например:

.. automodule:: pymorphy.contrib.tokenizers

    .. autofunction:: extract_tokens(foo, bar)

    .. autofunction:: extract_words

Answer 2

Я не думаю, что можно убедить Сфинкса быть более "дружелюбным", если у вас есть страж, который создает объект вне функции. Расширение Sphinx 'autodoc импортирует модуль , что означает выполнение кода уровня модуля.

Вы уверены, что не можете использовать что-то подобное?

def foo(param1=None):
    if param1 == None:
        param1 = whatever you want...
    else:
         ... 

Answer 3

Часть <object object at 0x108c1a520> созданной сигнатуры метода может быть изменена путем переопределения метода __repr__ объекта-стража.

_sentinel = type('_sentinel', (object,),
                 {'__repr__': lambda self: '_sentinel'})()

Сфинкс будет отображаться как-то так:

mymodule.foo(param1=_sentinel)