What about the _winapi and _overlapped modules?

I’ve just found out that there exist the so called _winapi and _overlapped modules, and as mentioned here winapi - Python's _winapi module - Stack Overflow, the _winapi module is in the stdlib since 3.3.
My question would be that how official are these modules? On Windows, I used the pywin32 package (for creating and waiting on windows events), but that can be problematic, and if there is a builtin, I would prefer to use that one.
I mean, there is no documentation about these, so are these ok to use? Is it planned to be documented? Thanks!

It’s not okay for scripts and libraries to directly depend on _winapi or _overlapped. The initial underscore means that they should be treated as private modules. They will never be documented.


_winapi and _overlapped are private implementation details of CPython that only provide a few functions needed by other standard library modules. They’ll probably stick around and technically there’s nothing stopping you from using them, but we won’t entertain enhancement requests for them that don’t serve other parts of the standard library, and there’s no guarantee that their APIs won’t change between, say, 3.11 and 3.12…or even between 3.11.1 and 3.11.2. If you use them anyway and open a bug report after we break your code, I’ll close it saying “I told you so” :wink:

Better to go with pywin32.


FYI, there are bugs in _winapi, such as linking to the [A]NSI versions of functions (e.g. CreateFileA instead of CreateFileW) and passing UTF-8 byte strings instead of ANSI strings, and converters such as the DWORD converter that don’t do proper bounds checking. Most of these issues are not a problem for how _winapi is used by the standard library. Also, functions such as _winapi.CreateJunction() may be added just for internal tests and should never be used by scripts because they don’t do enough error checking and cleanup (e.g. leaving an empty directory on failure; not checking whether the target is a directory on a local filesystem).

1 Like

Thanks for the clarifications!

1 Like