Re: [Docutils-develop] Adding type hints directly to docutils?

[Stephen F. <st...@th...>]

On Tue, 2024-04-16 at 19:45 +0000, Guenter Milde via Docutils-develop wrote:
> 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.

Excellent. I just wanted to make sure it wouldn't be wasted effort.

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

I'm a big fan of pre-commit and use it in many of my projects. However, as the
project is hosted in SVN I had assumed any git-specific tooling would be out the
window. More than happy to add this.

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

I too have some concerns with the style of black-formatted code - as I do with
the style of gofmt-formatted Go code - however, it _is_ robustly maintained,
requires little to no configuration on our end, and effectively allows
formatting to be ignored by developers. It is also possible to add a '.git-
blame-ignore-revs' file that will allow git-blame to ignore certain revisions.
This file is also respected by some software forges such as GitHub, though I
think it's fair to assume it is ignored for SVN repos on Sourceforge :)

If it's okay with you, I will propose adding hints to a single module _with_
black to see how it works. If the output is truly awful, we can change tack and
try to find a formatter than is slightly closer to what we already have but
still allows me to avoid fixing formatting in some many 100s of files by hand.

Cheers,
Stephen

> 
> 
> Günter
> 
> 
> 
> 
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
> 
> Please use "Reply All" to reply to the list.