X Tutup
Skip to content

Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14#2112

Merged
EliahKagan merged 5 commits intogitpython-developers:mainfrom
EliahKagan:py314
Mar 9, 2026
Merged

Upgrade Sphinx for 3.14 support; drop doc build support on 3.8; test 3.14#2112
EliahKagan merged 5 commits intogitpython-developers:mainfrom
EliahKagan:py314

Conversation

@EliahKagan
Copy link
Member

@EliahKagan EliahKagan commented Mar 9, 2026

As detailed in d1ca2af and 8d97906, no version of Sphinx supports both Python 3.8 and Python 3.14. This makes changes analogous to those in #1954 and #1956, except to extend support to Python 3.14 (rather than Python 3.13), and the changes here are significantly simpler than what had to be done in #1954, since no Python code had to be changed in this case.

d1ca2af uses a newer Sphinx version range where supported. 8d97906 then requires that version range, thereby dropping the ability to build documentation on 3.8, and adjusting CI accordingly. I did these as separate steps, expressing the version conditionally in d1ca2af, so that we can restore the relevant files to how they were there in the unexpected event that it's necessary to continue supporting building documentation on Python 3.8.

This adds some more interpreters to be tested regularly. The main purpose of this is to test Python 3.14 on GNU/Linux and macOS, where it is currently expected to work. It is expected only to mostly work on Windows, for the same reason that Python 3.13 is also only expected to mostly work on Windows. In both cases, there is a test that will fail on Windows. This is still as described in #1955, except that I haven't yet updated that to note that the situation is now the same for--and that it will thus also be able to address--Python 3.14.

Another change made to the interpreters tested here is that this tests free-threaded interpreters not only on GNU/Linux but also on macOS. We might want to undo that if it makes CI take longer overall. I expect that to rarely or never happen, but I'm not sure. I might find out during the course of testing this PR, which I'm doing in multiple pushes, whether that's a problem. For some more details (and rationale) on the interpreters added to be tested, see d1ab2e4 and 53c0a88.


This remains a draft mainly because, while I know the documentaton builds, I want to look at the RTD docs to make sure they look okay--they should either look the same or slightly better due to the upgrade, but this shouldn't be assumed.

Edit: Here's the build, and here's what it looks like. It looks the same as before, which is as expected--I just wanted to make sure it was no worse. With the newer Sphinx, I suspect it may be easier to make it look better too, such as by looking at other themes that might make the content clearer, especially in the API reference. But that's not automatic, and it's definitely outside the scope of this PR.

The main remaning thing to check, beisdes that all CI jobs pass (they should actually all pass for each commit except 53c0a88) is that macOS isn't what keeps CI on the PR from completing sooner. If so, then we might consider going back to testing free-threaded builds only on Ubuntu and not macOS, since that would decrease the number of macOS jobs by 2.

Further edit: See comments for more updates on this.

As discussed in gitpython-developers#2005 and gitpython-developers#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 gitpython-developers#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.
The status of 3.14 is now effectively the same as the status of
3.13 when we started testing it in gitpython-developers#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.
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 gitpython-developers#1954, which upgraded Sphinx to 7.1.2 on all Python
versions GitPython suppports other than Python 3.7. The subsequent
change in gitpython-developers#1956 of removing support for building the GitPython
documentation on Python 3.7 may be paralleled for 3.8 shortly.
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 gitpython-developers#1956, which
followed up on the change in gitpython-developers#1964 in the same way this change
follows up on the change in the immediately preceding commit.
@EliahKagan
Copy link
Member Author

EliahKagan commented Mar 9, 2026

That, as of this writing, all the still-pending checks at the tip of this PR are for macOS is some reason to think I may have been too eager in thinking we can run more jobs on macOS without it increasing the total PR check time.

Screenshot showning five pending checks, all waiting on macOS runners

However, I think the much shorter time macOS checks take than Windows checks will still make this not a problem. I'll check to see if that's really the case before assuming the enw checks in this PR don't have to be pared down before this is ready to merge.


Edit: I guessed wrong! The slowness of the Windows checks is outmatched by the smaller number of available macOS runners! I suspect that the Tahoe runners might be even faster, by an amount that reverses that, but the case for testing free-threaded interprters on macOS is weak enough right now that I'll just go back to testing free-threaded interpreters only on GNU/Linux on CI.

Edit 2: I've removed them in a new commit rather than rebasing out the original commit that added them, since I think both the process of testing them as well as their results are valuable to have in the history. I think this PR can be merged once CI passes on this new commit.

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.
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates documentation build dependencies and CI configuration to accommodate Python 3.14 support, acknowledging that a single Sphinx version range can no longer support building docs on Python 3.8 while also supporting Python 3.14.

Changes:

  • Bump Sphinx requirement for documentation builds to a newer supported range (>=7.4.7,<8).
  • Extend CI test matrix to include Python 3.14 and 3.14 free-threaded (3.14t).
  • Adjust CI documentation-build gating intended to skip docs on Python 3.7 and 3.8.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File Description
doc/requirements.txt Updates Sphinx version range used by the doc extra to a range compatible with Python 3.14.
.github/workflows/pythonpackage.yml Extends the CI Python matrix and attempts to alter docs-build gating logic.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

@EliahKagan EliahKagan marked this pull request as ready for review March 9, 2026 23:31
@EliahKagan EliahKagan merged commit 5780812 into gitpython-developers:main Mar 9, 2026
34 checks passed
@EliahKagan EliahKagan deleted the py314 branch March 9, 2026 23:32
@EliahKagan EliahKagan requested a review from Copilot March 9, 2026 23:34
@EliahKagan

This comment was marked as resolved.

This comment was marked as resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

X Tutup