Some decorated functions are ignored by pdoc3

[inhumantsar]

I'm not sure if this is a Click issue or a pdoc3 issue. It came up when running pdoc3 against our CLI project using Click 7. Figured I'd report the issue to both projects just in case.

Expected Behavior

Assuming we have a python package with one module containing the code below:

import click

def testdeco(func):
    def wrapper(x):
        print('in deco')
        func(x)
    return wrapper

@click.command()
@click.option('-s', '--some-arg', 'somearg')
def somefunc(somearg):
    """some func docstring"""
    print('foo')

@testdeco
def decofunc(n):
    print(n)

def otherfunc():
    """other func docstring"""
    print('bar')

I'd expect pdoc3 to generate relevant docs for somefunc()

Actual Behavior

Additional info

Click==7.0
Mako==1.1.1
Markdown==3.2.1
MarkupSafe==1.1.1
pdoc3==0.7.4

[kernc]

Clearly, _is_function() fails to return True for whatever objects click.commands are.

pdoc/pdoc/__init__.py

Lines 290 to 291 in 725bc1f

	def _is_function(obj):
	return inspect.isroutine(obj) and callable(obj)

[kernc]

Scratch that. In all likelihood we're missing a second unwrap() call here:

pdoc/pdoc/__init__.py

Lines 559 to 562 in 725bc1f

	public_objs = [(name, inspect.unwrap(obj))
	for name, obj in inspect.getmembers(self.obj)
	if (_is_public(name) and
	(is_from_this_module(obj) or name in var_docstrings))]

click.decorators.command.<locals>.decorator will never be from our module. Can you confirm?

[inhumantsar]

click.decorators.command.<locals>.decorator will never be from our module. Can you confirm?

i'm sorry? if you mean a situation like the reproduction above, no. that module would never call decorator directly.

[kernc]

I meant is_from_this_module(obj) won't be true for obj (which in your case is click.decorators.command.<locals>.decorator object) unless inspect.unwrap(obj) was called on it beforehand.

---

But I'm afraid the proposed solution won't work as click's decorators don't set __wrapped__ (as is customary for decorators) via functools.update_wrapper() nor via functools.wraps().
Instead they only set __doc__ manually:
https://github.com/pallets/click/blob/56314dbdc6075307d2104b2ae640186acb81a8ef/click/decorators.py#L116
See relevant:
pallets/click#127
pallets/click#234
pallets/click#255
If they decide to add __wrapped__ as well, this will become a pdoc3 bug. 😸

[kernc]

unless inspect.unwrap(obj) was called on it beforehand.

In fact, it appears well-defined decorators should set __module__ as well, so an additional inspect.unwrap() call is unnecessary.

This is not our bug.

A workaround is to declare __all__.