Couldn't read PEP-224 variable docstrings from x

[timkofu]

Expected Behavior

pdoc3 ignores .py files without docstrings.

Actual Behavior

pdoc3 throws a UserWarning exception "Couldn't read PEP-224 variable docstrings from ..."

Steps to Reproduce

1. run pdoc3 on a .py file without a docstring

Additional info

• pdoc version: 0.8.1

[kernc]

The warning you mention is printed when the source code of a module/object can't be determined:

pdoc/pdoc/__init__.py

Lines 238 to 242 in 048919e

	try:
	tree = ast.parse(inspect.getsource(doc_obj.obj))
	except (OSError, TypeError, SyntaxError) as exc:
	warn("Couldn't read PEP-224 variable docstrings from {!r}: {}".format(doc_obj, exc))
	return {}, {}

[kernc]

The warning is also raised when the source code does not follow valid Python 3 syntax ...

Maybe we should also print the raised exception type. 🤔

[timkofu]

Here's the reproduction:

➜  test_pdoc touch test1.py
➜  test_pdoc mkdir test
➜  test_pdoc touch test/__init__.py
➜  test_pdoc touch test/test2.py

➜  test_pdoc pdoc3 test1.py
.../lib/python3.8/site-packages/pdoc/__init__.py:239: UserWarning: Couldn't read PEP-224 variable docstrings from <Module 'test1'>: could not get source code
  warn("Couldn't read PEP-224 variable docstrings from {!r}: {}".format(doc_obj, exc))
Module test1
============

➜  test_pdoc pdoc3 test
.../lib/python3.8/site-packages/pdoc/__init__.py:239: UserWarning: Couldn't read PEP-224 variable docstrings from <Module 'test'>: could not get source code
  warn("Couldn't read PEP-224 variable docstrings from {!r}: {}".format(doc_obj, exc))
.../lib/python3.8/site-packages/pdoc/__init__.py:239: UserWarning: Couldn't read PEP-224 variable docstrings from <Module 'test.test2'>: could not get source code
  warn("Couldn't read PEP-224 variable docstrings from {!r}: {}".format(doc_obj, exc))
Module test
===========

Sub-modules
-----------
* test.test2

➜  test_pdoc pdoc3 --version
pdoc3 0.8.1
➜  test_pdoc python --version
Python 3.8.2

[kernc]

Confirmed.

>>> import inspect, test.test2

>>> test.test2
<module 'test.test2' from '/tmp/test/test2.py'>

>>> inspect.getsource(test.test2)
------------------------------------------------------------------------------------
/usr/lib/python3.7/inspect.py in findsource(object)
    784         lines = linecache.getlines(file)
    785     if not lines:
--> 786         raise OSError('could not get source code')
    787 
    788     if ismodule(object):

OSError: could not get source code

The problem is already in inspect.getsource(), which raises instead of returning empty string. 😕

[kernc]

This is Python bug bpo-27578 and proposed fixing PR python/cpython#20809. Encouraged to upvote; contribs move nowhere in CPython. 😆

[timkofu]

Up-voted 👍