[Docutils-develop] [docutils:feature-requests] Re: #87 [FR] Giving type annotations to docutils

[Günter M. <mi...@us...>]

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.



---

** [feature-requests:#87] [FR] Giving type annotations to docutils**

**Status:** open
**Group:** Default
**Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam  Turner
**Last Updated:** Mon Jan 03, 2022 10:18 AM UTC
**Owner:** nobody


*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* 

[1]: https://sourceforge.net/p/docutils/mailman/message/37410168/

> > 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


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.