python / python/typeshed

Use of generics in requests typing

Open
#10,899 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
5.1k
Forks
2.1k
Avg merge
1d 19h
Merged PRs (30d)
82

Description

Currently the requests typing makes heavy use of unions. For example the parameter type is:
https://github.com/python/typeshed/blob/f99e8b0615182bb0f17d9d126019d8d72c207ab3/stubs/requests/requests/sessions.pyi#L97-L103

The issue with this approach is that the type system can't keep track of which type has been chosen for a given field. For example, running pyright on this code:

from requests import Session

session = Session()
session.params = {}
reveal_type(session.params)

Shows us that the type system immediately "forgets" that our parameters are definitely in a dictionary:

test.py:5:13 - information: Type of "session.params" is "dict[str | bytes | int | float, str | bytes | int | float | Iterable[str | bytes | int | float] | None]"
0 errors, 0 warnings, 1 information

If we could make Session (as well as other classes such as Request) generic over the parameter type (as well as other fields), then we could keep track of this kind of state. For example, it might look like:

session: Session[dict] = Session()

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 requests/requests/sessions.pyi section around lines 97-103, then review how Session and Request are typed. Use the provided pyright example to assess whether generic parameter types remain specific after assignment; done means the proposed generic design is consistently defined for the affected classes and preserves the selected field types.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.