Sync Windows docstrings

Author: typeshedbot

crates/ty_vendored/vendor/typeshed/stdlib/_ctypes.pyi

@@ -31,22 +31,42 @@ if sys.platform == "win32":
     _COMError_Details: TypeAlias = tuple[str | None, str | None, str | None, int | None, int | None]
 
     class COMError(Exception):
+        """Raised when a COM method call failed.
+"""
         hresult: int
         text: str | None
         details: _COMError_Details
 
         def __init__(self, hresult: int, text: str | None, details: _COMError_Details) -> None: ...
 
-    def CopyComPointer(src: _PointerLike, dst: _PointerLike | _CArgObject) -> int: ...
+    def CopyComPointer(src: _PointerLike, dst: _PointerLike | _CArgObject) -> int:
+        """CopyComPointer(src, dst) -> HRESULT value
+"""
 
     FUNCFLAG_HRESULT: Final = 0x2
     FUNCFLAG_STDCALL: Final = 0x0
 
-    def FormatError(code: int = ...) -> str: ...
+    def FormatError(code: int = ...) -> str:
+        """FormatError([integer]) -> string
+
+Convert a win32 error code into a string. If the error code is not
+given, the return value of a call to GetLastError() is used.
+"""
     def get_last_error() -> int: ...
     def set_last_error(value: int) -> int: ...
-    def LoadLibrary(name: str, load_flags: int = 0, /) -> int: ...
-    def FreeLibrary(handle: int, /) -> None: ...
+    def LoadLibrary(name: str, load_flags: int = 0, /) -> int:
+        """LoadLibrary(name, load_flags) -> handle
+
+Load an executable (usually a DLL), and return a handle to it.
+The handle may be used to locate exported functions in this
+module. load_flags are as defined for LoadLibraryEx in the
+Windows API.
+"""
+    def FreeLibrary(handle: int, /) -> None:
+        """FreeLibrary(handle) -> void
+
+Free the handle of an executable previously loaded by LoadLibrary.
+"""
 
 else:
     def dlclose(handle: int, /) -> None:

crates/ty_vendored/vendor/typeshed/stdlib/_msi.pyi

@@ -1,3 +1,5 @@
+"""Documentation
+"""
 import sys
 from typing import Final, type_check_only
 
@@ -51,10 +53,32 @@ if sys.platform == "win32":
         __new__: None  # type: ignore[assignment]
         __init__: None  # type: ignore[assignment]
 
-    def UuidCreate() -> str: ...
-    def FCICreate(cabname: str, files: list[str], /) -> None: ...
-    def OpenDatabase(path: str, persist: int, /) -> _Database: ...
-    def CreateRecord(count: int, /) -> _Record: ...
+    def UuidCreate() -> str:
+        """Return the string representation of a new unique identifier.
+"""
+    def FCICreate(cabname: str, files: list[str], /) -> None:
+        """Create a new CAB file.
+
+  cabname
+    the name of the CAB file
+  files
+    a list of tuples, each containing the name of the file on disk,
+    and the name of the file inside the CAB file
+"""
+    def OpenDatabase(path: str, persist: int, /) -> _Database:
+        """Return a new database object.
+
+  path
+    the file name of the MSI file
+  persist
+    the persistence mode
+"""
+    def CreateRecord(count: int, /) -> _Record:
+        """Return a new record object.
+
+  count
+    the number of fields of the record
+"""
 
     MSICOLINFO_NAMES: Final[int]
     MSICOLINFO_TYPES: Final[int]

crates/ty_vendored/vendor/typeshed/stdlib/_socket.pyi

@@ -880,7 +880,14 @@ operations. A timeout of None indicates that timeouts on socket
 operations are disabled.
 """
     if sys.platform == "win32":
-        def ioctl(self, control: int, option: int | tuple[int, int, int] | bool, /) -> None: ...
+        def ioctl(self, control: int, option: int | tuple[int, int, int] | bool, /) -> None:
+            """ioctl(cmd, option) -> long
+
+Control the socket with WSAIoctl syscall. Currently supported 'cmd' values are
+SIO_RCVALL:  'option' must be one of the socket.RCVALL_* constants.
+SIO_KEEPALIVE_VALS:  'option' is a tuple of (onoff, timeout, interval).
+SIO_LOOPBACK_FAST_PATH: 'option' is a boolean value, and is disabled by default
+"""
 
     def listen(self, backlog: int = ..., /) -> None:
         """listen([backlog])
@@ -1070,7 +1077,14 @@ None, optlen.
     @overload
     def setsockopt(self, level: int, optname: int, value: None, optlen: int, /) -> None: ...
     if sys.platform == "win32":
