Add Type annotations developer guideline #4397
Conversation
Avasam
force-pushed
the
add-annotations-guidelines
branch
from
2401c13
to
818da0c
Compare
docs/development/developer-guide.rst
Outdated
| Setuptools makes use of inferred return annotations to reduce verbosity, | ||
| especially for complex return types. Explicit return types can be added for | ||
| functions whose inferred return type contains ``Any``, or that are not checked by | ||
| mypy (ie.: contains no parameter *and* no return type, see |
There was a problem hiding this comment.
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 fileTo 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 fileIs there any circumstance that it can actually get it right without explicit marks?
There was a problem hiding this comment.
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
|
@abravalheri Updated and added a few more details ! |
Avasam
force-pushed
the
add-annotations-guidelines
branch
from
ff82066
to
e9f787a
Compare
| ---------------- | ||
|
|
||
| Most standards and best practices are enforced by | ||
| [Ruff](https://docs.astral.sh/ruff/rules/)'s ``ANN2``, ``FA``, ``PYI``, ``UP`` |
| Avoid importing private type-checking-only symbols. These are often | ||
| [typeshed](https://github.com/python/typeshed) internal details and are not | ||
| guaranteed to be stable. | ||
| Importing from ``_typeshed`` or ``typing_extensions`` is fine, but if you find |
There was a problem hiding this comment.
It's annoying, I can't find how to create a newline w/o creating a new paragraph in RST.
Avasam
force-pushed
the
add-annotations-guidelines
branch
from
3faa7b0
to
59de2cf
Compare
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
newsfragments/. (N/A)(See documentation for details)