Replace all wildcard imports with explicit imports #1880
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This script can be removed after imports are refactored and checked to see that module contents are the same as before or otherwise non-broken. This script assumes that module contents are the same as the contents of their dictionaries, and that all modules in the project get imported as a consequence of importing the top-level module. These are both the case currently for GitPython, but they do not hold for all projects, and may not hold for GitPython at some point in the future.
Although this situation is not inherently desirable, for backward compatibility it cannot change at this time. It may be possible to change it in the next major version of GitPython, but even then it should not be changed accidentally, which can easily happen while refactoring imports. This tests the highest-risk accidental change (of those that are currently known) of the kind that the temporary modattrs.py script exists to help safeguard against. That script will be removed when the immediately forthcoming import refactoring is complete, whereas these test cases can be kept. For information about the specific situation this helps ensure isn't changed accidentally, see the new test cases' docstrings, as well as the next commit (which will test modattrs.py and these test cases by performing an incomplete change that would be a bug until completed). This commit adds three test cases. The first tests the unintuitive aspect of the current situation: - test_git_util_attribute_is_git_index_util The other two test the intuitive aspects of it, i.e., they test that changes (perhaps in an attempt to preserve the aspect needed for backward compatibility) do not make `git.util` unusual in new (and themselves incompatible) ways: - test_git_index_util_attribute_is_git_index_util - test_separate_git_util_module_exists The latter tests should also clarify, for readers of the tests, the limited nature of the condition the first test asserts.
This also checks if the regression tests in test_imports.py work. This replaces wildcard imports in git.index with explicit imports, and adds git.index.__all__. But this temporarily omits from it the public attributes of git.index that name its Python submodules and are thus are present as an indirect effect of importing names *from* them (since doing so also imports them). This partial change, until it is completed in the next commit, represents the kind of bug that modattrs.py seeks to safeguard against, and verifies that a diff between old and current output of modattrs.py clearly shows it. This diff is temporarily included as ab.diff, which will be deleted in the next commit. The key problem that diff reveals is the changed value of the util attribute of the top-level git module. Due to the way wildcard imports have been used within GitPython for its own modules, expressions like `git.util` (where `git` is the top-level git module) and imports like `from git import util` are actually referring to git.index.util, rather than the util Python submodule of the git module (conceptually git.util), which can only be accessed via `from git.util import ...` or in `sys.modules`. Although this is not an inherently good situation, in practice it has to be maintained at least until the next major version, because reasonable code that uses GitPython would be broken if the situation were changed to be more intuitive. But the more intuitive behavior automatically happens if wildcard imports are replaced with explicit imports of the names they had originally intended to import (in this case, in the top-level git module, which has not yet been done but will be), or if __all__ is added where helpful (in this case, in git.index, which this does). Adding the names explicitly is sufficient to restore the old behavior that is needed for backward compatibility, and has the further advantage that the unintuitive behavior will be explicit once all wildcard imports are replaced and __all__ is added to each module where it would be helpful. The modattrs.py script serves to ensure incompatible changes are not made; this commit checks it. The tests in test_imports.py also cover this specific anticipated incompatibility in git.util, but not all breakages that may arise when refactoring imports and that diff-ing modattrs.py output would help catch.
- Add the base, fun, typ, and util Python submodules of git.index to git.index.__all__ to restore the old behavior. - Import them explicitly for clarity, even though they are bound to the same-named attributes of git.index either way. This should help human readers know what the entries in __all__ are referring to, and may also help some automated tools. This is a preliminary decision and not necessarily the one that will ultimately be taken in this import refactoring. It *may* cause some kinds of mistakes, such as those arising from ill-advised use of wildcard imports in production code *outside* GitPython, somewhat worse in their effects. - Remove the ab.diff file that showed the problem this solves. This resolves the problem deliberately introduced in the previous incomplete commit, which modattrs.py output and test_imports test results confirm.
This uses explicit imports rather than wildcard imports in git.refs for names from its submodules. A comment suggested that the import order was deliberate. But each of the modules being imported from defined __all__, and there was no overlap in the names across any of them. The other main reason to import in a specific order is an order dependency in the side effects, but that does not appear to apply, at least not at this time. (In addition, at least for now, this adds explicit imports for the Python submodules of git.refs, so it is clear that they can always be accessed directly in git.refs without further imports, if desired. For clarity, those appear first, and that makes the order of the "from" imports not relevant to such side effects, due to the "from" imports no longer causing modules to be loaded for the first time. However, this is a much less important reason to consider the other imports' reordering okay, because these module imports may end up being removed later during this refactoring; their clarity benefit might not be justified, because if production code outside GitPython ill-advisedly uses wildcard imports, the bad effect of doing so could be increased.)
- No need to import Repo "as Repo". Some tools only recognize this to give the name conceptually public status when it appears in type stub files (.pyi files), and listing it in the newly created __all__ is sufficient to let humans and all tools know it has that status. - As very recently done in git.refs, this explicitly imports the submodules, so it is clear they are available and don't have to be explicitly imported. (Fundamental to the way they are used is that they will end up being imported in order to import Repo.) However, also as in git.refs, it may be that the problems this could cause in some inherently flawed but plausible uses are too greater for it to be justified. So this may be revisited.
But not yet in git.objects.submodule.* modules.
Such patching, which was introduced in 9519f18, seems no longer to be necessary. Since git.objects.submodule.util.__all__ has existed for a long time without including those names, they are not conceptually public attributes of git.objects.submodule.util, so they should not be in use by any code outside GitPython either. The modattrs.py script shows the change, as expected, showing these two names as no longer being in the git.objects.submodule.util module dictionary, in output of: python modattrs.py >b git diff --no-index a b However, because the removal is intentional, this is okay.
The submodules being made explicit here are of course Python submodules, not git submodules. The git.objects.submodule Python submodule (which is *about* git submodules) is made explicit here (as are the names imported from that Python submodule's own Python submodules) along with the other Python submodules of git.objects. Unlike some other submodules, but like the top-level git module until gitpython-developers#1659, git.objects already defined __all__ but it was dynamically constructed. As with git.__all__ previously (as noted in gitpython-developers#1859), I have used https://github.com/EliahKagan/deltall here to check that it is safe, sufficient, and probably necessary to replace this dynamically constructed __all__ with a literal list of strings in which all of the original elements are included. See: https://gist.github.com/EliahKagan/e627603717ca5f9cafaf8de9d9f27ad7 Running the modattrs.py script, and diffing against the output from before the current import refactoring began, reveals two changes to module contents as a result of the change here: - git.objects no longer contains `inspect`, which it imported just to build the dynamically constructed __all__. Because this was not itself included in that __all__ or otherwise made public or used out of git.objects, that is okay. This is exactly analogous to the situation in 8197e90, which removed it from the top-level git module after gitpython-developers#1659. - The top-level git module now has has new attributes blob, commit, submodule, and tree, aliasing the corresponding modules. This has happened as a result of them being put in git.objects.__all__ along with various names imported from them. (As noted in some prior commits, there are tradeoffs associated with doing this, and it may be that such elements of __all__ should be removed, here and elsewhere.)
So git.objects.util is less likely to be confused with git.util. (The modattrs.py script reveals the change in the value of git.objects.util.__doc__, as expected.)
This is the top-level of the git.objects.submodule subpackage, for its own Python submodules. This appears only not to have been done before because of a cyclic import problem involving imports that are no longer present. Doing it improves consistency, since all the other subpackages under the top-level git package already do this. The modattrs.py script reveals the four new attributes of git.objects.submodule for the four classes obtained by the new imports, as expected. (The explicit module imports do not change the attribues because they are the same attributes as come into existence due to those Python submodules being imported anywhere in any style.)
+ Update the detailed comment about the unused import situation.
These are in the modules that are directly under the top-level git module (and are not themselves subpackages, with their own submodules in the Python sense), except for: - git.util, where this change was very recently made. - git.compat, where no improvements of this kind were needed. - git.types, which currently has no __all__ and will only benefit from it if what should go in it is carefully considered (and where the imports themselves are grouped, sorted, and formatted already).
In git.compat and git.util. This applies them individually to each name that is known to be an unused import, rather than to entire import statements (except where the entire statement fit on one line and everything it imported is known to be unused). Either Ruff has the ability to accept this more granular style of suppression, or I had been unaware of it from flake8 (used before). I have veriifed that the suppressions are not superfluous: with no suppressions, Ruff does warn. This commit makes no change in git.types because it looks like no suppression at all may be needed there anymore; that will be covered in the next commit. This also removes the old `@UnusedImport` comments, which had been kept before because they were more granular; this specificity is now achieved by comments the tools being used can recognize.
In git.types. It appears Ruff, unlike flake8, recognizes "import X as X" to mean that "X" should not be considered unused, even when it appears outside a .pyi type stub file where that notation is more commonly used. Those imports in git.types may benefit from being changed in some way that uses a syntax whose intent is clearer in context, and depending on how that is done it may even be necessary to bring back suppressions. If so, they can be written more specifically. (For now, changing them would express more than is known about what names that are only present in git.types becuase it imports them should continue to be imported, should be considered conceptually public, or should be condered suitable for use within GitPython.)
- Use explicit imports instead of * imports. - Remove now-unneeded linter suppressions. - Alphabetize inside the try-block, though this will be undone. This currently fails to import due to a cyclic import error, so the third change, alphabetizing the imports, will have to be undone (at least in the absence of other changes). It is not merely that they should not be reordered in a way that makes them cross into or out of the try-block, but that within the try block not all orders will work. There will be more to do for backward compatibility, but the modattrs.py script, which imports the top-level git module, cannot be run until the cyclic import problem is fixed.
This still uses all explicit rather than wildcard imports (and
still omits suppressions that are no longer needed due to wildcard
imports not being used). But it brings back the old relative order
of the `from ... import ...` statements inside the try-block.
Since this fixes the circular import problem, it is possible to run
the modattrs.py script to check for changes. New changes since
replacing wildcard imports, which are probably undesirable, are the
removal of these attributes pointing to indirect Python submodules
of the git module:
base -> git.index.base
fun -> git.index.fun
head -> git.refs.head
log -> git.refs.log
reference -> git.refs.reference
symbolic -> git.refs.symbolic
tag -> git.refs.tag
typ -> git.index.typ
These should definitely never be used by code inside or outside of GitPython, as they have never been public, having even been omitted by the dynamic (and expansive) technique used to build git.__all__ in the past (which omitted modules intentionally). However, to ease compatibility, for now they are back. This is so that the change of making all imports explicit rather than using wildcards does not break anything. However, code using these names could never be relied on to work, and these should be considered eligible for removal, at least from the perspective of code outside GitPython. That is for the indirect submodules whose absence as a same-named direct submodule or attribute listed in __all__ was readily discoverable. The more difficult case is util. git.util is a module, git/util.py, which is how it is treated when it appears immediately after the "from" keyword, or as a key in sys.modules. However, the expression `git.util`, and a `from git import util` import, instead access the separate git.index.util module, which due to a wildcard import has been an attribute of the top-level git module for a long time. It may not be safe to change this, because although any code anywhere is better off not relying on this, this situation hasn't been (and isn't) immediately clear. To help with it somewhat, this also includes a detailed comment over where util is imported from git.index, explaining the situation.
Since they are listed in __all__. (They are imported either way because names are imported from them, and this caused them to be present with the same effect.) Though they are proably about to be removed along with the corresponding entries in __all__.
This is for non-toplevel __all__, as git.__all__ already did not do this. As noted in some of the previous commit messags that added them, omitting them might be a bit safer in terms of the impact of bugs bugs in code using GitPython, in that unexpected modules, some of which have the same name as other modules within GitPython, won't be imported due to wildcard imports from intermediate subpackages (those that are below the top-level git package/module but collect non-subpackage modules). Though it is hard to know, since some of these would have been imported before, when an __all__ was not defined at that level. However, a separate benefit of omitting them is consistency with git.__all__, which does not list the direct Python submodules of the git module. This does not affect the output of the modattrs.py script, because the attributes exist with the same objects as their values as a result of those Python submodules being imported (in "from" imports and otherwise), including when importing the top-level git module.
This makes all __all__ everywhere in the git package lists. Before, roughly half were lists and half were tuples. There are reasonable theoretical arguments for both, and in practice all tools today support both. Traditionally using a list is far more common, and it remains at least somewhat more common. Furthermore, git/util.py uses a list and is currently written to append an element to it that is conditionally defined on Windows (though it would probably be fine for that to be the only list, since it reflects an actual relevant difference about it). The goal here is just to remove inconsistency that does not signify anything and is the result of drift over time. If a reason (even preference) arises to make them all tuples in the future, then that is also probably fine.
This commits the diff of the output of the modattrs.py script between when the script was introduced in 1e5a944, and now (with the import refactoring finished and no wildcard imports remaining outside the test suite, and only there in one import statement for test helpers). Neither this diff nor modattrs.py itself will be retained. Both will be removed in the next commit. This is committed here to facilitate inspection and debugging (especially if turns out there are thus-far undetected regressions).
Now that it has served its purpose. (Of course, it can also be brought back from the history at any time if needed.) Changes: - Delete the modattrs.py script that was used to check for unintended changes to what module attributes existed and what objects they referred to, while doing the import refactoring. - Delete the ab.diff file showing the overall diff, which was temporarily introduced in the previous commit. - Remove the "a" and "b" temporary entries in .gitignore that were used to facilitate efficient use of modattrs.py while carrying out the import refactoring.
There is only one __all__ in the test suite, so this is mostly the change to imports, grouping and sorting them in a fully consistent style that is the same as the import style in the code under test.
|
It looks like https://github.com/gitpython-developers/GitPython/actions/runs/8339331003/job/22821123508, in 5b2771d, is due to a network error and would go away if run again. In contrast, the subsequent commit, fc86a23, is expected to having a failing status (which should go green again starting in the commit after that). |
Byron
approved these changes
Mar 19, 2024
There was a problem hiding this comment.
Thanks so much for fixing these imports! It sounds like doing so is going to have major benefits, despite being a conceptually simple change.
- I wrote a short script (1e5a944, f705fd6) to verify that changes to module contents were minimal and as expected, including verifying what object attributes reference, not just what the attributes' names were.
Incredibly diligent, thanks so much.
I will merge this PR once CI has caught up and is green.
renovate bot
referenced
this pull request
in allenporter/flux-local
Mar 31, 2024
[](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [GitPython](https://togithub.com/gitpython-developers/GitPython) | `==3.1.42` -> `==3.1.43` | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>gitpython-developers/GitPython (GitPython)</summary> ### [`v3.1.43`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.43) [Compare Source](https://togithub.com/gitpython-developers/GitPython/compare/3.1.42...3.1.43) #### Particularly Important Changes These are likely to affect you, please do take a careful look. - Issue and test deprecation warnings by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1886](https://togithub.com/gitpython-developers/GitPython/pull/1886) - Fix version_info cache invalidation, typing, parsing, and serialization by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1838](https://togithub.com/gitpython-developers/GitPython/pull/1838) - Document manual refresh path treatment by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1839](https://togithub.com/gitpython-developers/GitPython/pull/1839) - Improve static typing and docstrings related to git object types by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1859](https://togithub.com/gitpython-developers/GitPython/pull/1859) #### Other Changes - Test in Docker with Alpine Linux on CI by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1826](https://togithub.com/gitpython-developers/GitPython/pull/1826) - Build online docs (RTD) with -W and dependencies by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1843](https://togithub.com/gitpython-developers/GitPython/pull/1843) - Suggest full-path refresh() in failure message by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1844](https://togithub.com/gitpython-developers/GitPython/pull/1844) - `repo.blame` and `repo.blame_incremental` now accept `None` as the `rev` parameter. by [@​Gaubbe](https://togithub.com/Gaubbe) in [https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846) - Make sure diff always uses the default diff driver when `create_patch=True` by [@​can-taslicukur](https://togithub.com/can-taslicukur) in [https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832) - Revise docstrings, comments, and a few messages by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1850](https://togithub.com/gitpython-developers/GitPython/pull/1850) - Expand what is included in the API Reference by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1855](https://togithub.com/gitpython-developers/GitPython/pull/1855) - Restore building of documentation downloads by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1856](https://togithub.com/gitpython-developers/GitPython/pull/1856) - Revise type annotations slightly by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1860](https://togithub.com/gitpython-developers/GitPython/pull/1860) - Updating regex pattern to handle unicode whitespaces. by [@​jcole-crowdstrike](https://togithub.com/jcole-crowdstrike) in [https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853) - Use upgraded pip in test fixture virtual environment by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1864](https://togithub.com/gitpython-developers/GitPython/pull/1864) - lint: replace `flake8` with `ruff` check by [@​Borda](https://togithub.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862) - lint: switch Black with `ruff-format` by [@​Borda](https://togithub.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1865](https://togithub.com/gitpython-developers/GitPython/pull/1865) - Update readme and tox.ini for recent tooling changes by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1868](https://togithub.com/gitpython-developers/GitPython/pull/1868) - Split tox lint env into three envs, all safe by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1870](https://togithub.com/gitpython-developers/GitPython/pull/1870) - Slightly broaden Ruff, and update and clarify tool configuration by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1871](https://togithub.com/gitpython-developers/GitPython/pull/1871) - Add a "doc" extra for documentation build dependencies by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1872](https://togithub.com/gitpython-developers/GitPython/pull/1872) - Describe `Submodule.__init__` parent_commit parameter by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1877](https://togithub.com/gitpython-developers/GitPython/pull/1877) - Include TagObject in git.types.Tree_ish by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1878](https://togithub.com/gitpython-developers/GitPython/pull/1878) - Improve Sphinx role usage, including linking Git manpages by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1879](https://togithub.com/gitpython-developers/GitPython/pull/1879) - Replace all wildcard imports with explicit imports by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1880](https://togithub.com/gitpython-developers/GitPython/pull/1880) - Clarify how tag objects are usually tree-ish and commit-ish by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1881](https://togithub.com/gitpython-developers/GitPython/pull/1881) #### New Contributors - [@​Gaubbe](https://togithub.com/Gaubbe) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846) - [@​can-taslicukur](https://togithub.com/can-taslicukur) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832) - [@​jcole-crowdstrike](https://togithub.com/jcole-crowdstrike) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853) - [@​Borda](https://togithub.com/Borda) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862) **Full Changelog**: gitpython-developers/GitPython@3.1.42...3.1.43 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/allenporter/flux-local). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9--> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
lettuce-bot bot
referenced
this pull request
in lettuce-financial/github-bot-signed-commit
Apr 1, 2024
](https://renovatebot.com){kind=link}
[](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [GitPython](https://togithub.com/gitpython-developers/GitPython) | `==3.1.42` -> `==3.1.43` | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>gitpython-developers/GitPython (GitPython)</summary> ### [`v3.1.43`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.43) [Compare Source](https://togithub.com/gitpython-developers/GitPython/compare/3.1.42...3.1.43) #### Particularly Important Changes These are likely to affect you, please do take a careful look. - Issue and test deprecation warnings by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1886](https://togithub.com/gitpython-developers/GitPython/pull/1886) - Fix version_info cache invalidation, typing, parsing, and serialization by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1838](https://togithub.com/gitpython-developers/GitPython/pull/1838) - Document manual refresh path treatment by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1839](https://togithub.com/gitpython-developers/GitPython/pull/1839) - Improve static typing and docstrings related to git object types by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1859](https://togithub.com/gitpython-developers/GitPython/pull/1859) #### Other Changes - Test in Docker with Alpine Linux on CI by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1826](https://togithub.com/gitpython-developers/GitPython/pull/1826) - Build online docs (RTD) with -W and dependencies by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1843](https://togithub.com/gitpython-developers/GitPython/pull/1843) - Suggest full-path refresh() in failure message by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1844](https://togithub.com/gitpython-developers/GitPython/pull/1844) - `repo.blame` and `repo.blame_incremental` now accept `None` as the `rev` parameter. by [@​Gaubbe](https://togithub.com/Gaubbe) in [https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846) - Make sure diff always uses the default diff driver when `create_patch=True` by [@​can-taslicukur](https://togithub.com/can-taslicukur) in [https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832) - Revise docstrings, comments, and a few messages by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1850](https://togithub.com/gitpython-developers/GitPython/pull/1850) - Expand what is included in the API Reference by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1855](https://togithub.com/gitpython-developers/GitPython/pull/1855) - Restore building of documentation downloads by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1856](https://togithub.com/gitpython-developers/GitPython/pull/1856) - Revise type annotations slightly by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1860](https://togithub.com/gitpython-developers/GitPython/pull/1860) - Updating regex pattern to handle unicode whitespaces. by [@​jcole-crowdstrike](https://togithub.com/jcole-crowdstrike) in [https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853) - Use upgraded pip in test fixture virtual environment by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1864](https://togithub.com/gitpython-developers/GitPython/pull/1864) - lint: replace `flake8` with `ruff` check by [@​Borda](https://togithub.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862) - lint: switch Black with `ruff-format` by [@​Borda](https://togithub.com/Borda) in [https://github.com/gitpython-developers/GitPython/pull/1865](https://togithub.com/gitpython-developers/GitPython/pull/1865) - Update readme and tox.ini for recent tooling changes by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1868](https://togithub.com/gitpython-developers/GitPython/pull/1868) - Split tox lint env into three envs, all safe by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1870](https://togithub.com/gitpython-developers/GitPython/pull/1870) - Slightly broaden Ruff, and update and clarify tool configuration by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1871](https://togithub.com/gitpython-developers/GitPython/pull/1871) - Add a "doc" extra for documentation build dependencies by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1872](https://togithub.com/gitpython-developers/GitPython/pull/1872) - Describe `Submodule.__init__` parent_commit parameter by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1877](https://togithub.com/gitpython-developers/GitPython/pull/1877) - Include TagObject in git.types.Tree_ish by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1878](https://togithub.com/gitpython-developers/GitPython/pull/1878) - Improve Sphinx role usage, including linking Git manpages by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1879](https://togithub.com/gitpython-developers/GitPython/pull/1879) - Replace all wildcard imports with explicit imports by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1880](https://togithub.com/gitpython-developers/GitPython/pull/1880) - Clarify how tag objects are usually tree-ish and commit-ish by [@​EliahKagan](https://togithub.com/EliahKagan) in [https://github.com/gitpython-developers/GitPython/pull/1881](https://togithub.com/gitpython-developers/GitPython/pull/1881) #### New Contributors - [@​Gaubbe](https://togithub.com/Gaubbe) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846) - [@​can-taslicukur](https://togithub.com/can-taslicukur) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832) - [@​jcole-crowdstrike](https://togithub.com/jcole-crowdstrike) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853) - [@​Borda](https://togithub.com/Borda) made their first contribution in [https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862) **Full Changelog**: gitpython-developers/GitPython@3.1.42...3.1.43 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/lettuce-financial/github-bot-signed-commit). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Fixes #1349
This actually makes a number of related changes, several of which the reduction in mypy errors in #1859 helped in validating:
All wildcard imports (
from blah import *) are replaced with imports of specific names. This is the key change, with everything else done to support it, or directly facilitated by it, or conceptually related to it, or practically easy to do alongside it.Wildcard imports are inherently brittle, discouraged in PEP-8, and have already led to some difficulties for GitPython (see fc86a23 and the "Another ambiguity, possibly relevant" section of #1802). Even more importantly, this makes things easier for type checkers, especially for code that uses GitPython from the outside where common and useful configurations otherwise report errors due to the wildcards' lack of explicitness about what names they introduce.
Furthermore, the combination of the mypy error reduction in #1859 with the elimination of wildcard imports makes it feasible to verify that newly introduced dynamic behavior is done in a way that avoids breaking static type checking for users of GitPython. This allows deprecation warnings on access to specific module attributes, as may be useful in
git.compat, as well as a dynamically generatedgit.__version__attribute, to be safely approachable. (But such now-doable enhancements are not part of this pull request.)I wrote a short script (1e5a944, f705fd6) to verify that changes to module contents were minimal and as expected, including verifying what object attributes reference, not just what the attributes' names were.
Top-level names that are imported only to match what was imported before, but that are nonpublic and inadvisable to use, are commented as such where they are imported. Most of these could possibly be removed very soon.
The test suite has a few new tests, to test a particularly tricky aspect of the observable behavior of imports that is easy to change accidentally but should only ever be changed intentionally (the
git.utilvs.git.objects.utilissue).__all__is added where absent but clearly useful, which is everywhere undergitwhere it was absent exceptgit.types. This was only a handful of places.git.objects.__all__, which was dynamically generated as a list comprehension--asgit.__all__was prior to #1659--is likewise replaced with a literal__all__. As detailed in the f89d065 commit message, I useddeltall(see also #1875) to verify that this was the right course.The
__init__forgit.objects.submoduleno longer patchesIndexObjectandObjectintogit.objects.submodule.util. This had been done to avoid a circular import error, but at some point ceased to be needed. Becausegit.objects.submodule.utilhas defined__all__for a long time, which omits them (and seems always to have omitted them), and because it also does not use them, I didn't replace that patching with any other way of getting them in there. However, it looks like it would be feasible to import them in a way that would not cause problems, if that is called for.Also related to that situation,
git.objects.submodulehad been the only subpackage whose__init__didn't make names from its own submodules available directly in it. Because neither the circular import error nor the dynamic patching workaround are being done, there is no impediment to this, which improves consistency across the project and seemed to me to be what users would expect, so I included that.__all__is now placed at the PEP-8 recommended location near the top of each module, above imports except in rare cases where that is infeasible.A number of linter suppressions are removed, most of which are no longer needed due to wildcard imports no longer being used. Some others are made more specific, including by splitting them into suppressions that apply to specific names in a
fromimport. Some of what facilitates this is actually the switch from flake8 to Ruff in #1862.Imports across the project are fully sorted and grouped, in a consistent style that I think reflects the sensibility of the style that has been in place for an extended time. This is something that I had done bits of as part of other pull requests, and it was convenient to "complete" it here. I use scare quotes because it is likely I have missed some things. Ideally this should eventually be checked--or, better, applied--by an automated tool. Ruff can sort imports but I don't think it supports anything like this style, while isort is more configurable but might still be difficult to get to do it. However, the goal here is not this specific style, but instead to have something as consistent and helpful as possible if the style is not changed or before it is changed, while also making it easier to identify the advantages and disadvantages of an automatically applicable style over the best the current style has to offer.
Minor cleanup alongside these changes, including removal of old commented-out code (done in its own commits so it's easy to find in case that code is wanted again) and rewording the
git.objects.utilmodule docstring to distinguish that module fromgit.util. The latter is the reason for that__doc__attribute change.A few special considerations:
It was suggested that #1349 could be fixed by writing
git.__all__literally rather than dynamically generating it. But that improvement was since made in #1659, and while #1656 was fixed, #1349 remained. I've re-verified that this is the case by creating a repository that uses GitPython in a way that more closely approximates installing it from PyPI than is common during development, and ensures that the non-defaultmypyconfiguration inpyproject.tomlis not used, while still allowing arbitrary files to be tested, by doing a non-editable installation into a different directory with a separate virtual environment. More details are in this gist. This confirmed that, as of the main branch at 0a609b9, #1349 was reproducible, while at the tip of this feature branch, d524c76, it was resolved.I am not sure what the best choice is for whether intermediate subpackages--Python modules like
git.objectsandgit.refsthat are under the top-levelgitpackage but contain their own Python submodules--should include their Python submodules' names in__all__. In GitPython (though not all projects), everything is imported as a consequence of importing the top-levelgitmodule, so these are already available, and they are also already public, in the sense that they are available due to having been imported, with the fully qualified names they are guaranteed to have as a consequence of being imported. In most but not all cases--git.objectsbeing a major counterexample due to its previously dynamically built__all__that omitted modules--these were already importable in wildcard imports due to the absence of__all__.However, that this was the case had caused some problems, including several modules that are not direct children of the top-level
gitmodule ending up as attributes of it (most of which are simply private attributes that should not be used, but one of which, beinggit.index.util, is the cause of thegit.util/git.index.utilambiguity). Something different could be done ingit.objectsthan elsewhere for maximum similarity to the previous state of affairs, but I decided instead to omit them everywhere, based on the top-levelgitmodule not listing its own direct Python submodules in its__all__, and the possibility that omitting them would help mitigate the risks of wildcard imports outside of GitPython.Some modules have unused imports not listed in
__all__, present intentionally for use in other GitPython modules but not public outside the project. As commented on #1854, I'm unsure whether or how that should ultimately be improved, but I definitely consider it beyond the scope of this pull request. As such,implicit_reexport = trueremains set formypyinpyproject.toml(mypyotherwise warns about this situation wherever other modules use such imports).