Documenting with Sphinx python methods that do have default parameters with sentinel objects?

Question

If you want to be able to allow people to call some methods using None you have to do use a sentinel object when you define the method.

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

This would allow you to call foo(param1=None) and be able to make the difference between a call like foo().

The problem is that when Sphinx does document the method it will write something like

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

How can I convince Sphinx to have a user friendly output for these functions?

Note, Imagine how the documentations look if you have 3-4 parameters using the sentinel approach.

score 1 · Answer 1 · answered May 05 '18 at 19:33

The <object object at 0x108c1a520> part of generated method signature can be changed by overriding the __repr__ method of the sentinel object.

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

It will be rendered by Sphinx as something like this:

mymodule.foo(param1=_sentinel)

score 1 · Answer 2 · answered Aug 08 '11 at 18:45

1

I don't think it is possible to persuade Sphinx to be more "friendly" as long as you have a sentinel that creates an object outside the function. Sphinx' autodoc extension imports the module, which means that module-level code is executed.

Are you sure you can't use something like this?

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

answered Aug 08 '11 at 18:45

mzjn

48,958
13
128
248

2

sentinel is a one-off object outside function so that function can handle None values as a general case so I believe sorin really can't use what you're suggesting. – Mikhail Korobov Aug 08 '11 at 20:32

score 1 · Answer 3 · answered Aug 08 '11 at 20:38

1

This can be handled by manually specifying function signature in autodoc directive, e.g.:

.. automodule:: pymorphy.contrib.tokenizers

    .. autofunction:: extract_tokens(foo, bar)

    .. autofunction:: extract_words

answered Aug 08 '11 at 20:38

Mikhail Korobov

21,908
8
73
65

Yes, this works: +1. Why didn't I think of it? :-) http://stackoverflow.com/questions/5365684 – mzjn Aug 08 '11 at 20:59

Documenting with Sphinx python methods that do have default parameters with sentinel objects?

3 Answers3

Linked