Skip to content

[pywin32] Improve pipe and device I/O typing - #16456

Open
Robolightning wants to merge 4 commits into
python:mainfrom
StableKite:typing/pywin32-stablekite-surface
Open

Robolightning wants to merge 4 commits into
python:mainfrom
StableKite:typing/pywin32-stablekite-surface

Conversation

@Robolightning

Copy link
Copy Markdown

This improves typing for several pywin32 pipe and device-I/O APIs.

Changes:

  • type ConnectNamedPipe as returning int
  • type CreateNamedPipe numeric parameters and WaitNamedPipe.timeout as int
  • type PeekNamedPipe as returning tuple[bytes, int, int]
  • add DeviceIoControl overloads for synchronous bytes output, overlapped memoryview output, and caller-supplied writable buffers

Validation:

  • mypy over the two changed stubs: pass
  • typeshed stubtest for win32pipe and win32file on Windows: pass
  • strict latest Pyright (1.1.414) consumer: 0 errors, 0 warnings, 0 informations
  • real pywin32 312 named-pipe runtime smoke: pass

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@Avasam
Avasam self-requested a review October 30, 2026 19:51

@Avasam Avasam left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution, here's a few improvements I found.

Comment thread stubs/pywin32/win32/win32file.pyi Outdated
Comment on lines +38 to +46
Device: int, IoControlCode: int, InBuffer: ReadableBuffer | None, OutBuffer: int, Overlapped: None = None
) -> bytes: ...
@overload
def DeviceIoControl(
Device: int, IoControlCode: int, InBuffer: ReadableBuffer | None, OutBuffer: int, Overlapped: _win32typing.PyOVERLAPPED
) -> memoryview: ...
@overload
def DeviceIoControl(
Device: int,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Device: int is overly restrictive and rejects handle objects

Suggested change
Device: int, IoControlCode: int, InBuffer: ReadableBuffer | None, OutBuffer: int, Overlapped: None = None
) -> bytes: ...
@overload
def DeviceIoControl(
Device: int, IoControlCode: int, InBuffer: ReadableBuffer | None, OutBuffer: int, Overlapped: _win32typing.PyOVERLAPPED
) -> memoryview: ...
@overload
def DeviceIoControl(
Device: int,
Device: int | _win32typing.PyHANDLE, IoControlCode: int, InBuffer: ReadableBuffer | None, OutBuffer: int, Overlapped: None = None
) -> bytes: ...
@overload
def DeviceIoControl(
Device: int | _win32typing.PyHANDLE, IoControlCode: int, InBuffer: ReadableBuffer | None, OutBuffer: int, Overlapped: _win32typing.PyOVERLAPPED
) -> memoryview: ...
@overload
def DeviceIoControl(
Device: int | _win32typing.PyHANDLE,

Comment thread stubs/pywin32/win32/win32pipe.pyi Outdated
nOutBufferSize: int,
nInBufferSize: int,
nDefaultTimeOut: int,
sa: _win32typing.PySECURITY_ATTRIBUTES,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not part of your changes, but may as well fix: This can be None, pywin32's own win32/test/test_win32file.py calls this as such.

Suggested change
sa: _win32typing.PySECURITY_ATTRIBUTES,
sa: _win32typing.PySECURITY_ATTRIBUTES | None,

Comment thread stubs/pywin32/win32/win32file.pyi Outdated
Comment on lines +49 to +51
OutBuffer: WriteableBuffer,
Overlapped: _win32typing.PyOVERLAPPED | None = None,
) -> WriteableBuffer: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OutBuffer: WriteableBuffer rejects AllocateReadBuffer(n), even though the pywin32 docs name it as the intended input

https://github.com/mhammond/pywin32/blob/c113057938cc1536fb243c9ceb8e863aa2e448cc/win32/src/win32file.i#L374-L375

// @pyparm int/buffer|OutBuffer||Size of the buffer to allocate for output, or a writeable buffer
// as returned by .

The stub types its return as _win32typing.PyOVERLAPPEDReadBuffer, an empty class that is not a Buffer. The ReadFile overloads in the same file already handle this with _BufferT = TypeVar(bound=PyOVERLAPPEDReadBuffer | WriteableBuffer). I'd suggest the same here:

Suggested change
OutBuffer: WriteableBuffer,
Overlapped: _win32typing.PyOVERLAPPED | None = None,
) -> WriteableBuffer: ...
OutBuffer: _BufferT,
Overlapped: _win32typing.PyOVERLAPPED | None = None,
) -> _BufferT: ...

This also tightens the return type.

Comment thread stubs/pywin32/win32/win32pipe.pyi Outdated
nDefaultTimeOut: int,
sa: _win32typing.PySECURITY_ATTRIBUTES,
/,
) -> int: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not directly part of your changes, but may as well fix if modifying this function:

Suggested change
) -> int: ...
) -> _win32typing.PyHANDLE: ...

@github-actions

Copy link
Copy Markdown
Contributor

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants