X Tutup
Skip to content

Don't support building documentation on Python 3.7#1956

Merged
Byron merged 1 commit intogitpython-developers:mainfrom
EliahKagan:no37doc
Aug 18, 2024
Merged

Don't support building documentation on Python 3.7#1956
Byron merged 1 commit intogitpython-developers:mainfrom
EliahKagan:no37doc

Conversation

@EliahKagan
Copy link
Member

@EliahKagan EliahKagan commented Aug 18, 2024

This removes the specially cased alternative lower versions of sphinx and its dependencies that, since #1954, were only for Python 3.7. As discussed in comments there, this simplifies the documentation dependencies and avoids a situation where the version of Python used to build the documentation has a noticeable effect on the generated result.

This also conditions running the "Documentation" step in the main CI test workflow (pythonpackage.yml) on the Python version not being 3.7 (otherwise the job would always fail).

The only change this makes to the support status of GitPython on Python 3.7 is to no longer support building documentation on 3.7. GitPython can still be installed and used on 3.7 (though usually this would not be a good idea, outside of testing, since Python 3.7 itself has not been supported by the Python Software Foundation for quite some time). In addition, the documentation, which can be built on any version >= 3.8 (including 3.13 starting in #1954) is no less relevant to usage on Python 3.7 than it was before.

This should not be able to have any effect on other Python versions, including Python 3.12, which GitPython currently uses for its Read the Docs builds. But just in case, and to guard against inadvertent syntax errors, here's the successful PR preview build.

This removes the specially cased alternative lower versions of
`sphinx` and its dependencies that, since gitpython-developers#1954, were only for
Python 3.7. As discussed in comments there, this simplifies the
documentation dependencies and avoids a situation where the version
of Python used to build the documentation has a noticeable effect
on the generated result.

This also conditions running the "Documentation" step in the main
CI test workflow (`pythonpackage.yml`) on the Python version not
being 3.7 (otherwise the job would always fail).

The only change this makes to the support status of GitPython on
Python 3.7 is to no longer support building documentation on 3.7.
GitPython can still be installed and used on 3.7 (though usually
this would not be a good idea, outside of testing, since Python 3.7
itself has not been supported by the Python Software Foundation for
quite some time). In addition, the documentation, which can be
built on any version >= 3.8 (including 3.13 starting in gitpython-developers#1954) is
no less relevant to usage on Python 3.7 than it was before.
@EliahKagan EliahKagan marked this pull request as ready for review August 18, 2024 18:14
Copy link
Member

@Byron Byron left a comment

Choose a reason for hiding this comment

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

Fantastic, so much simpler, thanks a lot!

@Byron Byron merged commit cfadd9e into gitpython-developers:main Aug 18, 2024
@EliahKagan EliahKagan deleted the no37doc branch August 18, 2024 19:52
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull request Mar 9, 2026
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.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull request Mar 9, 2026
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.
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