Unsoundness with `typing.IO` and friends

Open
#1,994 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Stale
Tech stack
python
Domain
tooling

Research direction

Start by reviewing the runtime behavior of typing.IO, typing.BinaryIO, typing.TextIO, and io.BytesIO, along with their typeshed relationships and the linked CPython issue. Compare the three proposed approaches and document or implement an agreed specification and runtime direction; done requires resolving how isinstance() and issubclass() should behave.

Written by the indexing model from the issue text.

Description

topic: other

The classes typing.IO, typing.BinaryIO, and typing.TextIO look like they want to be Protocols or ABCs, but in fact they are defined as regular generic classes, both at runtime and in typeshed. However, they are meant to encompass the concrete IO classes defined in the io module, and in typeshed we implement that by having these classes inherit from typing.*IO classes, even though there is no such inheritance at runtime.

This can easily lead to unsound behavior:

import io, typing

def f(x: int | io.BytesIO) -> int:
    if isinstance(x, typing.BinaryIO):
        return x.fileno()
    return x

f(io.BytesIO()) + 1  # boom

Type checkers think BytesIO is a subclass of BinaryIO, because that's how it's defined in typeshed, but in fact it isn't at runtime.

I can see a few solutions:

  1. Special-case typing.*IO in the spec and say that type checkers should reject isinstance()/issubclass() calls involving them.
  2. Deprecate the typing.*IO classes and eventually remove them, nudging people to use their own Protocols (or the new io.Reader/io.Writer) instead. This is conceptually clean but may be annoying for a lot of users; the typing classes are nice to use in simple application code.
  3. Make these classes actually (runtime-checkable?) Protocols at runtime, though they would be unwieldily large.

Even if we do (2) or (3) type checkers might still want to do (1) since it will be a while before the relevant runtime changes take effect.

(Noticed this while looking into https://github.com/python/cpython/issues/133492 .)

Dominant language
Python
Stars
1.8k
Forks
302
Avg merge
23h
Merged PRs (30d)
8

Contributor guide

No contributing guide indexed for this repository

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.

More from python/typing

All issues in python/typing

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.