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: https://github.com/pdoc3/pdoc/blob/048919ece483e0609094cee2460d3467d2e0efc3/pdoc/init.py#L238-L242

[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. :thinking:

[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. :confused:

[kernc]

This is Python bug bpo-27578 and proposed fixing PR https://github.com/python/cpython/pull/20809. Encouraged to upvote; contribs move nowhere in CPython. :laughing:

[timkofu]

Up-voted 👍