-        def share(self, process_id: int, /) -> bytes: ...
+        def share(self, process_id: int, /) -> bytes:
+            """share(process_id) -> bytes
+
+Share the socket with another process.  The target process id
+must be provided and the resulting bytes object passed to the target
+process.  There the shared socket can be instantiated by calling
+socket.fromshare().
+"""
 
     def shutdown(self, how: int, /) -> None:
         """shutdown(flag)

crates/ty_vendored/vendor/typeshed/stdlib/_ssl.pyi

@@ -86,8 +86,23 @@ The values are 'cert_file_env', 'cert_file', 'cert_dir_env', 'cert_dir'.
 
 if sys.platform == "win32":
     _EnumRetType: TypeAlias = list[tuple[bytes, str, set[str] | bool]]
-    def enum_certificates(store_name: str) -> _EnumRetType: ...
-    def enum_crls(store_name: str) -> _EnumRetType: ...
+    def enum_certificates(store_name: str) -> _EnumRetType:
+        """Retrieve certificates from Windows' cert store.
+
+store_name may be one of 'CA', 'ROOT' or 'MY'.  The system may provide
+more cert storages, too.  The function returns a list of (bytes,
+encoding_type, trust) tuples.  The encoding_type flag can be interpreted
+with X509_ASN_ENCODING or PKCS_7_ASN_ENCODING. The trust setting is either
+a set of OIDs or the boolean True.
+"""
+    def enum_crls(store_name: str) -> _EnumRetType:
+        """Retrieve CRLs from Windows' cert store.
+
+store_name may be one of 'CA', 'ROOT' or 'MY'.  The system may provide
+more cert storages, too.  The function returns a list of (bytes,
+encoding_type) tuples.  The encoding_type flag can be interpreted with
+X509_ASN_ENCODING or PKCS_7_ASN_ENCODING.
+"""
 
 def txt2obj(txt: str, name: bool = False) -> tuple[int, str, str, str]:
     """Lookup NID, short name, long name and OID of an ASN1_OBJECT.

crates/ty_vendored/vendor/typeshed/stdlib/_winapi.pyi

@@ -175,7 +175,9 @@ if sys.platform == "win32":
     if sys.version_info >= (3, 14):
         COPY_FILE_DIRECTORY: Final = 0x00000080
 
-    def CloseHandle(handle: int, /) -> None: ...
+    def CloseHandle(handle: int, /) -> None:
+        """Close handle.
+"""
     @overload
     def ConnectNamedPipe(handle: int, overlapped: Literal[True]) -> Overlapped: ...
     @overload
@@ -204,7 +206,14 @@ if sys.platform == "win32":
         security_attributes: int,
         /,
     ) -> int: ...
-    def CreatePipe(pipe_attrs: Any, size: int, /) -> tuple[int, int]: ...
+    def CreatePipe(pipe_attrs: Any, size: int, /) -> tuple[int, int]:
+        """Create an anonymous pipe.
+
+  pipe_attrs
+    Ignored internally, can be None.
+
+Returns a 2-tuple of handles, to the read and write ends of the pipe.
+"""
     def CreateProcess(
         application_name: str | None,
         command_line: str | None,
@@ -216,7 +225,19 @@ if sys.platform == "win32":
         current_directory: str | None,
         startup_info: Any,
         /,
-    ) -> tuple[int, int, int, int]: ...
+    ) -> tuple[int, int, int, int]:
+        """Create a new process and its primary thread.
+
+  command_line
+    Can be str or None
+  proc_attrs
+    Ignored internally, can be None.
+  thread_attrs
+    Ignored internally, can be None.
+
+The return value is a tuple of the process handle, thread handle,
+process ID, and thread ID.
+"""
     def DuplicateHandle(
         source_process_handle: int,
         source_handle: int,
@@ -225,16 +246,46 @@ if sys.platform == "win32":
         inherit_handle: bool,
         options: int = 0,
         /,
-    ) -> int: ...
+    ) -> int:
+        """Return a duplicate handle object.
+
+The duplicate handle refers to the same object as the original
+handle. Therefore, any changes to the object are reflected
+through both handles.
+"""
     def ExitProcess(ExitCode: int, /) -> NoReturn: ...
-    def GetACP() -> int: ...
+    def GetACP() -> int:
+        """Get the current Windows ANSI code page identifier.
+"""
     def GetFileType(handle: int) -> int: ...
-    def GetCurrentProcess() -> int: ...
-    def GetExitCodeProcess(process: int, /) -> int: ...
+    def GetCurrentProcess() -> int:
+        """Return a handle object for the current process.
+"""
+    def GetExitCodeProcess(process: int, /) -> int:
+        """Return the termination status of the specified process.
+"""
     def GetLastError() -> int: ...
