GeezerVison is showing github.com — Refactor Git.{AutoInterrupt,CatFileContentStream} nesting by EliahKagan · Pull Request #2037 · gitpython-developers/GitPython
Conversation
EliahKagan
commented
Jun 7, 2025
•
edited
Loading
Uh oh!
There was an error while loading. Please reload this page.
This makes Git.AutoInterrupt and Git.CatFileContentStream transparent aliases to top-level nonpublic _AutoInterrupt and _CatFileContentStream classes in the cmd module.
This does not change the "public" interface. It also does not change metadata relevant to documentation: the __name__ and __qualname__ attributes are set explicitly to the values they had before when these classes were defined nested, so that Sphinx continues to document them (and to do so in full) in Git and as Git.AutoInterrupt and Git.CatFileContentStream.
The purpose of this is to increase readability. The Git class is big and complex, with a number of long members and various forms of nesting. Since these two classes can be understood even without reading the code of the Git class, moving the definitions out of the Git class into top-level nonpublic classes will hopefully increase readability and help with maintenance.
I originally intended this as just the first commit of several. But I realized that change is probably the only one that might be controversial. So I figured I'd open a PR for it by itself.
In my view:
- The flatter layout and physical separation makes for easier reading and emphasizes that, even as they are nested classes of the
Git class as far as the interface is concerned, these classes are uses by the Git and do not themselves use the Git class.
- The conceptual burden of setting
__name__ and __qualname__ to make Sphinx continue working as desired (while still having the metadata at runtime the same as Sphinx claims) is not too big of a conceptual burden.
But whether this is better is a subjective question, so I figured it would be good to get a review.
I have verified that the intended effect in Sphinx documentation--the effect that the classes continue to be presented, in full, as nested classes of Git, just as they may (and should!) continue to be used when they are accessed both within GitPython and by other code that uses GitPython--is what we get. Specifically:
Sorry, something went wrong.
Uh oh!
There was an error while loading. Please reload this page.
This makes `Git.AutoInterrupt` and `Git.CatFileContentStream`
transparent aliases to top-level nonpublic `_AutoInterrupt` and
`_CatFileContentStream` classes in the `cmd` module.
This does not change the "public" interface. It also does not
change metadata relevant to documentation: the `__name__` and
`__qualname__` attributes are set explicitly to the values they had
before when these classes were defined nested, so that Sphinx
continues to document them (and to do so in full) in `Git` and as
`Git.AutoInterrupt` and `Git.CatFileContentStream`.
The purpose of this is to increase readability. The `Git` class is
big and complex, with a number of long members and various forms of
nesting. Since these two classes can be understood even without
reading the code of the `Git` class, moving the definitions out of
the `Git` class into top-level nonpublic classes will hopefully
increase readability and help with maintenance.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks a lot, this makes perfect sense.
Thanks also for double-checking that the documentation is still working as it did before.
Please note that I didn't validate that the removed and added portions are still the same in the interest of time.
Sorry, something went wrong.
Uh oh!
There was an error while loading. Please reload this page.
EliahKagan
commented
Jun 7, 2025
•
edited
Loading
Uh oh!
There was an error while loading. Please reload this page.
Thanks a lot, this makes perfect sense. Thanks also for double-checking that the documentation is still working as it did before.
No problem!
It was not at all obvious to me what Sphinx would do if I had not modified the metadata. (So I tried that first, but only locally, without committing the change.) If that had turned out not to be necessary for Sphinx, then I would not be sure whether it would be best to do it or not, since I think the interface is really the same either way. In any case, I think it's better to modify the metadata like this and automatically keep the documentation, than not to do so and have Sphinx treat them as nonpublic and not emit documentation for them at all.
Please note that I didn't validate that the removed and added portions are still the same in the interest of time.
It looks like some common techniques don't work here, due to a combination of changed indentation, moving the code, changing the lines at the top of the code that is moved (to _ names), and changing some other lines near the top due different wrapping of docstrings.
I've double-checked it just now by:
-
Checking out the commit with:
git switch -d 5a8a4059d646fd313e81365ef240562556d8bd3f
-
Temporarily manually reindenting the moved lines in my editor, but otherwiser keeping everything the same.
-
Examining a diff made by:
git diff --color-moved=dimmed-zebra HEAD^
It looks right, with only the new, conceptually changed (e.g. adding _), and rewrapped lines appearing as red/green rather than as gray.
|
Byron reacted with heart emoji
Sorry, something went wrong.
Uh oh!
There was an error while loading. Please reload this page.
EliahKagan
added a commit
to EliahKagan/GitPython
that referenced
this pull request
Jun 7, 2025
This uses `TypeAlias` from the `typing` module, to make it so the
assignment statments introduced in gitpython-developers#2037 (to set `Git.AutoInterrupt`
and `Git.CatFileContentStream` to nonpublic module-level
implementations `_AutoInterrupt` and `_CatFileContentStream`) are
treated by `mypy` as type aliases rather than as class variables.
For details on the problem this partially fixes, see gitpython-developers#2038 and:
https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
The fix won't work in this form, however, because it attempts to
import `TypeAlias` unconditionally from the standard-library
`typing` module, which only gained it in Python 3.10.
This was referenced Jun 7, 2025
Reviewers
Byron
Byron approved these changes
Uh oh!
There was an error while loading. Please reload this page.
Assignees
No one assigned
Milestone
No milestone
Development
Successfully merging this pull request may close these issues.
Uh oh!
There was an error while loading. Please reload this page.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
|