Merge branch 'main' into add-test-for-postinstall

.editorconfig

@@ -9,7 +9,7 @@ indent_size = 4
 max_line_length = 120 # Same as .clang-format
 
 [*.py]
-max_line_length = 88 # Same as Black
+max_line_length = 88 # Same as Ruff's default
 
 [*.md]
 trim_trailing_whitespace = false

.git-blame-ignore-revs

@@ -13,3 +13,6 @@
 
 # 2024-05-28 formatted c++ source with clang-format
 637448f8252ab142eedd539ddf9b08259b73eecc
+
+# 2024-10-14 formatted Python source with Ruff format
+2b5191d8fc6f1d1fbde01481b49278c1957ef8f1

.github/issue_template.md

@@ -9,7 +9,7 @@ For all bugs, please provide the following information:
 ## Expected behavior and actual behavior
 
 ## Steps to reproduce the problem
-<!-- Prefer using code snippets rather than a screenshot. Please include a full minimal reproduction if possible. -->
+<!-- Prefer using code snippets rather than a screenshot. Please include a [full minimal reproduction](https://stackoverflow.com/help/minimal-reproducible-example) if possible. -->
 
 1. ...
 2. ...

.github/workflows/docs.yml

@@ -3,15 +3,18 @@ name: docs
 on:
   create:
     tags:
-    # https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
+      # https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
       - b[0-9][0-9][0-9]
       - publish-docs*
   push:
     branches:
       - main
+  pull_request: # Temporary just for test
+    branches:
+      - main
 
 jobs:
-  decompile:
+  generate:
     runs-on: windows-latest
 
     steps:
@@ -22,44 +25,43 @@ jobs:
         with:
           python-version: '3.9'
 
+      # We still need to install pywin32 because
+      # AutoDuck/py2d.py currently relies on runtime imports for introspection
+      # Downloading latest release is faster than re-building
       - name: Install latest release
         run: pip install --user --upgrade pywin32
 
-      - name: Set Python user site directory
-        run: python -c "import os,site;open(os.environ['GITHUB_ENV'], 'a').write(f'USER_DIR={site.USER_SITE}\n')"
+      - name: Generate PyWin32.chm help file
+        run: python AutoDuck/make.py
 
-      - name: Decompile shipped help file
-        run: hh -decompile site ${env:USER_DIR}\PyWin32.chm
+      - name: Decompile help file into HTML
+        run: hh -decompile site PyWin32.chm
 
       - name: Rename root HTML file
         run: mv site\PyWin32.HTML site\index.html
 
-    # Compress first to avoid slowly uploading thousands of individual files
-      - name: Create archive
-        run: python -m zipfile -c site.zip site
-
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: documentation
-          path: site.zip
+          path: site/
 
   publish:
     runs-on: ubuntu-latest
     needs:
-      - decompile
+      - generate
 
     # Only publish tags
     if: github.event_name == 'create' && github.event.ref_type == 'tag'
 
     steps:
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         with:
           name: documentation
 
       - name: Unpack archive
         run: python -m zipfile -e site.zip .
 
-      - uses: peaceiris/actions-gh-pages@v3
+      - uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: site

.github/workflows/download-arm64-libs.py

@@ -28,16 +28,16 @@
     VERSION += f"-rc{sys.version_info.serial}"
 
 URL = f"https://www.nuget.org/api/v2/package/pythonarm64/{VERSION}"
-PATH = dest / f"pythonarm64.{VERSION}.zip"
+DEST_PATH = dest / f"pythonarm64.{VERSION}.zip"
 
-if PATH.is_file():
-    print("Skipping download because", PATH, "exists")
+if DEST_PATH.is_file():
+    print("Skipping download because", DEST_PATH, "exists")
 else:
     print("Downloading", URL)
-    urlretrieve(URL, PATH)
-    print("Downloaded", PATH)
+    urlretrieve(URL, DEST_PATH)
+    print("Downloaded", DEST_PATH)
 
-with ZipFile(PATH, "r") as zf:
+with ZipFile(DEST_PATH, "r") as zf:
     for name in zf.namelist():
         zip_path = pathlib.PurePath(name)
         if zip_path.parts[:2] == ("tools", "libs"):

.github/workflows/main.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13-dev"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13-dev"]
         architecture: ["x64", "x86"]
 
     steps:
@@ -37,13 +37,21 @@ jobs:
         run: |
           python --version
           pip --version
