Re: Adding type hints directly to docutils?
Guenter Milde via Docutils-develop <[email protected]>
| Newsgroups | gmane.text.docutils.devel |
|---|---|
| Message-ID | <[email protected]> |
Dear Stephen, On 2024-04-15, Stephen Finucane wrote: > I recently had to contribute a fix to the stubs type hints package for > docutils in typeshed [1]. Is there any reason *not* to add these > directly to docutils? * Historically, support for legacy versions prevented directly adding type hints. * Currently, the main reason is: "it must be done by someone" and it is just one of may open tasks. * The main author is no longer active and sometimes the correct type is not known (e.g. there are still cases with 0 and 1 for booleans from the days Python did not have False/True). Sometimes no hint may be better than a misleading hint... I don't know about the quality of the existing stubs. * One more reason is the idea to wait until we drop support for Python 3.9 (once it reaches end of life...) so we can use the union operator (:PEP:`604`). > I would be willing to tackle this effort if it would be welcomed (I > previously tackled the "make docutils support Python 3 natively" > effort, along with some smaller quality-of-life fixes). Contributions are welcome. > As a follow-up to the above, are there any significant concerns with > using a tool like 'ruff format' or 'black' to auto-format code before > adding the annotations? It's small thing but it would make the process > of folding in hints somewhat easier if I can rely on tooling to handle > formatting for me. There is support for automatic checks with https://pre-commit.com for Git-based repos (a ".pre-commit-config.yaml" file). It includes checks for trailing-whitespace and flake8 (with ".flake8" configuration files for the numerous exceptions due to legacy code or practicability). "black" seems too rigid to me (practicability beats purity), especially as we have a large codebase with long legacy and must rely on "git blame" in many cases to find out whether some legacy code may be dropped or has a reason... Günter _______________________________________________ Docutils-develop mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/docutils-develop Please use "Reply All" to reply to the list.