Make pywin32_postinstall and pywin32_testall into Console Scripts

.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

@@ -1,4 +1,4 @@
-Notable changes in recent builds.
+Notable changes in recent builds.
 
 Maintained by hand, so what's "notable" is subjective! Contributors are
 encouraged to add entries for their work.
@@ -14,6 +14,9 @@ https://mhammond.github.io/pywin32_installers.html.
 Coming in build 309, as yet unreleased
 --------------------------------------
 
+* The postinstall script is now available as a console script. You can invoke it in one of two new methods:
+  1. `python -m pywin32_postinstall -install` (recommended)
+  2. `pywin32_postinstall -install` (shorter but you don't have control over which python environment is used)
 * 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)

README.md

@@ -49,18 +49,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
@@ -91,7 +95,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.

setup.py

@@ -2077,7 +2077,18 @@ def convert_optional_data_files(files):
     license="PSF",
     classifiers=classifiers,
     cmdclass=cmdclass,
-    scripts=["pywin32_postinstall.py", "pywin32_testall.py"],
+    # This adds the scripts under Python3XX/Scripts, but doesn't actually do much
+    scripts=[
+        "win32/scripts/pywin32_postinstall.py",
+        "win32/scripts/pywin32_testall.py",
+    ],
+    # This shortcuts `python -m win32.scripts.some_script` to just `some_script`
+    entry_points={
+        "console_scripts": [
+            "pywin32_postinstall = win32.scripts.pywin32_postinstall:main",
+            "pywin32_testall = win32.scripts.pywin32_testall:main",
+        ]
+    },
     ext_modules=ext_modules,
     package_dir={
         "win32com": "com/win32com",

pywin32_postinstall.py → win32/scripts/pywin32_postinstall.py

@@ -655,10 +655,11 @@ def main():
 
     * Typical usage:
 
-    > python pywin32_postinstall.py -install
+    > python -m pywin32_postinstall -install
 
-    This should be run automatically after installation,
-    but if it fails you can run it again.
+    * or (shorter but you don't have control over which python environment is used)
+
+    > pywin32_postinstall -install
 
     Given EXE installers are no longer provided,
     and wheel installs can't run postinstall scripts,

pywin32_testall.py → win32/scripts/pywin32_testall.py

@@ -7,10 +7,8 @@
 
 # locate the dirs based on where this script is - it may be either in the
 # source tree, or in an installed Python 'Scripts' tree.
-this_dir = os.path.dirname(__file__)
-site_packages = [
-    site.getusersitepackages(),
-] + site.getsitepackages()
+project_root = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+site_packages = [site.getusersitepackages()] + site.getsitepackages()
 
 failures = []
 
@@ -45,7 +43,7 @@ def find_and_run(possible_locations, extras):
 def main():
     import argparse
 
-    code_directories = [this_dir] + site_packages
+    code_directories = [project_root] + site_packages
 
     parser = argparse.ArgumentParser(
         description="A script to trigger tests in all subprojects of PyWin32."
@@ -89,10 +87,7 @@ def main():
     # win32com
     maybes = [
         os.path.join(directory, "win32com", "test", "testall.py")
-        for directory in [
-            os.path.join(this_dir, "com"),
-        ]
-        + site_packages
+        for directory in [os.path.join(project_root, "com")] + site_packages
     ]
     extras = remains + ["1"]  # only run "level 1" tests in CI
     find_and_run(maybes, extras)