Type hint for a file or file-like object?

Question

Is there any correct type hint to use for a file or file-like object in Python? For example, how would I type-hint the return value of this function?

def foo() -> ???:
    return open('bar')

Solution 1

Use either the typing.TextIO or typing.BinaryIO types, for files opened in text mode or binary mode respectively.

From the docs:

class typing.IO

Wrapper namespace for I/O stream types.

This defines the generic type IO[AnyStr] and aliases TextIO and BinaryIO for respectively IO[str] and IO[bytes]. These representing the types of I/O streams such as returned by open().

Solution 2

The short answer:

• You need to be explicit. That is from typing import TextIO not just from typing import *.
• Use IO to mean a file without specifying what kind
• Use TextIO or BinaryIO if you know the type
• You cannot currently specify it be opened for write or its encoding.

As an example:

from typing import BinaryIO

def binf(inf: BinaryIO):
    pass

with open('x') as f:
    binf(f)

gives an inspection error (in PyCharm) of Expected type 'BinaryIO', got 'TextIO' instead

Comments

[Yongwei Wu]

Generically, maybe typing.IO as the type description?

[Admin]

None of these seem to work for me: def f() -> IO: return open('test') gives "Expected type 'IO', got 'TextIOWrapper[str]' instead" in PyCharm.

[Wayne Werner]

@Marein what about IO[str]?

[Admin]

The same I'm afraid. I'm also noticing that iterating over the lines in a file gives "Expected 'collections.iterable'".

[Wayne Werner]

@Marein I suggest that you post a new question with a minimal reproducible example because your code works fine for me, even using PyCharm.

[Jean-François Corbett]

Reproduced @Marein's issue in PyCharm community 2017.2: i.imgur.com/Ai4sVQl.jpg

[CMCDragonkai]

Why does BufferedReader not come under the IO type? Mypy keeps saying that it got BufferedReader, but expects Optional[IO[Any]].

[Tshirtman]

The documentation is a bit confusing, it indicates a deprecation, but i’m not entirely sure what is covered by it, the optimist interpretation that it’s only about the typing.io namespace, but i’m not keen on being too optimistic when programming.

[mxmlnkn]

@Tshirtman I think you can be a optimistic about this. I found this issue regarding the deprecation and it seems to be clearer about typing.io being the namespace to be deprecated because typing.io.BinaryIO and others also exist and were mostly used directly from the typing namespace, e.g., typing.BinaryIO.

[Tshirtman]

@mxmlnkn indeed, that bug certainly disambiguates it, thanks :)