Repository navigation
Type annotations for trio.open_file & trio.wrap_file #3390
Description
Hi,
I am currently adding type annotations to my projects. It seems that trio.open_file and trio.wrap_file returns an instance of the trio._file_io.AsyncIOWrapper. What puts me off a bit is the _file_io part, because names that begin with an underscore are usually meant to be private.
Is trio._file_io.AsyncIOWrapper the correct type annotation to use for the return value of trio.open_file? If so, does it not make sense to expose this type as part of Trio's public API, e.g. trio.AsyncIOWrapper, or perhaps trio.abc.AsyncIOWrapper?
Activity
CoolCat467 commentedon Feb 13, 2026
I previously also encountered this issue and made a pull request to fix it, but it never went through. I don't remember why I closed it, that was 2 years ago, but I agree we should publicly expose
AsyncIOWrapperor a protocol that represents it somewhere.Until exposed publicly,
trio._file_io.AsyncIOWrapperis indeed the correct annotation to use for the moment, unless you write aProtocolclass that represents it yourself.[-]Type hints for trio.open_file / trio.wrap_file[/-][+]Type annotations for `trio.open_file` & `trio.wrap_file`[/+]TeamSpen210 commentedon Feb 13, 2026
As I mentioned there it might be better to declare your own protocol. The type is complicated, using a lot of self-types to limit its API to match the sync file's methods. Given the complexity I was imagining it'd be likely it needs tweaking in future. Also using it prevents you from accepting any native file objects which just directly implement the async methods.
A5rocks commentedon Feb 14, 2026
Yeah I think it's a very complicated type and maybe not ideal to export. However, I also think there's not that many downsides -- I think we don't especially care about type hint changes being breaking (because it doesn't break working programs!), so I don't think it's that important to worry about future changes.
I'd be fine if it were exported!