Skip to content

Commit 31f89a1

Browse files
committed
Add the nonpublic indirect submodule aliases back for now
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.
1 parent 64c9efd commit 31f89a1

File tree

1 file changed

+20
-1
lines changed

1 file changed

+20
-1
lines changed

Diff for: git/__init__.py

+20-1
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,11 @@
144144
SymbolicReference,
145145
Tag,
146146
TagReference,
147+
head, # noqa: F401 # Nonpublic. May disappear! Use git.refs.head.
148+
log, # noqa: F401 # Nonpublic. May disappear! Use git.refs.log.
149+
reference, # noqa: F401 # Nonpublic. May disappear! Use git.refs.reference.
150+
symbolic, # noqa: F401 # Nonpublic. May disappear! Use git.refs.symbolic.
151+
tag, # noqa: F401 # Nonpublic. May disappear! Use git.refs.tag.
147152
)
148153
from git.diff import ( # @NoMove
149154
INDEX,
@@ -164,7 +169,21 @@
164169
IndexEntry,
165170
IndexFile,
166171
StageType,
167-
util, # noqa: F401 # For backward compatibility.
172+
base, # noqa: F401 # Nonpublic. May disappear! Use git.index.base.
173+
fun, # noqa: F401 # Nonpublic. May disappear! Use git.index.fun.
174+
typ, # noqa: F401 # Nonpublic. May disappear! Use git.index.typ.
175+
#
176+
# NOTE: The expression `git.util` evaluates to git.index.util, and the import
177+
# `from git import util` imports git.index.util, NOT git.util. It may not be
178+
# feasible to change this until the next major version, to avoid breaking code
179+
# inadvertently relying on it. If git.index.util really is what you want, use or
180+
# import from that name, to avoid confusion. To use the "real" git.util module,
181+
# write `from git.util import ...`, or access it as `sys.modules["git.util"]`.
182+
# (This differs from other historical indirect-submodule imports that are
183+
# unambiguously nonpublic and are subject to immediate removal. Here, the public
184+
# git.util module, even though different, makes it less discoverable that the
185+
# expression `git.util` refers to a non-public attribute of the git module.)
186+
util, # noqa: F401
168187
)
169188
from git.util import ( # @NoMove
170189
Actor,

0 commit comments

Comments
 (0)