Add API type definitions through stub files

[AA-Turner]

@daviddrysdale

xref #200
closes #202
closes #203

This PR has the stubs, automatic checking of the stubs with mypy.stubgen, and changes to setup.py to support packaging type stubs (I think I made the changes to the right setup.py, I was mildly confused as there's another one at the top level)

A

[daviddrysdale]

Thanks for preparing this!

Just a couple of initial questions, without looking at the .pyi file details as yet.

I think I made the changes to the right setup.py, I was mildly confused as there's another one at the top level

IIRC that got added (#7) to help out folk who pointed installers at the top-level GitHub URL, which would then fail because the code is in a subdirectory. (I've added #209 as a reminder to sort this out)

[daviddrysdale]

A few questions from an initial pass (just looking over the smaller files).

[daviddrysdale]

Thanks for the updates; a couple more questions as I work through the PR.

[daviddrysdale]

Are the X as X parts needed?

[AA-Turner]

It is required, although looking at the docs it seems it might also be possible to put in __all__ -- though in other stub files I've seen it like this and thought it was the canonical approach

https://mypy.readthedocs.io/en/stable/config_file.html#confval-implicit_reexport (note the last line that implicit re-export is disabled for stubs -- the docs could be written more clearly here on the inverse of explicit re-exports)

[daviddrysdale]

Maybe make the layout of the imports match __init__.py more closely?

Or is this (and the X as X parts) something tool-derived that's easier to leave as-is?

[AA-Turner]

The from X import Y as Y was autogenerated, yes -- mypy.stubgen was able to infer a lot of stuff, but I had to manually correct a lot of types, and all private variables/class variables/functions I had to hand write, as stubgen didn't pick them up.

[daviddrysdale]

Phew, I've finished looking over the .pyi files! (I still want to check over the packaging changes btw)

[septatrix]

Given that there is a debian directory in this repo are you responsible for publishing new versions?

[daviddrysdale]

Given that there is a debian directory in this repo are you responsible for publishing new versions?

Nope. I included the debian/ at the request (#39) of someone else, but there's not been a significant update here since ~2015. Maybe check the Debian package info?