-          pip install --upgrade setuptools wheel
+          pip install --upgrade setuptools>=74 wheel
 
       - name: Build and install
         run: |
           python setup.py install --user
-
-      - name: Run postinstall install/remove # Smokescreen test to validate it doesn't crash
+          
+      # This needs to happen *after* installing pywin32 since
+      # AutoDuck/py2d.py currently relies on runtime imports for introspection
+      # This isn't included in the wheel (TODO: could we?)
+      # and only servces as a PR test for the docs.yaml workflow
+      - name: Generate PyWin32.chm help file
+        run: python AutoDuck/make.py
+
+      # Smokescreen test to validate it doesn't crash
+      - name: Run postinstall install/remove
         run: |
           cd "$(python -m site --user-site)/.."
           python Scripts/pywin32_postinstall.py -install
@@ -92,7 +100,7 @@ jobs:
         run: |
           python --version
           pip --version
-          pip install --upgrade setuptools wheel
+          pip install --upgrade setuptools>=74 wheel
 
       - name: Obtain ARM64 library files
         run: |
@@ -116,31 +124,29 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          # This job only needs to target the oldest version supported by our checkers
-          # (black>=24.10.0 supports Python >=3.9)
-          python-version: "3.9"
+          # This job only needs to target the oldest supported version
+          python-version: "3.8"
           cache: pip
           cache-dependency-path: .github/workflows/main.yml
       - run: pip install clang-format pycln
       - run: pycln . --config=pycln.toml --check
-      - uses: chartboost/ruff-action@v1
+      - uses: astral-sh/ruff-action@v1
         with:
-          version: "0.4.5"
-      - uses: psf/black@stable
+          version: "0.4.9"
+      - uses: astral-sh/ruff-action@v1
         with:
-          options: "--fast --check --diff --verbose"
-      - run: | # Too many files to fit in a single command, exclude vendored Scintilla and mapi_headers
+          version: "0.4.9"
+          args: "format --check"
+      - run: | # Too many files to fit in a single command, also exclude vendored Scintilla and MAPIStubLibrary
           clang-format --Werror --dry-run $(git ls-files '*.cpp')
-          clang-format --Werror --dry-run $(git ls-files '*.h' ':!:Pythonwin/Scintilla/' ':!:com/win32comext/mapi/src/mapi_headers/')
-        shell: powershell
+          clang-format --Werror --dry-run $(git ls-files '*.h' ':!:Pythonwin/Scintilla/' ':!:com/win32comext/mapi/src/MAPIStubLibrary/')
 
   mypy:
     runs-on: windows-2019
     timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
-        # mypy 1.5 dropped support for Python 3.7
         # mypy won't understand "3.13-dev", keeping the CI simple by just omitting it
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
@@ -151,7 +157,7 @@ jobs:
           cache: pip
           cache-dependency-path: .github/workflows/main.yml
           check-latest: true
-      - run: pip install types-regex types-setuptools mypy==1.11
+      - run: pip install types-setuptools PyOpenGL mypy==1.11
       - run: mypy . --python-version=${{ matrix.python-version }}
 
   pyright:
@@ -160,7 +166,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13-dev"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13-dev"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -170,7 +176,7 @@ jobs:
           cache-dependency-path: .github/workflows/main.yml
           check-latest: true
       # pyright vendors typeshed, but let's make sure we have the most up to date stubs
-      - run: pip install types-regex types-setuptools
+      - run: pip install types-setuptools PyOpenGL
       - uses: jakebailey/pyright-action@v2
         with:
           python-version: ${{ matrix.python-version }}

.pre-commit-config.yaml

@@ -29,11 +29,7 @@ repos:
     hooks:
       - id: ruff # Run the linter.
         args: [--fix]
-  - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 24.4.2
-    hooks:
-      - id: black
-        verbose: true
+      - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-clang-format
     rev: v18.1.5
     hooks:
@@ -42,9 +38,8 @@ repos:
         # https://github.com/pre-commit/mirrors-clang-format/blob/main/.pre-commit-hooks.yaml#L6
         types: [c++]
 
-
 # Vendored
-exclude: ^(com/win32comext/mapi/src/mapi_headers/|Pythonwin/Scintilla/).*$
+exclude: ^(com/win32comext/mapi/src/MAPIStubLibrary/|Pythonwin/Scintilla/).*$
 
 ci:
   autoupdate_schedule: quarterly

