Merge branch 'main' of https://github.com/mhammond/pywin32 into pywin32_postinstall-relative-path-support

Author: Avasam

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Typeshed type stubs and annotations
+    url: https://github.com/python/typeshed/issues?q=state%3Aopen+pywin32
+    about: For static type-checking and IntelliSense
   - name: python-win32 mailing list
     url: http://mail.python.org/mailman/listinfo/python-win32
     about: For support requests, problems or questions

.github/ISSUE_TEMPLATE/issue_template.md

@@ -4,7 +4,10 @@ about: Do not open github issues for general support requests
 ---
 
 <!--
-Note that issues in this repository are only for bugs or feature requests in the pywin32.
+Note that issues in this repository are only for bugs or feature requests in the pywin32 repository.
+
+Type stubs currently live in [typeshed](<https://github.com/python/typeshed/tree/main/stubs/pywin32>).
+Any issue or request related to static type-checking and IntelliSense should be raised there.
 
 **If you need support or help using this package, please follow [these instructions](https://github.com/mhammond/pywin32/blob/main/README.md#support)** - support or help requests will be closed without comment.
 -->

.github/workflows/main.yml

@@ -39,6 +39,14 @@ jobs:
           pip --version
           pip install --upgrade setuptools>=74 wheel
 
+      - name: Fix user Scripts missing from PATH
+        if: matrix.architecture == 'x86'
+        run: |
+          # Work around https://github.com/actions/setup-python/issues/1005
+          $ScriptsPath = python -c "import sysconfig,os; print(sysconfig.get_path('scripts', f'{os.name}_user'))"
+          echo $ScriptsPath
+          Add-Content $env:GITHUB_PATH $ScriptsPath
+
       - name: Build and install
         run: pip install . -v --user
 
@@ -49,18 +57,17 @@ jobs:
       - name: Generate PyWin32.chm help file
         run: python AutoDuck/make.py
 
-      # Smokescreen test to validate it doesn't crash and dlls can be found
+      # Smokescreen test to validate postinstall doesn't crash, dlls can be found, and both pathless invocation methods work
       - name: Run postinstall install/remove
         run: |
           $UserSite = "$(python -m site --user-site)"
-          cd "$UserSite/.."
-          python Scripts/pywin32_postinstall.py -install -destination "$UserSite"
-          python Scripts/pywin32_postinstall.py -remove -destination "$UserSite"
+          python -m win32.scripts.pywin32_postinstall -install -destination "$UserSite"
+          pywin32_postinstall -remove -destination "$UserSite"
 
       - name: Run tests
         # Run the tests directly from the source dir so support files (eg, .wav files etc)
         # can be found - they aren't installed into the Python tree.
-        run: python pywin32_testall.py -v -skip-adodbapi
+        run: python win32/scripts/pywin32_testall.py -v -skip-adodbapi
 
       - name: Build wheels
         run: pip wheel . -v --wheel-dir=dist

CHANGES.txt

@@ -15,7 +15,10 @@ Coming in build 309, as yet unreleased
 --------------------------------------
 
 * Added support for relative path for `pywin32_postinstall`'s `-destination` argument (#2454, @Avasam)
-* Changed the implementation of 'com_record' to a subclassable Python type (2437#, #2361, @geppi)
+* The postinstall script is now available as a console script. You can invoke it in one of two new methods: (#2408, @Avasam)
+  1. `python -m pywin32_postinstall -install` (recommended)
+  2. `pywin32_postinstall -install` (shorter but you don't have control over which python environment is used)
+* Changed the implementation of 'com_record' to a subclassable Python type (#2437, #2361, @geppi)
 * Removed param `hIcon` from `win32comext.shell.ShellExecuteEx`. It was unusable since Windows Vista (#2423, @Avasam)
 * Fixed `nbios.NCBStruct` packing (#2406, @Avasam)
 * Restored axdebug builds on Python 3.10 (#2416, @Avasam)

Pythonwin/win32view.cpp

@@ -839,8 +839,8 @@ static PyObject *ui_edit_window_save_file(PyObject *self, PyObject *args)
     CDocument *pDocument = pView->GetDocument();
     if (pDocument)
         pDocument->SetModifiedFlag(FALSE);  // start off with unmodified
-    PyWinObject_FreeTCHAR(fileName);
     GUI_END_SAVE;
+    PyWinObject_FreeTCHAR(fileName);
     RETURN_NONE;
 }
 // @pymethod tuple|PyCEditView|PreCreateWindow|Calls the underlying MFC PreCreateWindow method.

Pythonwin/win32win.cpp

@@ -1654,9 +1654,9 @@ static PyObject *ui_window_message_box(PyObject *self, PyObject *args)
     // @pyseemfc CWnd|MessageBox
 
     rc = pWnd->MessageBox(message, title, style);
+    GUI_END_SAVE;
     PyWinObject_FreeTCHAR(message);
     PyWinObject_FreeTCHAR(title);
-    GUI_END_SAVE;
     return Py_BuildValue("i", rc);
     // @rdesc An integer identifying the button pressed to dismiss the dialog.
 }

README.md

@@ -22,13 +22,18 @@ The docs are a long and sad story, but [there's now an online version](https://m
 of the `PyWin32.chm` helpfile (thanks [@ofek](https://github.com/mhammond/pywin32/pull/1774)!).
 Lots of that is very old, but some is auto-generated and current. Would love help untangling the docs!
 
+You can get type hints, signatures and annotations from [`types-pywin32`](https://pypi.org/project/types-pywin32/).
+
 ## Support
 
 Feel free to [open issues](https://github.com/mhammond/pywin32/issues) for
 all bugs (or suspected bugs) in pywin32. [pull-requests](https://github.com/mhammond/pywin32/pulls)
 for all bugs or features are also welcome.
 
-However, please **do not open github issues for general support requests**, or
+Type stubs currently live in [typeshed](<https://github.com/python/typeshed/tree/main/stubs/pywin32>).
+Any issue or request related to static type-checking and IntelliSense should be raised there.
+
+However, please **do not open GitHub issues for general support requests**, or
 for problems or questions using the modules in this package - they will be
 closed. For such issues, please email the
 [python-win32 mailing list](https://mail.python.org/mailman/listinfo/python-win32) -
@@ -53,18 +58,22 @@ There is a post-install script (see below) which should *not* be run inside virt
 it should only be run in "global" installs.
 
 For unreleased changes, you can download builds made by [github actions](https://github.com/mhammond/pywin32/actions/) -
-choose any "workflow" from the `main` branch and download its "artifacts")
+choose any "workflow" from the `main` branch and download its "artifacts"
 
 ### Installing globally
 
 Outside of a virtual environment you might want to install COM objects, services, etc. You can do
 this by executing:
 
 ```shell
-python Scripts/pywin32_postinstall.py -install
+python -m pywin32_postinstall -install
 ```
 
-From the root of your Python installation.
+or (shorter but you don't have control over which python environment is used)
+
+```shell
+pywin32_postinstall -install
+```
 
 If you do this with normal permissions it will be global for your user (a few files will be
 copied to the root of your Python install and some changes made to HKCU). If you execute this from
@@ -103,7 +112,13 @@ It usually means one of 2 things:
 So you should run it again:
 
     ```shell
-    python Scripts/pywin32_postinstall.py -install
+    python -m pywin32_postinstall -install
+    ```
+
+    or (shorter but you don't have control over which python environment is used)
+
+    ```shell
+    pywin32_postinstall -install
     ```
 
     This will make some small attempts to cleanup older conflicting installs.

com/win32com/client/CLSIDToClass.py

@@ -17,7 +17,9 @@
 Access.
 """
 
-mapCLSIDToClass = {}
+from __future__ import annotations
+
+mapCLSIDToClass: dict[str, type] = {}
 
 
 def RegisterCLSID(clsid, pythonClass):

com/win32com/client/__init__.py

@@ -5,6 +5,7 @@
 # Note that if the unknown dispatch object then returns a known
 # dispatch object, the known class will be used.  This contrasts
 # with dynamic.Dispatch behaviour, where dynamic objects are always used.
+from __future__ import annotations
 
 import sys
 from itertools import chain
@@ -263,7 +264,39 @@ def __setattr__(self, attr, val):
         setattr(self._obj_, attr, val)
 
 
-def DispatchWithEvents(clsid, user_event_class):
+def __get_disp_and_event_classes(dispatch):
+    # Create/Get the object.
+    disp = Dispatch(dispatch)
+
+    if disp.__class__.__dict__.get("CLSID"):
+        return disp.__class__
+
+    # Eeek - no makepy support - try and build it.
+    error_msg = "This COM object can not automate the makepy process - please run makepy manually for this object"
+    try:
+        ti = disp._oleobj_.GetTypeInfo()
+        disp_clsid = ti.GetTypeAttr()[0]
+        tlb, index = ti.GetContainingTypeLib()
+        tla = tlb.GetLibAttr()
+        gencache.EnsureModule(tla[0], tla[1], tla[3], tla[4], bValidateFile=0)
+        # Get the class from the module.
+        disp_class = gencache.GetClassForProgID(str(disp_clsid))
+    except pythoncom.com_error as error:
+        raise TypeError(error_msg) from error
+
+    if disp_class is None:
+        raise TypeError(error_msg)
+    # Get the clsid
+    clsid = disp_class.CLSID
+    # Create a new class that derives from 2 classes:
+    # the event sink class and the user class.
+    events_class = getevents(clsid)
+    if events_class is None:
+        raise ValueError("This COM object does not support events.")
+    return disp, disp_class, events_class
+
+
+def DispatchWithEvents(clsid, user_event_class) -> EventsProxy:
     """Create a COM object that can fire events to a user defined class.
     clsid -- The ProgID or CLSID of the object to create.
     user_event_class -- A Python class object that responds to the events.
@@ -302,39 +335,14 @@ class object that derives from three classes:
     Visible changed: 1
     >>>
     """
-    # Create/Get the object.
-    disp = Dispatch(clsid)
-    if not disp.__class__.__dict__.get(
-        "CLSID"
-    ):  # Eeek - no makepy support - try and build it.
-        try:
-            ti = disp._oleobj_.GetTypeInfo()
-            disp_clsid = ti.GetTypeAttr()[0]
-            tlb, index = ti.GetContainingTypeLib()
-            tla = tlb.GetLibAttr()
-            gencache.EnsureModule(tla[0], tla[1], tla[3], tla[4], bValidateFile=0)
-            # Get the class from the module.
-            disp_class = gencache.GetClassForProgID(str(disp_clsid))
-        except pythoncom.com_error:
-            raise TypeError(
-                "This COM object can not automate the makepy process - please run makepy manually for this object"
-            )
-    else:
-        disp_class = disp.__class__
-    # If the clsid was an object, get the clsid
-    clsid = disp_class.CLSID
-    # Create a new class that derives from 3 classes - the dispatch class, the event sink class and the user class.
-    events_class = getevents(clsid)
-    if events_class is None:
-        raise ValueError("This COM object does not support events.")
+    disp, disp_class, events_class = __get_disp_and_event_classes(clsid)
     result_class = type(
         "COMEventClass",
         (disp_class, events_class, user_event_class),
         {"__setattr__": _event_setattr_},
     )
-    instance = result_class(
-        disp._oleobj_
-    )  # This only calls the first base class __init__.
+    # This only calls the first base class __init__.
+    instance = result_class(disp._oleobj_)
     events_class.__init__(instance, instance)
     if hasattr(user_event_class, "__init__"):
         user_event_class.__init__(instance)
@@ -365,33 +373,14 @@ def WithEvents(disp, user_event_class):
     This is mainly useful where using DispatchWithEvents causes
     circular reference problems that the simple proxy doesn't deal with
     """
-    disp = Dispatch(disp)
-    if not disp.__class__.__dict__.get(
-        "CLSID"
-    ):  # Eeek - no makepy support - try and build it.
-        try:
-            ti = disp._oleobj_.GetTypeInfo()
-            disp_clsid = ti.GetTypeAttr()[0]
-            tlb, index = ti.GetContainingTypeLib()
-            tla = tlb.GetLibAttr()
-            gencache.EnsureModule(tla[0], tla[1], tla[3], tla[4], bValidateFile=0)
-            # Get the class from the module.
-            disp_class = gencache.GetClassForProgID(str(disp_clsid))
-        except pythoncom.com_error:
-            raise TypeError(
-                "This COM object can not automate the makepy process - please run makepy manually for this object"
-            )
-    else:
-        disp_class = disp.__class__
-    # Get the clsid
-    clsid = disp_class.CLSID
-    # Create a new class that derives from 2 classes - the event sink
-    # class and the user class.
-    events_class = getevents(clsid)
-    if events_class is None:
-        raise ValueError("This COM object does not support events.")
-    result_class = type("COMEventClass", (events_class, user_event_class), {})
-    instance = result_class(disp)  # This only calls the first base class __init__.
+    disp, disp_class, events_class = __get_disp_and_event_classes(disp)
+    result_class = type(
+        "COMEventClass",
+        (events_class, user_event_class),
+        {},
+    )
+    # This only calls the first base class __init__.
+    instance = result_class(disp)
     if hasattr(user_event_class, "__init__"):
         user_event_class.__init__(instance)
     return instance

com/win32com/src/extensions/PyIType.cpp

@@ -688,8 +688,8 @@ PyObject *pythoncom_loadtypelib(PyObject *self, PyObject *args)
     ITypeLib *ptl;
     PY_INTERFACE_PRECALL;
     SCODE sc = LoadTypeLib(bstrName, &ptl);
-    PyWinObject_FreeBstr(bstrName);
     PY_INTERFACE_POSTCALL;
+    PyWinObject_FreeBstr(bstrName);
     if (FAILED(sc))
         return PyCom_BuildPyException(sc);
 

com/win32comext/bits/src/PyIBackgroundCopyJob.cpp

@@ -620,9 +620,9 @@ PyObject *PyIBackgroundCopyJob::SetProxySettings(PyObject *self, PyObject *args)
     HRESULT hr;
     PY_INTERFACE_PRECALL;
     hr = pIBCJ->SetProxySettings(ProxyUsage, ProxyList, ProxyBypassList);
+    PY_INTERFACE_POSTCALL;
     PyWinObject_FreeWCHAR(ProxyList);
     PyWinObject_FreeWCHAR(ProxyBypassList);
-    PY_INTERFACE_POSTCALL;
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pIBCJ, IID_IBackgroundCopyJob);
     Py_INCREF(Py_None);

com/win32comext/internet/src/PyIDocHostUIHandler.cpp

@@ -376,8 +376,8 @@ PyObject *PyIDocHostUIHandler::TranslateUrl(PyObject *self, PyObject *args)
     HRESULT hr;
     PY_INTERFACE_PRECALL;
     hr = pIDHUIH->TranslateUrl(dwTranslate, pchURLIn, &pchURLOut);
-    PyWinObject_FreeWCHAR(pchURLIn);
     PY_INTERFACE_POSTCALL;
+    PyWinObject_FreeWCHAR(pchURLIn);
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pIDHUIH, IID_IDocHostUIHandler);
     PyObject *pyretval = MakeOLECHARToObj(pchURLOut);

com/win32comext/internet/src/PyIInternetSecurityManager.cpp

@@ -145,8 +145,8 @@ PyObject *PyIInternetSecurityManager::ProcessUrlAction(PyObject *self, PyObject
     PY_INTERFACE_PRECALL;
     hr = pIISM->ProcessUrlAction(pwszUrl, dwAction, (BYTE *)&dwPolicy, sizeof(dwPolicy), (BYTE *)context, cbcontext,
                                  dwFlags, 0);
-    PyWinObject_FreeWCHAR(pwszUrl);
     PY_INTERFACE_POSTCALL;
+    PyWinObject_FreeWCHAR(pwszUrl);
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pIISM, IID_IInternetSecurityManager);
     return Py_BuildValue("ll", hr, dwPolicy);

com/win32comext/shell/src/PyICopyHook.cpp

@@ -54,11 +54,10 @@ PyObject *PyICopyHookA::CopyCallback(PyObject *self, PyObject *args)
     HRESULT hr;
     PY_INTERFACE_PRECALL;
     hr = pICH->CopyCallback(hwnd, wFunc, wFlags, srcFile, srcAttribs, destFile, destAttribs);
+    PY_INTERFACE_POSTCALL;
     PyWinObject_FreeChars(srcFile);
     PyWinObject_FreeChars(destFile);
 
-    PY_INTERFACE_POSTCALL;
-
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pICH, IID_IShellCopyHook);
     Py_INCREF(Py_None);
@@ -143,10 +142,10 @@ PyObject *PyICopyHookW::CopyCallback(PyObject *self, PyObject *args)
     HRESULT hr;
     PY_INTERFACE_PRECALL;
     hr = pICH->CopyCallback(hwnd, wFunc, wFlags, srcFile, srcAttribs, destFile, destAttribs);
-    PyWinObject_FreeWCHAR(srcFile);
-    PyWinObject_FreeWCHAR(destFile);
 
     PY_INTERFACE_POSTCALL;
+    PyWinObject_FreeWCHAR(srcFile);
+    PyWinObject_FreeWCHAR(destFile);
 
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pICH, IID_IShellCopyHook);

com/win32comext/shell/src/PyIExtractIcon.cpp

@@ -38,8 +38,9 @@ PyObject *PyIExtractIcon::Extract(PyObject *self, PyObject *args)
     HRESULT hr;
     PY_INTERFACE_PRECALL;
     hr = pIEI->Extract(pszFile, nIconIndex, &hiconLarge, &hiconSmall, nIconSize);
-    PyWinObject_FreeChars(pszFile);
     PY_INTERFACE_POSTCALL;
+    PyWinObject_FreeChars(pszFile);
+
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pIEI, IID_IExtractIcon);
     if (hr == S_FALSE)

com/win32comext/shell/src/PyIExtractIconW.cpp

@@ -42,8 +42,9 @@ PyObject *PyIExtractIconW::Extract(PyObject *self, PyObject *args)
     HRESULT hr;
     PY_INTERFACE_PRECALL;
     hr = pIEI->Extract(pszFile, nIconIndex, &hiconLarge, &hiconSmall, nIconSize);
-    PyWinObject_FreeWCHAR(pszFile);
     PY_INTERFACE_POSTCALL;
+    PyWinObject_FreeWCHAR(pszFile);
+
     if (FAILED(hr))
         return PyCom_BuildPyException(hr, pIEI, IID_IExtractIconW);
     if (hr == S_FALSE)