[Python] How to document Python functions with overload/dispatch decorators?

Discussão em 'Python' iniciado por Stack, Setembro 3, 2025.

  1. Stack

    Stack Membro Participativo

    I am using the multipledispatch package, in a fashion similar to the example code below. I want to be able to see the docstring text when I ask for help(my_add) in the Python command line, but instead all I see is information about the decorator.

    I have looked up functools.wraps, which I'm sure is what I want to use. I have found examples of how to use it, such as How can I apply a decorator to an imported function? and Python decorator handling docstrings.

    But I still don't entirely understand two issues:

    1. How to apply functools.wraps to external decorators that I don't "own"?
    2. How to apply it specifically to this case with multiple dispatch, since the function I want to wrap will have multiple docstrings associated with the same function name?

    Below is an example to help explain.

    >>> from multipledispatch import dispatch
    >>> @dispatch(str, str)
    ... def my_add(elem1, elem2):
    ... '''A flavor of 'add' where two strings are concatenated.'''
    ... return elem1 + ' ' + elem2
    ...
    >>> @dispatch(int, int)
    ... def my_add(elem1, elem2):
    ... '''A flavor of 'my_add' where two strings are concatenated.'''
    ... return elem1 + elem2
    ...
    >>> my_add('hey','you')
    'hey you'
    >>> my_add(4, 5)
    9
    >>> my_add(4.5, 6)
    # (Traceback details removed...)

    KeyError: (<class 'float'>, <class 'int'>)
    During handling of the above exception, another exception occurred:
    NotImplementedError: Could not find signature for my_add: <float, int>


    I wanted to show that error and the different dispatches just to show that that part is working as I want it (looking for the matched dispatch and calling the associated "flavor" of the function).

    But next, if I try to look at the help, instead of seeing the simple docstring that I have provided, I see the docstring associated with the @dispatch decorator.

    >>> help(my_add)

    Help on Dispatcher in module multipledispatch.dispatcher object:

    my_add = class Dispatcher(builtins.object)
    | Methods defined here:
    |
    | __call__(self, *args, **kwargs)
    | Call self as a function.
    |
    | __getstate__(self)
    |


    etc.

    I'm not even sure what it should show, since there are potentially 2 conflicting docstrings I'd like to push forward. So, I tried to see if I could call help on a function that's actually run, but then of course it gives me help on the returned data type. E.g.,

    >>> help(my_add(3, 5))

    Help on int object:

    class int(object)
    | int(x=0) -> integer
    | int(x, base=10) -> integer
    |
    | Convert a number or string to an integer, or return 0 if no arguments

    Continue reading...

Compartilhe esta Página