AutoDuck/Dump2HHC.py

@@ -231,9 +231,7 @@ def _urlescape(name):
 
 
 def _genCategoryHTMLFromDict(dict, output):
-    keys = list(dict.keys())
-    keys.sort()
-    for key in keys:
+    for key in sorted(dict):
         topic = dict[key]
         output.write(f'<LI><A HREF="{topic.context}">{topic.name}</A>\n')
 
@@ -285,9 +283,7 @@ def genCategoryHTML(output_dir, cats):
 
 def _genItemsFromDict(dict, cat, output, target, do_children=1):
     CHM = "mk:@MSITStore:%s.chm::/" % target
-    keys = list(dict.keys())
-    keys.sort()
-    for k in keys:
+    for k in sorted(dict):
         context = dict[k].context
         name = dict[k].name
         output.write(
@@ -297,9 +293,7 @@ def _genItemsFromDict(dict, cat, output, target, do_children=1):
              <param name="ImageNumber" value="1">
              <param name="Local" value="{CHM}{context}">
              </OBJECT>
-      """.format(
-                **locals()
-            )
+      """.format(**locals())
         )
         if not do_children:
             continue
@@ -343,9 +337,7 @@ def genTOC(cats, output, title, target):
         <param name="Local" value="{CHM}{target}.html">
         </OBJECT>
     <UL>
-""".format(
-            **locals()
-        )
+""".format(**locals())
     )
 
     for cat in cats:
@@ -359,9 +351,7 @@ def genTOC(cats, output, title, target):
                  <param name="Local" value="{CHM}{cat_id}.html">
                  </OBJECT>
             <UL>
-        """.format(
-                **locals()
-            )
+        """.format(**locals())
         )
         # Next write the overviews for this category
         output.write(
@@ -372,9 +362,7 @@ def genTOC(cats, output, title, target):
                      <param name="Local" value="{CHM}{cat_id}_overview.html">
                      </OBJECT>
                 <UL>
-        """.format(
-                **locals()
-            )
+        """.format(**locals())
         )
         _genItemsFromDict(cat.overviewTopics, cat, output, target)
         _genItemsFromDict(cat.extOverviewTopics, cat, output, target)
@@ -391,9 +379,7 @@ def genTOC(cats, output, title, target):
                     <param name="Local" value="{CHM}{cat_id}_modules.html">
                     </OBJECT>
                 <UL>
-""".format(
-                **locals()
-            )
+""".format(**locals())
         )
         _genItemsFromDict(cat.modules, cat, output, target)
         output.write(
@@ -408,9 +394,7 @@ def genTOC(cats, output, title, target):
                     <param name="ImageNumber" value="1">
                     <param name="Local" value="{CHM}{cat_id}_objects.html">
                     </OBJECT>
-                <UL>""".format(
-                **locals()
-            )
+                <UL>""".format(**locals())
         )
         # Don't show 'children' for objects - params etc don't need their own child nodes!
         _genItemsFromDict(cat.objects, cat, output, target, do_children=0)
@@ -427,9 +411,7 @@ def genTOC(cats, output, title, target):
          <param name="Local" value="{CHM}{cat_id}_constants.html">
          </OBJECT>
            <UL>
-""".format(
-                **locals()
-            )
+""".format(**locals())
         )
         _genItemsFromDict(cat.constants, cat, output, target)
         output.write(

AutoDuck/InsertExternalOverviews.py

@@ -26,12 +26,8 @@ def genHTML(doc):
     s = ""
     for cat in doc:
         s += f"<H3>{cat.label}</H3>\n"
-        dict = {}
-        for item in cat.overviewItems.items:
-            dict[item.name] = item.href
-        keys = list(dict.keys())
-        keys.sort()
-        for k in keys:
+        dict = {item.name: item.href for item in cat.overviewItems.items}
+        for k in sorted(dict):
             s += f'<LI><A HREF="html/{dict[k]}">{k}</A>\n'
     return s
 

AutoDuck/README → AutoDuck/README.md

@@ -1,4 +1,4 @@
-Just run MAKE.BAT to build the documentation.
+Just run [make.py](./make.py) to build the documentation.
 
 Main focus these days is on the .chm file - a single .chm
 provides the best documentation solution.  We don't even

AutoDuck/TOCToHHK.py

@@ -1,4 +1,3 @@
-import os.path
 import sys
 
 """