Support Python 3

[hawkowl]

This is an organizing for Python 3 support, to keep everything under one roof.

TODO: add checklist?

[mwhudson]

The major item of work is moving away from the compiler package. astbuilder is the core hard part of pydoctor!

[twm]

#147 (epydoc only works on Python 2 and is unmaintained) seems relevant. Will we have to port and/or vendor some portion of epydoc to get pydoctor running on Python 3?

[mthuurne]

As far as I know, the master branch of pydoctor runs fine on Python 3 now. Please try it on your code and report any issues.

The next step would be dropping Python 2.7 support. Should that be tracked in this issue or should I create a new issue for that?

[mikepurvis]

$ pip3 install git+https://github.com/twisted/pydoctor.git --upgrade
...
Successfully built pydoctor CacheControl
ERROR: pydoctor 19.11.0 requires enum34, which is not installed.
Installing collected packages: incremental, appdirs, msgpack, lockfile, CacheControl, pydoctor

The enum34 dep should be conditional on sys.version_info. Otherwise it seems to work great for my use-case. Thanks for your work on this and for pinging to let me know.

[mthuurne]

$ pip3 install git+https://github.com/twisted/pydoctor.git --upgrade
...
Successfully built pydoctor CacheControl
ERROR: pydoctor 19.11.0 requires enum34, which is not installed.
Installing collected packages: incremental, appdirs, msgpack, lockfile, CacheControl, pydoctor

The enum34 dep should be conditional on sys.version_info. Otherwise it seems to work great for my use-case. Thanks for your work on this and for pinging to let me know.

The entry in setup.py reads "enum34;python_version<'3.4'", which is supposed to restrict the requirement to Python versions that actually need it.

I can't reproduce the problem: if I run the same command line in a fresh virtualenv, it ignores enum34, as it should. I'm using Python 3.6.9 and pip 19.3.1, on Linux.

[mikepurvis]

Ah, okay— this is probably just my computer's python environment being a superfund site. Thanks for looking!

[wsanchez]

I created a PR in Klein to generate API docs. We can test Python 3 support there.

[sandrotosi]

Is there any chance of a release to include the python3 port? it would simplify the inclusion in Debian (which is actively trying to remove python2 support, so any help would help greatly). thanks!

[mthuurne]

After #183 is merged, I'm not aware of any bugs that would prevent pydoctor from being used for external projects.

In the case of Twisted though, there is code inside Twisted itself that is called by pydoctor. That code still needs to be migrated to Python 3. Ideally that would be fixed before releasing pydoctor, since Twisted is the largest code base out there using pydoctor and currently we don't use it for testing pydoctor under Python 3.

There are incomplete features, such as type annotation support being implemented for variables but not yet for functions, but that's not a regression compared to the previous release, which had no type annotation support at all. The old @type docstring tag still works.

[wsanchez]

#183 is merged.

[mthuurne]

Indeed. Unfortunately, there is another bug though that I found today: non-fatal errors in docstrings are sometimes not logged. It would be good to fix that before releasing. Part of the problem is that epytextproblems is reset by the driver, but that only drops them from the closing summary so another bug must be preventing them from being logged in detail. I can probably find some time to investigate next week.

What is still missing is type annotation support for function signatures. But while that is very nice to have, I don't think it's critical. Having a pydoctor release that runs on Python 3 with no known regressions would already be a big step forward.

Should we produce a universal wheel or separate wheels for Python 2 and 3? For universal, we'd need some minor changes in setup.cfg.

Who could make an official release? @hawkowl ?

[mikepurvis]

Ping, any chance of a release soon?

[mthuurne]

pydoctor 20.7.0 is now available on PyPI.

Please let me know if anything doesn't work.