Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 5ca5844

Browse filesBrowse files
EliahKaganEliahKagan
committed
Fully qualify non-builtin exceptions in :raise:
This expands exceptions from git.exc and gitdb.exc in :raise: sections of docstrings, to include those qualifiers. This serves a few purposes. The main benefits are: - Immediately clarify which exceptions are not built-in ones, as not all readers are necessarily familiar with all built-in exceptions. - Distinguish exceptions defined in GitPython (in git.exc) from those defined in gitdb (in gitdb.exc). Although the gitdb exceptions GitPython uses are imported into git.exc and listed in __all__, they are still not introduced in GitPython, which is relevant for (a) preventing confusion, so developers don't think they accidentally imported a different same-named exception, (b) understanding why they do not have documentation in the generated GitPython docs. It also has these minor benefits: - May help sphinx-autodoc find them. In practice I think this is unlikely to be necessary. - Most other references, including references to classes, within docstrings in the git module, are now fully qualified, when not defined/introduced in the same module. So this is consistent with that. This consistency might be more than a minor benefit if there were a committment to keep most such refernces fully qualified, but this really should not be a goal: especially where Sphinx autodoc is guaranteed to be able to resolve them, shortening (in some cases, re-shortening) the references in the future may lead to better docstring readability.
1 parent 432ec72 commit 5ca5844
Copy full SHA for 5ca5844

File tree

8 files changed

+21
-21
lines changed
Filter options

8 files changed

+21
-21
lines changed

‎git/cmd.py

