Add deprecation decorator and comments for pywin32 (#11570)

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: Avasam

stubs/pywin32/@tests/stubtest_allowlist_win32.txt

@@ -48,11 +48,8 @@ win32com(ext)?.axscript.client.debug
 win32com(ext)?.axscript.client.pydumper
 win32com(ext)?.directsound.test.*
 
-# Deprecated and obsolete
-pythoncom.MakeIID
-pythoncom.MakeTime
-(win32.lib.)?win32pdhquery.Query.addperfcounter
 # Deprecated and makes a buffer of random junk. Use something like `b"\x00" * bufferSize` instead
+# It's safer to not even expose this method as deprecated.
 (win32.)?win(32|xp)gui.PyMakeBuffer
 
 # Axdebug is not built on Python 3.11 anyway: https://github.com/mhammond/pywin32/blob/main/setup.py#L403-L405

stubs/pywin32/_win32typing.pyi

@@ -2,7 +2,7 @@
 from _typeshed import Incomplete, Unused
 from collections.abc import Iterable
 from typing import Literal, final, overload
-from typing_extensions import Self
+from typing_extensions import Self, TypeAlias, deprecated
 
 class ArgNotFound: ...
 class PyOleEmpty: ...
@@ -123,7 +123,12 @@ class FORM_INFO_1:
     def ImageableArea(self): ...
 
 class ImportCallback: ...
-class LARGE_INTEGER: ...
+
+# Note: Don't use these, use `int` instead. Or an overload with a deprecation message on the tuple param.
+# We're only keeping these here as a reminder when typing from source code.
+# Deprecated: Support for passing 2 integers to create a 64bit value is deprecated - pass a long instead
+LARGE_INTEGER: TypeAlias = int | tuple[int, int]
+ULARGE_INTEGER: TypeAlias = int | tuple[int, int]
 
 class NCB:
     @property
@@ -164,6 +169,12 @@ class PRINTER_DEFAULTS:
 class PyACL:
     def Initialize(self) -> None: ...
     def IsValid(self) -> bool: ...
+    @deprecated(
+        """\
+Early versions of this function supported only two arguments. \
+This has been deprecated in preference of the three argument version, \
+which reflects the win32 API and the new functions in this module."""
+    )
     @overload
     def AddAccessAllowedAce(self, access: int, sid: PySID, /) -> None: ...
     @overload
@@ -172,7 +183,16 @@ class PyACL:
     def AddAccessAllowedObjectAce(
         self, AceRevision, AceFlags, AccessMask, ObjectTypeGuid: PyIID, InheritedObjectTypeGuid: PyIID, sid: PySID, /
     ) -> None: ...
-    def AddAccessDeniedAce(self, revision: int, access: int, sid: PySID, access1: int, sid1: PySID, /) -> None: ...
+    @deprecated(
+        """\
+Early versions of this function supported only two arguments. \
+This has been deprecated in preference of the three argument version, \
+which reflects the win32 API and the new functions in this module."""
+    )
+    @overload
+    def AddAccessDeniedAce(self, access: int, sid: PySID, /) -> None: ...
+    @overload
+    def AddAccessDeniedAce(self, revision: int, access: int, sid: PySID, /) -> None: ...
     def AddAccessDeniedAceEx(self, revision: int, aceflags: int, access: int, sid: PySID, /) -> None: ...
     def AddMandatoryAce(self, AceRevision, AceFlags, MandatoryPolicy, LabelSid: PySID, /) -> None: ...
     def AddAuditAccessAce(self, dwAceRevision, dwAccessMask, sid: PySID, bAuditSuccess, bAuditFailure, /) -> None: ...
@@ -217,10 +237,17 @@ class PyCEHANDLE: ...
 class PyCERTSTORE:
     @property
     def HCERTSTORE(self): ...
-    # Flags argument is deprecated.
-    # The underlying function is now always called with `CERT_CLOSE_STORE_CHECK_FLAG`,
-    # and support for this param will be dropped at some point in the future.
-    def CertCloseStore(self, Flags: int = ...) -> None: ...
+    @overload
+    def CertCloseStore(self) -> None: ...
+    @deprecated(
+        """\
+`Flags` argument has been deprecated as it is likely to crash the process if \
+`CERT_CLOSE_STORE_FORCE_FLAG` is specified. The underlying function is now \
+always called with `CERT_CLOSE_STORE_CHECK_FLAG`, and support for this \
+param will be dropped at some point in the future."""
+    )
+    @overload
+    def CertCloseStore(self, Flags: int) -> None: ...
     def CertControlStore(self, Flags, CtrlType, CtrlPara: int) -> None: ...
     def CertEnumCertificatesInStore(self) -> list[PyCERT_CONTEXT]: ...
     def CertEnumCTLsInStore(self) -> list[PyCTL_CONTEXT]: ...
@@ -2403,7 +2430,6 @@ class SERVICE_STATUS:
     def __getitem__(self, i: int, /) -> int: ...
 
 class TRACKMOUSEEVENT: ...
-class ULARGE_INTEGER: ...
 class WIN32_FIND_DATA: ...
 class com_error: ...
 
@@ -3682,7 +3708,11 @@ class PyIInternetPriority:
 
 class PyIInternetProtocol:
     def Read(self, cb, /) -> None: ...
-    def Seek(self, dlibMove: LARGE_INTEGER, dwOrigin, /) -> None: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def Seek(self, dlibMove: tuple[int, int], dwOrigin, /) -> None: ...
+    @overload
+    def Seek(self, dlibMove: int, dwOrigin, /) -> None: ...
     def LockRequest(self, dwOptions, /) -> None: ...
     def UnlockRequest(self) -> None: ...
 
@@ -3741,13 +3771,32 @@ class PyIKnownFolderManager:
     def Redirect(self, _id: PyIID, hwnd: int, flags, TargetPath, Exclusion: tuple[PyIID, ...], /) -> None: ...
 
 class PyILockBytes:
-    def ReadAt(self, ulOffset: ULARGE_INTEGER, cb, /) -> str: ...
-    def WriteAt(self, ulOffset: ULARGE_INTEGER, data: str, /): ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def ReadAt(self, ulOffset: tuple[int, int], cb, /) -> str: ...
+    @overload
+    def ReadAt(self, ulOffset: int, cb, /) -> str: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def WriteAt(self, ulOffset: tuple[int, int], data: str, /): ...
+    @overload
+    def WriteAt(self, ulOffset: int, data: str, /): ...
     def Flush(self) -> None: ...
-    def SetSize(self, cb: ULARGE_INTEGER, /) -> None: ...
-    def LockRegion(self, libOffset: ULARGE_INTEGER, cb: ULARGE_INTEGER, dwLockType, /) -> None: ...
-    def UnlockRegion(self, libOffset: ULARGE_INTEGER, cb: ULARGE_INTEGER, dwLockType, /) -> None: ...
-    def Stat(self, grfStatFlag, /) -> STATSTG: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def SetSize(self, cb: tuple[int, int], /) -> None: ...
+    @overload
+    def SetSize(self, cb: int, /) -> None: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def LockRegion(self, libOffset: tuple[int, int], cb: tuple[int, int], dwLockType, /) -> None: ...
+    @overload
+    def LockRegion(self, libOffset: int, cb: int, dwLockType, /) -> None: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def UnlockRegion(self, libOffset: tuple[int, int], cb: tuple[int, int], dwLockType, /) -> None: ...
+    @overload
+    def UnlockRegion(self, libOffset: int, cb: int, dwLockType, /) -> None: ...
 
 class PyIMAPIContainer:
     def OpenEntry(self, entryId: str, iid: PyIID, flags, /): ...
@@ -3882,6 +3931,7 @@ class PyIMsgServiceAdmin:
     def GetMsgServiceTable(self, flags, /) -> PyIMAPITable: ...
     def GetProviderTable(self, flags, /) -> PyIMAPITable: ...
     def DeleteMsgService(self, uuid: PyIID, /) -> None: ...
+    @deprecated("This is deprecated, and there is no replacement referenced to use instead.")
     def RenameMsgService(self, uuid: PyIID, flags, newName: str, /) -> None: ...
     def OpenProfileSection(self, uuid: PyIID, iid: PyIID, flags, /): ...
     def AdminProviders(self, uuid: PyIID, flags, /): ...
@@ -4104,7 +4154,7 @@ class PyIPersistStream:
     def IsDirty(self) -> bool: ...
     def Load(self, stream: PyIStream, /) -> None: ...
     def Save(self, stream: PyIStream, bClearDirty, /) -> None: ...
-    def GetSizeMax(self) -> ULARGE_INTEGER: ...
+    def GetSizeMax(self) -> int: ...
 
 class PyIPersistStreamInit:
     def InitNew(self) -> None: ...
@@ -4539,13 +4589,33 @@ class PyIStream:
     def read(self, numBytes, /) -> str: ...
     def Write(self, data: str, /) -> None: ...
     def write(self, data: str, /) -> None: ...
-    def Seek(self, offset, origin, /) -> ULARGE_INTEGER: ...
-    def SetSize(self, newSize: ULARGE_INTEGER, /) -> None: ...
-    def CopyTo(self, stream: PyIStream, cb: ULARGE_INTEGER, /) -> ULARGE_INTEGER: ...
+    @overload
+    def Seek(self, offset: int, origin: int, /) -> int: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def Seek(self, offset: tuple[int, int], origin: int, /) -> int: ...
+    @overload
+    def SetSize(self, newSize: int, /) -> None: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def SetSize(self, newSize: tuple[int, int], /) -> None: ...
+    @overload
+    def CopyTo(self, stream: PyIStream, cb: int, /) -> int: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def CopyTo(self, stream: PyIStream, cb: tuple[int, int], /) -> int: ...
     def Commit(self, flags, /) -> None: ...
     def Revert(self) -> None: ...
-    def LockRegion(self, offset: ULARGE_INTEGER, cb: ULARGE_INTEGER, lockType, /) -> None: ...
-    def UnLockRegion(self, offset: ULARGE_INTEGER, cb: ULARGE_INTEGER, lockType, /) -> None: ...
+    @overload
+    def LockRegion(self, offset: int, cb: int, lockType, /) -> None: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def LockRegion(self, offset: tuple[int, int], cb: tuple[int, int], lockType, /) -> None: ...
+    @overload
+    def UnLockRegion(self, offset: int, cb: int, lockType, /) -> None: ...
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def UnLockRegion(self, offset: tuple[int, int], cb: tuple[int, int], lockType, /) -> None: ...
     def Clone(self) -> PyIStream: ...
     def Stat(self, grfStatFlag: int = ..., /) -> STATSTG: ...
 
@@ -4682,6 +4752,10 @@ class PyPROPERTYKEY: ...
 
 @final
 class PyPROPVARIANT:
+    @overload
+    @deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+    def __init__(self, Value: tuple[int, int], Type=...) -> None: ...
+    @overload
     def __init__(self, Value, Type=...) -> None: ...
     @property
     def vt(self): ...

stubs/pywin32/pythoncom.pyi

@@ -1,5 +1,5 @@
 from _typeshed import Incomplete
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, deprecated
 
 import _win32typing
 from win32.lib.pywintypes import com_error as com_error
@@ -69,6 +69,10 @@ def IsGatewayRegistered(iid: _win32typing.PyIID | None, /) -> int: ...
 def LoadRegTypeLib(iid: _win32typing.PyIID, versionMajor, versionMinor, lcid, /) -> _win32typing.PyITypeLib: ...
 def LoadTypeLib(libFileName: str, /) -> _win32typing.PyITypeLib: ...
 def MakePyFactory(iid: _win32typing.PyIID, /) -> _win32typing.PyIClassFactory: ...
+@deprecated("Use pywintypes.IID() instead.")
+def MakeIID(iidString: str, is_bytes: bool = ..., /) -> _win32typing.PyIID: ...
+@deprecated("Use pywintypes.Time() instead.")
+def MakeTime(timeRepr, /) -> _win32typing.PyTime: ...
 def MkParseDisplayName(
     displayName: str, bindCtx: _win32typing.PyIBindCtx | None = ..., /
 ) -> tuple[_win32typing.PyIMoniker, Incomplete, _win32typing.PyIBindCtx]: ...

stubs/pywin32/win32/lib/pywintypes.pyi

@@ -2,8 +2,8 @@
 # "KeyError: 'pywintypes'"
 from _typeshed import Incomplete
 from datetime import datetime
-from typing import Literal, NoReturn
-from typing_extensions import Never
+from typing import Literal, NoReturn, overload
+from typing_extensions import Never, deprecated
 
 import _win32typing
 
@@ -45,7 +45,11 @@ def SECURITY_DESCRIPTOR() -> _win32typing.PySECURITY_DESCRIPTOR: ...
 def HANDLE() -> HANDLEType: ...
 def HKEY() -> _win32typing.PyHKEY: ...
 def WAVEFORMATEX() -> _win32typing.PyWAVEFORMATEX: ...
-def TimeStamp(*args): ...  # incomplete
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def TimeStamp(timestamp: tuple[int, int], /) -> TimeType: ...
+@overload
+def TimeStamp(timestamp: int, /) -> TimeType: ...
 
 FALSE: Literal[False]
 TRUE: Literal[True]

stubs/pywin32/win32/lib/win32pdhquery.pyi

@@ -1,4 +1,5 @@
 from _typeshed import Incomplete
+from typing_extensions import deprecated
 
 class BaseQuery:
     counters: Incomplete
@@ -24,6 +25,8 @@ class BaseQuery:
 class Query(BaseQuery):
     volatilecounters: Incomplete
     def __init__(self, *args, **namedargs) -> None: ...
+    @deprecated("Use `addcounterbybrowsing` instead.")
+    def addperfcounter(self, object, counter, machine=None): ...
     def addinstcounter(
         self, object, counter, machine: Incomplete | None = ..., objtype: str = ..., volatile: int = ..., format=...
     ) -> None: ...

stubs/pywin32/win32/win32api.pyi

@@ -1,6 +1,7 @@
 from _typeshed import Incomplete, ReadableBuffer
 from collections.abc import Callable, Iterable
 from typing import TypedDict
+from typing_extensions import deprecated
 
 import _win32typing
 from win32.lib.pywintypes import error as error
@@ -111,8 +112,10 @@ def GetModuleFileName(hModule: int, /) -> str: ...
 def GetModuleFileNameW(hModule: int, /) -> str: ...
 def GetModuleHandle(fileName: str | None = ..., /) -> int: ...
 def GetPwrCapabilities(): ...
+@deprecated("This function is obsolete, applications should use the registry instead.")
 def GetProfileSection(section: str, iniName: str | None = ..., /): ...
 def GetProcAddress(hModule: int, functionName: _win32typing.PyResourceId, /): ...
+@deprecated("This function is obsolete, applications should use the registry instead.")
 def GetProfileVal(section: str, entry: str, defValue: str, iniName: str | None = ..., /) -> str: ...
 def GetShortPathName(path: str, /) -> str: ...
 def GetStdHandle(handle: int, /) -> _win32typing.PyHANDLE: ...
@@ -223,6 +226,7 @@ def SetSysColors(Elements, RgbValues, /) -> None: ...
 def SetLocalTime(SystemTime: _win32typing.PyTime, /) -> None: ...
 def SetSystemTime(year, month, dayOfWeek, day, hour, minute, second, millseconds, /): ...
 def SetClassLong(hwnd: int, offset, val, /): ...
+@deprecated("This function is obsolete, use `win32api.SetClassLong` instead")
 def SetClassWord(hwnd: int, offset, val, /): ...
 def SetCursor(hCursor: int, /) -> int: ...
 def SetEnvironmentVariable(Name, Value, /) -> None: ...
@@ -233,6 +237,11 @@ def SetSystemPowerState(Suspend, Force, /) -> None: ...
 def SetThreadLocale(lcid, /) -> None: ...
 def SetTimeZoneInformation(tzi, /): ...
 def SetWindowLong(hwnd: int | None, offset: int, value: float, /) -> int: ...
+
+# This method is accidentally overwritten in source, can re-introduce once fixed:
+# https://github.com/mhammond/pywin32/pull/2199
+# @deprecated("This function is obsolete, use `win32api.SetWindowLong` instead")
+# def SetWindowWord(hwnd, offset: int, val: int) -> int: ...
 def ShellExecute(hwnd: int, op: str, file: str, params: str, _dir: str, bShow, /): ...
 def ShowCursor(show, /): ...
 def Sleep(time, bAlterable: int = ..., /): ...
@@ -250,7 +259,9 @@ def UpdateResource(
 def VkKeyScan(char, char1, /): ...
 def WinExec(cmdLine: str, arg, /) -> None: ...
 def WinHelp(hwnd: int, hlpFile: str, cmd, data: str | int = ..., /) -> None: ...
+@deprecated("This function is obsolete, applications should use the registry instead.")
 def WriteProfileSection(section: str, data: str, iniName: str | None = ..., /): ...
+@deprecated("This function is obsolete, applications should use the registry instead.")
 def WriteProfileVal(section: str, entry: str, value: str, iniName: str | None = ..., /) -> None: ...
 def HIBYTE(val: int, /) -> int: ...
 def LOBYTE(val: int, /) -> int: ...

stubs/pywin32/win32/win32file.pyi

@@ -1,6 +1,7 @@
 from _typeshed import Incomplete
 from socket import socket
 from typing import overload
+from typing_extensions import deprecated
 
 import _win32typing
 from win32.lib.pywintypes import error as error
@@ -90,7 +91,11 @@ def SetEndOfFile(hFile: int, /) -> None: ...
 def SetFileApisToANSI() -> None: ...
 def SetFileApisToOEM() -> None: ...
 def SetFileAttributes(filename: str, newAttributes: int, /) -> None: ...
-def SetFilePointer(handle: int, offset, moveMethod, /) -> None: ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def SetFilePointer(handle: int, offset: tuple[int, int], moveMethod, /) -> None: ...
+@overload
+def SetFilePointer(handle: int, offset: int, moveMethod, /) -> None: ...
 def SetVolumeLabel(rootPathName: str, volumeName: str, /) -> None: ...
 def UnlockFile(hFile: int, offsetLow, offsetHigh, nNumberOfBytesToUnlockLow, nNumberOfBytesToUnlockHigh, /) -> None: ...
 def TransmitFile(
@@ -162,7 +167,11 @@ def DuplicateEncryptionInfoFile(
 def BackupRead(
     hFile: int, NumberOfBytesToRead, Buffer, bAbort, bProcessSecurity, lpContext, /
 ) -> tuple[Incomplete, Incomplete, Incomplete]: ...
-def BackupSeek(hFile: int, NumberOfBytesToSeek, lpContext, /): ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def BackupSeek(hFile: int, NumberOfBytesToSeek: tuple[int, int], lpContext, /): ...
+@overload
+def BackupSeek(hFile: int, NumberOfBytesToSeek: int, lpContext, /): ...
 def BackupWrite(
     hFile: int, NumberOfBytesToWrite, Buffer: str, bAbort, bProcessSecurity, lpContext, /
 ) -> tuple[Incomplete, Incomplete]: ...
@@ -233,11 +242,26 @@ def GetFullPathName(FileName, Transaction: int | None = ...): ...
 def Wow64DisableWow64FsRedirection(): ...
 def Wow64RevertWow64FsRedirection(OldValue, /) -> None: ...
 def GetFileInformationByHandleEx(File: int, FileInformationClass): ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def SetFileInformationByHandle(File: int, FileInformationClass, Information: tuple[int, int]) -> None: ...
+@overload
 def SetFileInformationByHandle(File: int, FileInformationClass, Information) -> None: ...
 def ReOpenFile(OriginalFile: int, DesiredAccess, ShareMode, Flags) -> int: ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def OpenFileById(
+    File: int,
+    FileId: tuple[int, int],
+    DesiredAccess,
+    ShareMode,
+    Flags,
+    SecurityAttributes: _win32typing.PySECURITY_ATTRIBUTES | None = ...,
+) -> int: ...
+@overload
 def OpenFileById(
     File: int,
-    FileId: _win32typing.PyIID,
+    FileId: _win32typing.PyIID | int,
     DesiredAccess,
     ShareMode,
     Flags,