Type annotations for `trio.open_file` & `trio.wrap_file`

[kinnay]

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?

[CoolCat467]

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 AsyncIOWrapper or a protocol that represents it somewhere.

Until exposed publicly, trio._file_io.AsyncIOWrapper is indeed the correct annotation to use for the moment, unless you write a Protocol class that represents it yourself.

[TeamSpen210]

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]

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!