GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Refactor Git.{AutoInterrupt,CatFileContentStream} nesting by EliahKagan · Pull Request #2037 · gitpython-developers/GitPython

Conversation

@EliahKagan

@EliahKagan EliahKagan commented Jun 7, 2025 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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:

  • I observed this locally, and
  • It can be seen in the readthedocs cloud build for this PR, for Git.AutoInterrupt and Git.CatFileContentStream. (They can be compared to the latest release versions of the Git.AutoInterrupt and Git.CatFileContentStream classes.)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@EliahKagan
Refactor Git.{AutoInterrupt,CatFileContentStream} nesting
5a8a405
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.
@EliahKagan
EliahKagan force-pushed the flatten branch from eb07ccb to 5a8a405 Compare June 7, 2025 06:00
@EliahKagan
EliahKagan marked this pull request as ready for review June 7, 2025 06:06
@EliahKagan
EliahKagan requested a review from Byron June 7, 2025 06:06
Byron
Byron approved these changes Jun 7, 2025
View reviewed changes

@Byron Byron left a comment

Copy link
Copy Markdown
Member

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.

All reactions
@Byron
Byron merged commit 1e463d4 into gitpython-developers:main Jun 7, 2025
@EliahKagan
EliahKagan deleted the flatten branch June 7, 2025 06:23
@EliahKagan

EliahKagan commented Jun 7, 2025 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member Author

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:

  1. Checking out the commit with:

    git switch -d 5a8a4059d646fd313e81365ef240562556d8bd3f
  2. Temporarily manually reindenting the moved lines in my editor, but otherwiser keeping everything the same.

  3. 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
All reactions
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@EliahKagan EliahKagan mentioned this pull request Jun 7, 2025
Git.{AutoInterrupt,CatFileContentStream} refactor broke static typing #2038
Closed
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull request Jun 7, 2025
@EliahKagan
Start on fixing AutoInterrupt/CatFileContentStream aliases
c6d16d0
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
Fix Git.{AutoInterrupt,CatFileContentStream} static typing #2039
Merged
Fix CI mypy command on free-threaded Python #2040
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Byron Byron Byron approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

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.

2 participants

@EliahKagan @Byron
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.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.