Add deprecation decorator and comments for pywin32 (#11570)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

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: _win32typing.PyIID,
+    FileId: tuple[int, int],
+    DesiredAccess,
+    ShareMode,
+    Flags,
+    SecurityAttributes: _win32typing.PySECURITY_ATTRIBUTES | None = ...,
+) -> int: ...
+@overload
+def OpenFileById(
+    File: int,
+    FileId: _win32typing.PyIID | int,
     DesiredAccess,
     ShareMode,
     Flags,

stubs/pywin32/win32/win32security.pyi

@@ -1,4 +1,6 @@
 from _typeshed import Incomplete
+from typing import overload
+from typing_extensions import deprecated
 
 import _win32typing
 from win32.lib.pywintypes import error as error
@@ -64,8 +66,12 @@ def SetNamedSecurityInfo(
 ) -> None: ...
 def GetNamedSecurityInfo(ObjectName: str, ObjectType: int, SecurityInfo: int, /) -> _win32typing.PySECURITY_DESCRIPTOR: ...
 def OpenProcessToken(processHandle, desiredAccess, /) -> int: ...
-def LookupPrivilegeValue(systemName: str, privilegeName: str, /) -> _win32typing.LARGE_INTEGER: ...
-def LookupPrivilegeName(SystemName: str, luid: _win32typing.LARGE_INTEGER, /) -> str: ...
+def LookupPrivilegeValue(systemName: str, privilegeName: str, /) -> int: ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def LookupPrivilegeName(SystemName: str, luid: tuple[int, int], /) -> str: ...
+@overload
+def LookupPrivilegeName(SystemName: str, luid: int, /) -> str: ...
 def LookupPrivilegeDisplayName(SystemName: str, Name: str, /) -> str: ...
 def AdjustTokenPrivileges(
     TokenHandle: int, bDisableAllPrivileges, NewState: _win32typing.PyTOKEN_PRIVILEGES
@@ -132,9 +138,19 @@ def LsaConnectUntrusted() -> _win32typing.PyLsaLogon_HANDLE: ...
 def LsaDeregisterLogonProcess(LsaHandle: _win32typing.PyLsaLogon_HANDLE, /) -> None: ...
 def LsaLookupAuthenticationPackage(LsaHandle: _win32typing.PyLsaLogon_HANDLE, PackageName: str, /): ...
 def LsaEnumerateLogonSessions() -> tuple[Incomplete, ...]: ...
-def LsaGetLogonSessionData(LogonId, /) -> tuple[Incomplete, ...]: ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def LsaGetLogonSessionData(LogonId: tuple[int, int], /) -> tuple[Incomplete, ...]: ...
+@overload
+def LsaGetLogonSessionData(LogonId: int, /) -> tuple[Incomplete, ...]: ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
 def AcquireCredentialsHandle(
-    Principal, Package, CredentialUse, LogonID, AuthData, /
+    Principal, Package, CredentialUse, LogonID: tuple[int, int], AuthData, /
+) -> tuple[_win32typing.PyCredHandle, _win32typing.PyTime]: ...
+@overload
+def AcquireCredentialsHandle(
+    Principal, Package, CredentialUse, LogonID: int | None, AuthData, /
 ) -> tuple[_win32typing.PyCredHandle, _win32typing.PyTime]: ...
 def InitializeSecurityContext(
     Credential: _win32typing.PyCredHandle,
@@ -158,6 +174,12 @@ def AcceptSecurityContext(
     /,
 ) -> tuple[Incomplete, Incomplete, Incomplete]: ...
 def QuerySecurityPackageInfo(PackageName, /): ...
+@overload
+@deprecated("Support for passing two ints to create a 64-bit value is deprecated; pass a single int instead")
+def LsaCallAuthenticationPackage(
+    LsaHandle: _win32typing.PyLsaLogon_HANDLE, AuthenticationPackage, MessageType, ProtocolSubmitBuffer: tuple[int, int], /
+) -> None: ...
+@overload
 def LsaCallAuthenticationPackage(
     LsaHandle: _win32typing.PyLsaLogon_HANDLE, AuthenticationPackage, MessageType, ProtocolSubmitBuffer, /
 ) -> None: ...

stubs/pywin32/win32/win32wnet.pyi

@@ -29,7 +29,8 @@ def WNetGetLastError() -> tuple[Incomplete, Incomplete, Incomplete]: ...
 def WNetGetResourceParent(NetResource: _win32typing.PyNETRESOURCE, /) -> _win32typing.PyNETRESOURCE: ...
 def WNetGetConnection(connection: str | None = ..., /) -> str: ...
 
-NCB = _win32typing.PyNCB
-NCBType = _win32typing.PyNCB
 NETRESOURCE = _win32typing.PyNETRESOURCE
+NCB = _win32typing.PyNCB
+# old "deprecated" names, before types could create instances.
 NETRESOURCEType = _win32typing.PyNETRESOURCE
+NCBType = _win32typing.PyNCB