#87 [FR] Giving type annotations to docutils
Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface
Hi all,
I noticed py2 and py36- support will be dropped in the next release.
Yes, I am currently working on this, ... soon in the repository.
Günter @milde -- happy to help with this if you'd like?
It helps to integrate type annotations in docutils-stub package into
upstream.
I believe it helps to develop third-party extensions (including Sphinx).
Is there any chance to merge it into the docutils?In my view, it would make sense to have annotations right in the "master".
This could also be used as an indicator for the public API:
In the Docutils Backwards Compatibility Policy, we could change the
clause about the "scope of the public API" to an "opt-in" scheme: only
function/class interfaces with annotations belong to the stable, public
API while not annotated function interfaces may be changed or removed in
future versions if this helps to improve or clean up the code base.What do other Docutils developers/contributors/users think?
In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful.
I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion.
A
Firstly, definitely +1 in general for "inline" type annotations.
That's an interesting take 😬
As noted in the original post, the major use-case of these type annotations are for third-party extension development, e.g. to allow for programmatic (mypy) type checking against docutils usage.
Third-party extensions should "only" care about the public API
Aha sorry - imprecision of language strikes again!
For almost everyone, type annotations of the public API will be far and away the most useful.
For developers of Docutils itself, I believe also annotating private methods will be useful -- my comment was more arguing against just annotating the public API, but carried with it the implicit assumption that the public API would be annotated regardless.
Sorry for the misunderstanding!
A
I.e. we should not use "not annotated" as the only indication of a non-public or provisional part of the API.
It would still help in the major task of clearly defining the public API, if we could state that by default:
all functions, classes, and variables are provisional unless annotated
annotated objects that are not part of the public API must say so (either using underscore or in the docstring).
* if a module is marked as provisional, this holds for all objects defined in this module, whether they are annotated or not.
I agree that Sourceforge is sub-optimal on many edges.
As explained in the Docutils documentation Docutils Mailing Lists,
you may use any e-mail application to send a mail to docutils-develop@lists.sourceforge.net.
(A click on the link given there will open an e-mail application in most browsers.)
I don't understand why Sourceforge does not allow to place "mailto" links or an explaining text on https://sourceforge.net/p/docutils/mailman/. At least I managed to let the "Support" tab point to our own documentation as the "best way to get help".
Last edit: Günter Milde 2022-01-03
This is also sort of my problem -- I have many mail aliases (e.g. docutils@example.org.uk) that forward to the single account I send from (adam@example.org.uk). This allows me to filter incoming emails and if one alias gets on a spam list it isn't a massive deal.
That does mean that sending to public mailing lists is an issue though -- why I prefer bug trackers/forums like discourse. If needed though I'll sort myself out eventually!
A
Thanks for the first commits with type hints.
We should, however, mention, that using the type hints (with e.g. mypy) requires Python 3.10 or newer. With 3.9 and mypy 0.812, I get, e.g., for
mypy docutils/core.pythe result:Also, the boilerplate (TYPE_CHECKING blocks) are quite large. How about a dedicated module for Docutils-specific type definitions?
We may also define shortcuts/aliases for often used Unions like
str | os.PathLike[str]which may offer a better intelligible way of representingpathdict: dict[str, list[str | os.PathLike[str]] | str | os.PathLike[str]], say.