From d1ab2e40b3bd03f84dcf440ed920bf7ab512366f Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 9 Mar 2026 14:17:27 -0400 Subject: [PATCH 1/5] Test free-threaded interpreter on macOS As discussed in #2005 and #2011, we had not been doing this before. Conditions have changed in two relevant ways: - The free-threaded interpreter has been around longer and it sees more use. - The macOS runners are very fast now. The specific motivations for doing this now are: - In view of the condition described in #2109 and how the change there seems to have helped with it, there's some reason to think *patch* versions of Python sometimes affect GitPython in ways it makes possibly unfounded assumptions about the effect of garbage collection. This mainly affects Windows and it is not specific to free-threaded builds. However, in principle we could also see assumptions violated in tests we think always work on Unix-like operating systems, due to differences in how garbage collection works in free-threaded interpreters. Therefore, the assumption that this only needs to be tested occasionally is not as well founded I assumed when I suggested testing it only on GNU/Linux. - We may add 3.14 jobs to CI soon, and it's useful to be able to see how both free-threaded interpreters work on CI, as well as to confirm for at least a short while that they are continuing to work as expected. This macOS free-threaded interpreter CI jobs could be disabled once more if necessary, or if they're found to make CI complete slower in PRs by even a small amount so long as they don't seem to be surfacing anything. --- .github/workflows/pythonpackage.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index 6c5cf4552..6c1f7a67a 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -17,8 +17,6 @@ jobs: exclude: - os-type: macos python-version: "3.7" # Not available for the ARM-based macOS runners. - - os-type: macos - python-version: "3.13t" - os-type: windows python-version: "3.13" # FIXME: Fix and enable Python 3.13 on Windows (#1955). - os-type: windows From 53c0a8800bc4297c2b50c14e8ada45bdaedfe2ab Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 9 Mar 2026 15:15:28 -0400 Subject: [PATCH 2/5] Test Python 3.14 on Ubuntu and macOS on CI The status of 3.14 is now effectively the same as the status of 3.13 when we started testing it in #1990. This doesn't enable it on Windows yet, for the same reason that we still have not yet enabled regular CI tests of 3.13 on Windows. It is hoped that 3.13 and 3.14 can be gotten fully working on Windows (rather than just mostly working, we think) soon; these exclusions are meant to be temporary. Both the usual GIL interpreter and the free-threaded (nogil) intepreters are tested. See the immediately preceding commit on the tradeoffs involved in doing so. --- .github/workflows/pythonpackage.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index 6c1f7a67a..3d2cb9b63 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -13,14 +13,18 @@ jobs: strategy: matrix: os-type: [ubuntu, macos, windows] - python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.13t"] + python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.13t", "3.14", "3.14t"] exclude: - os-type: macos python-version: "3.7" # Not available for the ARM-based macOS runners. - os-type: windows - python-version: "3.13" # FIXME: Fix and enable Python 3.13 on Windows (#1955). + python-version: "3.13" # FIXME: Fix and enable Python 3.13 and 3.14 on Windows (#1955). - os-type: windows python-version: "3.13t" + - os-type: windows + python-version: "3.14" + - os-type: windows + python-version: "3.14t" include: - os-ver: latest - os-type: ubuntu From d1ca2af85b96062a9d5979edf895ddf3968cfa49 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 9 Mar 2026 17:42:21 -0400 Subject: [PATCH 3/5] Upgrade Sphinx to ~7.4.7 Except on Python 3.8, where 7.1.2 is the latest compatible version. (This would also apply to versions lower than 3.8, but we don't support building docs on any such versions, even though we still support installing and using GitPython on 3.7.) The reason for this change is that, starting in Python 3.14, the `ast` module no longer has a `Str` member. String literals are instead represented by `ast.Constant` (and the type of the value can be checked to see if it's a string). But versions of `sphinx` lower than 7.2.0 rely on `ast.Str` being present. This causes our documentation not to be able to build at all starting in 3.14. The most important part of the error is: Exception occurred: File "/opt/hostedtoolcache/Python/3.14.3/x64/lib/python3.14/site-packages/sphinx/pycode/__init__.py", line 141, in analyze raise PycodeError(f'parsing {self.srcname!r} failed: {exc!r}') from exc sphinx.errors.PycodeError: parsing '/home/runner/work/GitPython/GitPython/git/index/base.py' failed: AttributeError("module 'ast' has no attribute 'Str'") An example of code in `sphinx` 7.1.2 that will cause such an error is `sphinx.pycode.parser.visit_Expr` implementation, which starts: if (isinstance(self.previous, (ast.Assign, ast.AnnAssign)) and isinstance(node.value, ast.Str)): In `sphinx` 7.2.0, `sphinx.pycode.parser.visit_Expr` instead begins: if (isinstance(self.previous, (ast.Assign, ast.AnnAssign)) and isinstance(node.value, ast.Constant) and isinstance(node.value.value, str)): This upgrades `sphinx` on all versions of Python where it *can* be installed at a version that has such changes -- rather than only on Python 3.14 -- for consistency, including consistency in possible minor variations in generated documentation that could otherwise arise from using different versions of `sphinx` unnecessarily. As for why this upgrades to 7.4.7 rather than only to 7.2.0, that's because they are both compatible with the same versions of Python, and as far as I know there's no reason to prefer an earlier version within that range. Although GitPython still supports being installed and run on Python 3.8 (and even on Python 3.7), it has been end-of-life (i.e., no longer supported by the Python Software Foundation) for quite some time now. That the version of Sphinx used to build documentation will now be different on Python 3.8 than other versions is a reason not to use Python 3.8 for this purpose, but probablly already not the most important reason. The change here is conceptually similar to, but much simpler than, the change in #1954, which upgraded Sphinx to 7.1.2 on all Python versions GitPython suppports other than Python 3.7. The subsequent change in #1956 of removing support for building the GitPython documentation on Python 3.7 may be paralleled for 3.8 shortly. --- doc/requirements.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 81140d898..cbf34cc69 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,3 +1,4 @@ -sphinx >= 7.1.2, < 7.2 +sphinx >= 7.4.7, < 8 ; python_version >= "3.9" +sphinx >= 7.1.2, < 7.2 ; python_version < "3.9" sphinx_rtd_theme sphinx-autodoc-typehints From 8d979061850e8659a089e4249be84d906c409334 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 9 Mar 2026 18:10:49 -0400 Subject: [PATCH 4/5] Don't support building documentation on Python 3.8 This discontinues supporting building documentation on Python 3.8. It does not affect installing or running GitPython on Python 3.8 (except when the `doc` extra is used, but this is only used for building documentation). The reason is that it is no longer possible to use the same version of Sphinx on Python 3.8 as on the most recent supported versions of Python, because Python 3.14 no longer has `ast.Str` (using `str.Constant` for string literals instead), which causes the oldest version of `sphinx` that runs on Python 3.14 to be `sphinx` 7.2.0, while the newest version that is installable on Python 3.8 is `sphinx` 7.1.2. The immediately preceding commit changes the requirements for the `doc` extra to specify a newer `sphinx` version for Python 3.9 and later. This can't be done on Python 3.8. Because there can be subtle differences in documentation generated with different `sphinx` versions, and because Python 3.8 has been end-of-life for some time, it is not really worth carrying conditional dependencies for the `sphinx` version in `doc/requirements.txt`. Note that, while it is probably not a very good idea to use GitPython (or anything) on Python 3.8 since it is end-of-life, this change does not stop supporting installing GitPython on that or any other version it has been supporting. Installing and using GitPython remains supported all the way back to Python 3.7 at this time. This only affects the `doc` extra and its requirements. This change is analogous to the change made in #1956, which followed up on the change in #1964 in the same way this change follows up on the change in the immediately preceding commit. --- .github/workflows/pythonpackage.yml | 7 ++++++- doc/requirements.txt | 3 +-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index 3d2cb9b63..8c84f7580 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -30,6 +30,11 @@ jobs: - os-type: ubuntu python-version: "3.7" os-ver: "22.04" + - build-docs: true # We ensure documentation builds, except on very old interpreters. + - python-version: "3.7" + build-docs: false + - python-version: "3.8" + build-docs: false - experimental: false fail-fast: false @@ -110,7 +115,7 @@ jobs: continue-on-error: false - name: Documentation - if: matrix.python-version != '3.7' + if: matrix.build-docs run: | pip install '.[doc]' make -C doc html diff --git a/doc/requirements.txt b/doc/requirements.txt index cbf34cc69..24472ba39 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,4 +1,3 @@ -sphinx >= 7.4.7, < 8 ; python_version >= "3.9" -sphinx >= 7.1.2, < 7.2 ; python_version < "3.9" +sphinx >= 7.4.7, < 8 sphinx_rtd_theme sphinx-autodoc-typehints From 4b25af2ae8aba951503c8c7055ffa5085bc18f3f Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 9 Mar 2026 19:16:00 -0400 Subject: [PATCH 5/5] Go back to testing free-threaded interpreters only on GNU/Linux This effectively reverts d1ab2e4. It doesn't look like any problems arose, and contrary to my guess, the additional jobs do actually make the checks that we intend to be blocking for PRs take longer, even after all non-macOS checks have completed. --- .github/workflows/pythonpackage.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index 8c84f7580..874e18a8f 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -17,6 +17,10 @@ jobs: exclude: - os-type: macos python-version: "3.7" # Not available for the ARM-based macOS runners. + - os-type: macos + python-version: "3.13t" + - os-type: macos + python-version: "3.14t" - os-type: windows python-version: "3.13" # FIXME: Fix and enable Python 3.13 and 3.14 on Windows (#1955). - os-type: windows