python / python/cpython

`None` vs `Never` as `typing.Generator`'s send type

Open
#123,521 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs topic-typing
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Documentation

Documentation for typing.Generator currently says:

If your generator will only yield values, set the SendType and ReturnType to None

While not obviously wrong, using None as SendType looks imprecise: we want a typechecker to warn about .send(t) calls for any t, right? Using that method likely indicates that the generator is used incorrectly.

Now type checkers will reject .send(t) calls for all t types except None and Any.

Since python 3.11 we have a Never type - effectively a "please don't" type. So setting SendType to Never instead of None would be more useful from the interface declaration perspective: literally saying "please don't send anything here".

I do understand that None is there to match runtime behaviour closer since calling it.send(None) is equivalent to calling next(it) for the next time, so None is formally correct. However, there's no benefit ever from doing it.send(None) if the generator does not use sent values - calling next(it) is clearly preferable.

My suggested solution is to recommend typing.Never as SendType in such cases in documentation. I'm ready to write a PR with this change.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked typing.Generator documentation and review the guidance for SendType and ReturnType. Check the five-comment discussion before proceeding, since the issue has had no recent activity. Done means the documentation reflects the resolved recommendation for generators that do not accept sent values.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.