Add Type annotations developer guideline

[Avasam]

Summary of changes

Add Type annotations developer guideline
CC @abravalheri feel free to wordsmith. I figured these things are probably better documented with sources than left in PR discussions.

Pull Request Checklist

• Changes have tests (N/A)
• News fragment added in newsfragments/. (N/A)
  (See documentation for details)

[abravalheri]

I have a curiosity question:

In which instances mypy can correctly infer return types without degenerating to Any?
For example, I tried the following:

def fn(a: str):
    return int(a)

reveal_type(fn)

main.py:4: note: Revealed type is "def (a: builtins.str) -> Any"
Success: no issues found in 1 source file

To me the return value should be int, but mypy infers a "degenerate" Any.

"Humanly obvious" None also are not correctly inferred:

def fn(a: str):
    print(a)

reveal_type(fn)

main.py:4: note: Revealed type is "def (a: builtins.str) -> Any"
Success: no issues found in 1 source file

Is there any circumstance that it can actually get it right without explicit marks?

[Avasam]

Oh my... I've always (wrongly) assumed that mypy at least infers the return type for functions it does type-check...

Maybe we should instead turn on some ANN2 rules for public methods so this can be checked automatically instead of having to add it as a guideline.

• https://docs.astral.sh/ruff/rules/missing-return-type-undocumented-public-function/
• https://docs.astral.sh/ruff/rules/missing-return-type-static-method/
• https://docs.astral.sh/ruff/rules/missing-return-type-class-method/

https://mypy.readthedocs.io/en/stable/config_file.html#confval-disallow_incomplete_defs is also an option.

At least until if/when mypy introduces more return type inference like requested in python/mypy#4409 and python/mypy#17307

[Avasam]

Even w/o enforcement, running ruff check pkg_resources --fix --unsafe-fixes --select=ANN2 --ignore=ANN202,ANN204 (ignoring tests) is pretty valuable.

Let's merge #4390 and #4391 first.

[Avasam]

@abravalheri Updated and added a few more details !

[Avasam]

ANN2 added in #4409

[abravalheri]

I did not find the FA rules, is that PyFlake (F)?

[Avasam]

It's annoying, I can't find how to create a newline w/o creating a new paragraph in RST.

[abravalheri]

Yeah \n is threated in RST as a space and \n\n creates a new paragraph, no other option.

[abravalheri]

I think this is markdown syntax for link, but setuptools uses RST.
There is a couple of other occurrences below.

[Avasam]

Not used to RST, but I think I got it right

[abravalheri]

Thank you.

Reminder for my future self, probably adding something like https://github.com/sloria/sphinx-issues is useful.

[abravalheri]

Thank you very much.