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

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

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

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

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

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

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

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


python python-sphinx default-parameters
person sorin    schedule 08.08.2011    source источник

Ответы (3)


arrow_upward
1
arrow_downward

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

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

def foo(param1=None):
    if param1 == None:
        param1 = whatever you want...
    else:
         ...
person mzjn    schedule 08.08.2011
comment
sentinel - это одноразовый объект вне функции, поэтому эта функция может обрабатывать значения None в общем случае, поэтому я считаю, что sorin действительно не может использовать то, что вы предлагаете. - person Mikhail Korobov; 09.08.2011

arrow_upward
1
arrow_downward

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

.. automodule:: pymorphy.contrib.tokenizers

    .. autofunction:: extract_tokens(foo, bar)

    .. autofunction:: extract_words
person Mikhail Korobov    schedule 08.08.2011
comment
Да, это работает: +1. Почему я не подумал об этом? :-) stackoverflow.com/questions/5365684 - person mzjn; 09.08.2011

arrow_upward
0
arrow_downward

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

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

Он будет отображаться Sphinx примерно так:

mymodule.foo(param1=_sentinel)
person KostyaEsmukov    schedule 05.05.2018