Copy file name to clipboardExpand all lines: git/cmd.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -699,7 +699,7 @@ def wait(self, stderr: Union[None, str, bytes] = b"") -> int:
699699
May deadlock if output or error pipes are used and not handled
700700
separately.
701701
702-
:raise GitCommandError:
702+
:raise git.exc.GitCommandError:
703703
If the return status is not 0.
704704
"""
705705
if stderr is None:
@@ -1091,7 +1091,7 @@ def execute(
10911091
Note that git is executed with ``LC_MESSAGES="C"`` to ensure consistent
10921092
output regardless of system language.
10931093
1094-
:raise GitCommandError:
1094+
:raise git.exc.GitCommandError:
10951095
10961096
:note:
10971097
If you add additional keyword arguments to the signature of this method,

‎git/db.py

Copy file name to clipboardExpand all lines: git/db.py
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,13 @@ def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
5656
"""
5757
:return: Full binary 20 byte sha from the given partial hexsha
5858
59-
:raise AmbiguousObjectName:
59+
:raise gitdb.exc.AmbiguousObjectName:
6060
61-
:raise BadObject:
61+
:raise gitdb.exc.BadObject:
6262
6363
:note:
64-
Currently we only raise :class:`BadObject` as git does not communicate
65-
ambiguous objects separately.
64+
Currently we only raise :class:`~gitdb.exc.BadObject` as git does not
65+
communicate ambiguous objects separately.
6666
"""
6767
try:
6868
hexsha, _typename, _size = self._git.get_object_header(partial_hexsha)

‎git/index/base.py

Copy file name to clipboardExpand all lines: git/index/base.py
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -284,7 +284,7 @@ def merge_tree(self, rhs: Treeish, base: Union[None, Treeish] = None) -> "IndexF
284284
self (containing the merge and possibly unmerged entries in case of
285285
conflicts)
286286
287-
:raise GitCommandError:
287+
:raise git.exc.GitCommandError:
288288
If there is a merge conflict. The error will be raised at the first
289289
conflicting path. If you want to have proper merge resolution to be done by
290290
yourself, you have to commit the changed index (or make a valid tree from
@@ -624,7 +624,7 @@ def write_tree(self) -> Tree:
624624
:raise ValueError:
625625
If there are no entries in the cache.
626626
627-
:raise UnmergedEntriesError:
627+
:raise git.exc.UnmergedEntriesError:
628628
"""
629629
# We obtain no lock as we just flush our contents to disk as tree.
630630
# If we are a new index, the entries access will load our data accordingly.
@@ -1077,7 +1077,7 @@ def move(
10771077
:raise ValueError:
10781078
If only one item was given.
10791079
1080-
:raise GitCommandError:
1080+
:raise git.exc.GitCommandError:
10811081
If git could not handle your request.
10821082
"""
10831083
args = []

‎git/index/fun.py

Copy file name to clipboardExpand all lines: git/index/fun.py
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ def run_commit_hook(name: str, index: "IndexFile", *args: str) -> None:
8888
:param args:
8989
Arguments passed to hook file.
9090
91-
:raise HookExecutionError:
91+
:raise git.exc.HookExecutionError:
9292
"""
9393
hp = hook_path(name, index.repo.git_dir)
9494
if not os.access(hp, os.X_OK):

‎git/objects/submodule/base.py

Copy file name to clipboardExpand all lines: git/objects/submodule/base.py
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1106,7 +1106,7 @@ def remove(
11061106
Doesn't work atomically, as failure to remove any part of the submodule will
11071107
leave an inconsistent state.
11081108
1109-
:raise InvalidGitRepositoryError:
1109+
:raise git.exc.InvalidGitRepositoryError:
11101110
Thrown if the repository cannot be deleted.
11111111
11121112
:raise OSError:
@@ -1382,7 +1382,7 @@ def module(self) -> "Repo":
13821382
"""
13831383
:return: Repo instance initialized from the repository at our submodule path
13841384
1385-
:raise InvalidGitRepositoryError:
1385+
:raise git.exc.InvalidGitRepositoryError:
13861386
If a repository was not available.
13871387
This could also mean that it was not yet initialized.
13881388
"""
@@ -1454,7 +1454,7 @@ def branch(self) -> "Head":
14541454
:return:
14551455
The branch instance that we are to checkout
14561456
1457-
:raise InvalidGitRepositoryError:
1457+
:raise git.exc.InvalidGitRepositoryError:
14581458
If our module is not yet checked out.
14591459
"""
14601460
return mkhead(self.module(), self._branch_path)

‎git/remote.py

Copy file name to clipboardExpand all lines: git/remote.py
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -801,7 +801,7 @@ def create(cls, repo: "Repo", name: str, url: str, allow_unsafe_protocols: bool
801801
:return:
802802
New :class:`Remote` instance
803803
804-
:raise GitCommandError:
804+
:raise git.exc.GitCommandError:
805805
In case an origin with that name already exists.
806806
"""
807807
scmd = "add"

‎git/repo/base.py

Copy file name to clipboardExpand all lines: git/repo/base.py
+5-5Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -202,12 +202,12 @@ def __init__(
202202
Please note that this was the default behaviour in older versions of
203203
GitPython, which is considered a bug though.
204204
205-
:raise InvalidGitRepositoryError:
205+
:raise git.exc.InvalidGitRepositoryError:
206206
207-
:raise NoSuchPathError:
207+
:raise git.exc.NoSuchPathError:
208208
209209
:return:
210-
git.Repo
210+
:class:`Repo`
211211
"""
212212

213213
epath = path or os.getenv("GIT_DIR")
@@ -893,7 +893,7 @@ def _set_alternates(self, alts: List[str]) -> None:
893893
The array of string paths representing the alternates at which git should
894894
look for objects, i.e. ``/home/user/repo/.git/objects``.
895895
896-
:raise NoSuchPathError:
896+
:raise git.exc.NoSuchPathError:
897897
898898
:note:
899899
The method does not check for the existence of the paths in `alts`, as the
@@ -1553,7 +1553,7 @@ def archive(
15531553
repository-relative path to a directory or file to place into the archive,
15541554
or a list or tuple of multiple paths.
15551555
1556-
:raise GitCommandError:
1556+
:raise git.exc.GitCommandError:
15571557
If something went wrong.
15581558
15591559
:return:

‎git/repo/fun.py

Copy file name to clipboardExpand all lines: git/repo/fun.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ def touch(filename: str) -> str:
5959
def is_git_dir(d: "PathLike") -> bool:
6060
"""This is taken from the git setup.c:is_git_directory function.
6161
62-
:raise WorkTreeRepositoryUnsupported:
62+
:raise git.exc.WorkTreeRepositoryUnsupported:
6363
If it sees a worktree directory. It's quite hacky to do that here, but at least
6464
clearly indicates that we don't support it. There is the unlikely danger to
6565
throw if we see directories which just look like a worktree dir, but are none.
@@ -234,7 +234,7 @@ def rev_parse(repo: "Repo", rev: str) -> Union["Commit", "Tag", "Tree", "Blob"]:
234234
``git rev-parse``-compatible revision specification as string. Please see
235235
http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html for details.
236236
237-
:raise BadObject:
237+
:raise gitdb.exc.BadObject:
238238
If the given revision could not be found.
239239
240240
:raise ValueError:

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.