Getting exception with Python 3.9 and 0.9.2

[dbrattli]

Expected Behavior

Should work with Python 3.9.

Actual Behavior

Getting exception:

Traceback (most recent call last):
  File "/usr/local/bin/pdoc", line 8, in <module>
    sys.exit(main())
  File "/usr/local/lib/python3.9/site-packages/pdoc/cli.py", line 572, in main
    recursive_write_files(module, ext='.html', **template_config)
  File "/usr/local/lib/python3.9/site-packages/pdoc/cli.py", line 349, in recursive_write_files
    recursive_write_files(submodule, ext=ext, **kwargs)
  File "/usr/local/lib/python3.9/site-packages/pdoc/cli.py", line 344, in recursive_write_files
    f.write(m.html(**kwargs))
  File "/usr/local/lib/python3.9/site-packages/pdoc/__init__.py", line 832, in html
    html = _render_template('/html.mako', module=self, **kwargs)
  File "/usr/local/lib/python3.9/site-packages/pdoc/__init__.py", line 158, in _render_template
    return t.render(**config).strip()
  File "/usr/local/lib/python3.9/site-packages/mako/template.py", line 476, in render
    return runtime._render(self, self.callable_, args, data)
  File "/usr/local/lib/python3.9/site-packages/mako/runtime.py", line 878, in _render
    _render_context(
  File "/usr/local/lib/python3.9/site-packages/mako/runtime.py", line 920, in _render_context
    _exec_template(inherit, lclcontext, args=args, kwargs=kwargs)
  File "/usr/local/lib/python3.9/site-packages/mako/runtime.py", line 947, in _exec_template
    callable_(context, *args, **kwargs)
  File "_html_mako", line 143, in render_body
  File "_html_mako", line 49, in show_module
  File "_html_mako", line 428, in render_show_module
  File "/usr/local/lib/python3.9/site-packages/pdoc/__init__.py", line 1085, in subclasses
    for c in type.__subclasses__(self.obj))
TypeError: descriptor '__subclasses__' for 'type' objects doesn't apply to a 'types.GenericAlias' object

Steps to Reproduce

1. git clone https://github.com/dbrattli/Expression.git
2. cd expression
3. pdoc --html expression -o docs

Additional info

• pdoc version: 0.9.2

[kernc]

What's the exception? The traceback seems to be missing a line.

[dbrattli]

Yes, sorry. Also updated traceback above:

TypeError: descriptor '__subclasses__' for 'type' objects doesn't apply to a 'types.GenericAlias' object

[kernc]

Thanks. Upstream issue bpo-40296.

If you want to have a look about fixing / special-casing this, welcome.

pdoc/pdoc/__init__.py

Lines 1068 to 1077 in bec6307

	def subclasses(self) -> List['Class']:
	"""
	Returns a list of subclasses of this class that are visible to the
	Python interpreter (obtained from `type.__subclasses__()`).
	The objects in the list are of type `pdoc.Class` if available,
	and `pdoc.External` otherwise.
	"""
	return sorted(cast(Class, self.module.find_class(c))
	for c in type.__subclasses__(self.obj))

[dbrattli]

Some more info. The object itself where pdoc crashed is a type alias:

Try = Result[TSource, Exception]

I.e Try is just a narrower Result type where the last generic type is pinned to Exception. This object will give False for issubclass(type(self.obj), type).

So the object being checked for subclasses is expression.core.result.Result[~TSource, Exception] which have already been documented. So I think it should perhaps just be skipped by pdoc?

[kernc]

Yeah, given the bpo bug, I guess if our __subclasses__() call fails with TypeError that contains 'types.GenericAlias', we can just return an empty list?

[dbrattli]

Yes, that works but gives duplicates the Result type in the menu (to the left). The doc page itself gets the name (Try) right. Any docstring for Try as a variable is not picked up.

Sub-classing fixes the problem with documenting the Try "alias", but will give a little runtime overhead because of the subclass e.g:

class Try(Result[TSource, Exception]):
   """A result type where the failure case can only be a valid
   exception."""

[kernc]

Any docstring for Try as a variable is not picked up.

PEP-224 docstring for Try variable is not picked up?

Looks related to #229 (comment).

What other fix do you propose?

[dbrattli]

Yes, this is the same as #229. We should document it as a type alias and not as a class.

[ajyoon]

Was it expected that bpo 40296 would resolve this issue? I'm on Python 3.10.4, which I believe should include the fix, and I still get an error like this.

Traceback (most recent call last):
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/bin/pdoc", line 8, in <module>
    sys.exit(main())
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/cli.py", line 575, in main
    recursive_write_files(module, ext='.html', **template_config)
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/cli.py", line 351, in recursive_write_files
    recursive_write_files(submodule, ext=ext, **kwargs)
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/cli.py", line 351, in recursive_write_files
    recursive_write_files(submodule, ext=ext, **kwargs)
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/cli.py", line 346, in recursive_write_files
    f.write(m.html(**kwargs))
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/__init__.py", line 880, in html
    html = _render_template('/html.mako', module=self, **kwargs)
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/__init__.py", line 155, in _render_template
    return t.render(**config).strip()
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/mako/template.py", line 439, in render
    return runtime._render(self, self.callable_, args, data)
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/mako/runtime.py", line 874, in _render
    _render_context(
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/mako/runtime.py", line 916, in _render_context
    _exec_template(inherit, lclcontext, args=args, kwargs=kwargs)
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/mako/runtime.py", line 943, in _exec_template
    callable_(context, *args, **kwargs)
  File "_html_mako", line 143, in render_body
  File "_html_mako", line 43, in show_module
  File "_html_mako", line 428, in render_show_module
  File "/home/ayoon/.cache/pypoetry/virtualenvs/neoscore-ptOHLkol-py3.10/lib/python3.10/site-packages/pdoc/__init__.py", line 1138, in subclasses
    for c in type.__subclasses__(self.obj))
TypeError: descriptor '__subclasses__' for 'type' objects doesn't apply to a '_CallableGenericAlias' object

[kernc]

This is how it was special-cased in pydoc: python/cpython#30253. I guess we should do something similar for pdoc3.