-    def GetModuleFileName(module_handle: int, /) -> str: ...
-    def GetStdHandle(std_handle: int, /) -> int: ...
-    def GetVersion() -> int: ...
+    def GetModuleFileName(module_handle: int, /) -> str:
+        """Return the fully-qualified path for the file that contains module.
+
+The module must have been loaded by the current process.
+
+The module parameter should be a handle to the loaded module
+whose path is being requested. If this parameter is 0,
+GetModuleFileName retrieves the path of the executable file
+of the current process.
+"""
+    def GetStdHandle(std_handle: int, /) -> int:
+        """Return a handle to the specified standard device.
+
+  std_handle
+    One of STD_INPUT_HANDLE, STD_OUTPUT_HANDLE, or STD_ERROR_HANDLE.
+
+The integer associated with the handle object is returned.
+"""
+    def GetVersion() -> int:
+        """Return the version number of the current operating system.
+"""
     def OpenProcess(desired_access: int, inherit_handle: bool, process_id: int, /) -> int: ...
     def PeekNamedPipe(handle: int, size: int = 0, /) -> tuple[int, int] | tuple[bytes, int, int]: ...
     if sys.version_info >= (3, 10):
@@ -250,9 +301,17 @@ if sys.platform == "win32":
     def SetNamedPipeHandleState(
         named_pipe: int, mode: int | None, max_collection_count: int | None, collect_data_timeout: int | None, /
     ) -> None: ...
-    def TerminateProcess(handle: int, exit_code: int, /) -> None: ...
+    def TerminateProcess(handle: int, exit_code: int, /) -> None:
+        """Terminate the specified process and all of its threads.
+"""
     def WaitForMultipleObjects(handle_seq: Sequence[int], wait_flag: bool, milliseconds: int = 0xFFFFFFFF, /) -> int: ...
-    def WaitForSingleObject(handle: int, milliseconds: int, /) -> int: ...
+    def WaitForSingleObject(handle: int, milliseconds: int, /) -> int:
+        """Wait for a single object.
+
+Wait until the specified object is in the signaled state or
+the time-out interval elapses. The timeout value is specified
+in milliseconds.
+"""
     def WaitNamedPipe(name: str, timeout: int, /) -> None: ...
     @overload
     def WriteFile(handle: int, buffer: ReadableBuffer, overlapped: Literal[True]) -> tuple[Overlapped, int]: ...
@@ -262,6 +321,8 @@ if sys.platform == "win32":
     def WriteFile(handle: int, buffer: ReadableBuffer, overlapped: int | bool) -> tuple[Any, int]: ...
     @final
     class Overlapped:
+        """OVERLAPPED structure wrapper
+"""
         event: int
         def GetOverlappedResult(self, wait: bool, /) -> tuple[int, int]: ...
         def cancel(self) -> None: ...
@@ -270,17 +331,54 @@ if sys.platform == "win32":
     if sys.version_info >= (3, 13):
         def BatchedWaitForMultipleObjects(
             handle_seq: Sequence[int], wait_all: bool, milliseconds: int = 0xFFFFFFFF
-        ) -> list[int]: ...
+        ) -> list[int]:
+            """Supports a larger number of handles than WaitForMultipleObjects
+
+Note that the handles may be waited on other threads, which could cause
+issues for objects like mutexes that become associated with the thread
+that was waiting for them. Objects may also be left signalled, even if
+the wait fails.
+
+It is recommended to use WaitForMultipleObjects whenever possible, and
+only switch to BatchedWaitForMultipleObjects for scenarios where you
+control all the handles involved, such as your own thread pool or
+files, and all wait objects are left unmodified by a wait (for example,
+manual reset events, threads, and files/pipes).
+
+Overlapped handles returned from this module use manual reset events.
+"""
         def CreateEventW(security_attributes: int, manual_reset: bool, initial_state: bool, name: str | None) -> int: ...
         def CreateMutexW(security_attributes: int, initial_owner: bool, name: str) -> int: ...
-        def GetLongPathName(path: str) -> str: ...
-        def GetShortPathName(path: str) -> str: ...
+        def GetLongPathName(path: str) -> str:
+            """Return the long version of the provided path.
+
+If the path is already in its long form, returns the same value.
+
+The path must already be a 'str'. If the type is not known, use
+os.fsdecode before calling this function.
+"""
+        def GetShortPathName(path: str) -> str:
+            """Return the short version of the provided path.
+
+If the path is already in its short form, returns the same value.
+
+The path must already be a 'str'. If the type is not known, use
+os.fsdecode before calling this function.
+"""
         def OpenEventW(desired_access: int, inherit_handle: bool, name: str) -> int: ...
         def OpenMutexW(desired_access: int, inherit_handle: bool, name: str) -> int: ...
         def ReleaseMutex(mutex: int) -> None: ...
         def ResetEvent(event: int) -> None: ...
         def SetEvent(event: int) -> None: ...
 
     if sys.version_info >= (3, 12):
-        def CopyFile2(existing_file_name: str, new_file_name: str, flags: int, progress_routine: int | None = None) -> int: ...
+        def CopyFile2(existing_file_name: str, new_file_name: str, flags: int, progress_routine: int | None = None) -> int:
+            """Copies a file from one name to a new name.
+
+This is implemented using the CopyFile2 API, which preserves all stat
+and metadata information apart from security attributes.
+
+progress_routine is reserved for future use, but is currently not
+implemented. Its value is ignored.
+"""
         def NeedCurrentDirectoryForExePath(exe_name: str, /) -> bool: ...