Skip to content

Navigation Menu

Sign in

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 7fbfc77

Browse filesBrowse files
ByronByron
authored
Merge pull request #1850 from EliahKagan/copyedit
Revise docstrings, comments, and a few messages
2 parents 87b8035 + 37c93de commit 7fbfc77
Copy full SHA for 7fbfc77

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Dismiss banner

50 files changed

+3105
-2078
lines changed

‎git/__init__.py

Copy file name to clipboardExpand all lines: git/__init__.py
+13-8Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -122,18 +122,23 @@
122122
def refresh(path: Optional[PathLike] = None) -> None:
123123
"""Convenience method for setting the git executable path.
124124
125-
:param path: Optional path to the Git executable. If not absolute, it is resolved
125+
:param path:
126+
Optional path to the Git executable. If not absolute, it is resolved
126127
immediately, relative to the current directory.
127128
128-
:note: The *path* parameter is usually omitted and cannot be used to specify a
129-
custom command whose location is looked up in a path search on each call. See
130-
:meth:`Git.refresh` for details on how to achieve this.
129+
:note:
130+
The `path` parameter is usually omitted and cannot be used to specify a custom
131+
command whose location is looked up in a path search on each call. See
132+
:meth:`Git.refresh <git.cmd.Git.refresh>` for details on how to achieve this.
131133
132-
:note: This calls :meth:`Git.refresh` and sets other global configuration according
133-
to the effect of doing so. As such, this function should usually be used instead
134-
of using :meth:`Git.refresh` or :meth:`FetchInfo.refresh` directly.
134+
:note:
135+
This calls :meth:`Git.refresh <git.cmd.Git.refresh>` and sets other global
136+
configuration according to the effect of doing so. As such, this function should
137+
usually be used instead of using :meth:`Git.refresh <git.cmd.Git.refresh>` or
138+
:meth:`FetchInfo.refresh <git.remote.FetchInfo.refresh>` directly.
135139
136-
:note: This function is called automatically, with no arguments, at import time.
140+
:note:
141+
This function is called automatically, with no arguments, at import time.
137142
"""
138143
global GIT_OK
139144
GIT_OK = False

‎git/cmd.py

Copy file name to clipboardExpand all lines: git/cmd.py
+204-149Lines changed: 204 additions & 149 deletions
Large diffs are not rendered by default.

‎git/compat.py

Copy file name to clipboardExpand all lines: git/compat.py
+9-6Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,9 @@
3535
:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
3636
used.
3737
38-
:note: ``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To
39-
detect Cygwin, use ``sys.platform == "cygwin"``.
38+
:note:
39+
``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To detect
40+
Cygwin, use ``sys.platform == "cygwin"``.
4041
"""
4142

4243
is_posix = os.name == "posix"
@@ -46,9 +47,10 @@
4647
:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
4748
used.
4849
49-
:note: For POSIX systems, more detailed information is available in
50-
:attr:`sys.platform`, while :attr:`os.name` is always ``"posix"`` on such systems,
51-
including macOS (Darwin).
50+
:note:
51+
For POSIX systems, more detailed information is available in :attr:`sys.platform`,
52+
while :attr:`os.name` is always ``"posix"`` on such systems, including macOS
53+
(Darwin).
5254
"""
5355

5456
is_darwin = sys.platform == "darwin"
@@ -57,7 +59,8 @@
5759
This is deprecated because it clearer to write out :attr:`os.name` or
5860
:attr:`sys.platform` checks explicitly.
5961
60-
:note: For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
62+
:note:
63+
For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
6164
``sys.platform == "darwin"`.
6265
"""
6366

‎git/config.py

Copy file name to clipboardExpand all lines: git/config.py
+111-71Lines changed: 111 additions & 71 deletions
Large diffs are not rendered by default.

‎git/db.py

Copy file name to clipboardExpand all lines: git/db.py
+8-8Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,6 @@ class GitCmdObjectDB(LooseObjectDB):
3030
objects, pack files and an alternates file.
3131
3232
It will create objects only in the loose object database.
33-
34-
:note: For now, we use the git command to do all the lookup, just until we
35-
have packs and the other implementations.
3633
"""
3734

3835
def __init__(self, root_path: PathLike, git: "Git") -> None:
@@ -53,13 +50,16 @@ def stream(self, binsha: bytes) -> OStream:
5350

5451
def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
5552
"""
56-
:return: Full binary 20 byte sha from the given partial hexsha
53+
:return:
54+
Full binary 20 byte sha from the given partial hexsha
55+
56+
:raise gitdb.exc.AmbiguousObjectName:
5757
58-
:raise AmbiguousObjectName:
59-
:raise BadObject:
58+
:raise gitdb.exc.BadObject:
6059
61-
:note: Currently we only raise :class:`BadObject` as git does not communicate
62-
AmbiguousObjects separately.
60+
:note:
61+
Currently we only raise :class:`~gitdb.exc.BadObject` as git does not
62+
communicate ambiguous objects separately.
6363
"""
6464
try:
6565
hexsha, _typename, _size = self._git.get_object_header(partial_hexsha)

‎git/diff.py

Copy file name to clipboardExpand all lines: git/diff.py
+58-40Lines changed: 58 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,9 @@ class Diffable:
8484
compatible type.
8585
8686
:note:
87-
Subclasses require a repo member as it is the case for Object instances, for
88-
practical reasons we do not derive from Object.
87+
Subclasses require a repo member as it is the case for
88+
:class:`~git.objects.base.Object` instances, for practical reasons we do not
89+
derive from :class:`~git.objects.base.Object`.
8990
"""
9091

9192
__slots__ = ()
@@ -111,37 +112,38 @@ def diff(
111112
create_patch: bool = False,
112113
**kwargs: Any,
113114
) -> "DiffIndex":
114-
"""Create diffs between two items being trees, trees and index or an
115-
index and the working tree. Detects renames automatically.
115+
"""Create diffs between two items being trees, trees and index or an index and
116+
the working tree. Detects renames automatically.
116117
117118
:param other:
118119
This the item to compare us with.
119120
120-
* If None, we will be compared to the working tree.
121+
* If ``None``, we will be compared to the working tree.
121122
* If :class:`~git.index.base.Treeish`, it will be compared against the
122123
respective tree.
123-
* If :class:`~Diffable.Index`, it will be compared against the index.
124+
* If :class:`Diffable.Index`, it will be compared against the index.
124125
* If :attr:`git.NULL_TREE`, it will compare against the empty tree.
125-
* It defaults to :class:`~Diffable.Index` so that the method will not by
126+
* It defaults to :class:`Diffable.Index` so that the method will not by
126127
default fail on bare repositories.
127128
128129
:param paths:
129130
This a list of paths or a single path to limit the diff to. It will only
130131
include at least one of the given path or paths.
131132
132133
:param create_patch:
133-
If True, the returned :class:`Diff` contains a detailed patch that if
134+
If ``True``, the returned :class:`Diff` contains a detailed patch that if
134135
applied makes the self to other. Patches are somewhat costly as blobs have
135136
to be read and diffed.
136137
137138
:param kwargs:
138-
Additional arguments passed to git-diff, such as ``R=True`` to swap both
139+
Additional arguments passed to ``git diff``, such as ``R=True`` to swap both
139140
sides of the diff.
140141
141-
:return: git.DiffIndex
142+
:return:
143+
:class:`DiffIndex`
142144
143145
:note:
144-
On a bare repository, 'other' needs to be provided as
146+
On a bare repository, `other` needs to be provided as
145147
:class:`~Diffable.Index`, or as :class:`~git.objects.tree.Tree` or
146148
:class:`~git.objects.commit.Commit`, or a git command error will occur.
147149
"""
@@ -184,7 +186,7 @@ def diff(
184186

185187
args.insert(0, self)
186188

187-
# paths is list here, or None.
189+
# paths is a list here, or None.
188190
if paths:
189191
args.append("--")
190192
args.extend(paths)
@@ -204,7 +206,7 @@ def diff(
204206

205207

206208
class DiffIndex(List[T_Diff]):
207-
"""An Index for diffs, allowing a list of Diffs to be queried by the diff
209+
R"""An Index for diffs, allowing a list of :class:`Diff`\s to be queried by the diff
208210
properties.
209211
210212
The class improves the diff handling convenience.
@@ -256,34 +258,34 @@ def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]:
256258
class Diff:
257259
"""A Diff contains diff information between two Trees.
258260
259-
It contains two sides a and b of the diff, members are prefixed with
260-
"a" and "b" respectively to indicate that.
261+
It contains two sides a and b of the diff. Members are prefixed with "a" and "b"
262+
respectively to indicate that.
261263
262264
Diffs keep information about the changed blob objects, the file mode, renames,
263265
deletions and new files.
264266
265-
There are a few cases where None has to be expected as member variable value:
267+
There are a few cases where ``None`` has to be expected as member variable value:
266268
267-
``New File``::
269+
New File::
268270
269271
a_mode is None
270272
a_blob is None
271273
a_path is None
272274
273-
``Deleted File``::
275+
Deleted File::
274276
275277
b_mode is None
276278
b_blob is None
277279
b_path is None
278280
279-
``Working Tree Blobs``
281+
Working Tree Blobs:
280282
281283
When comparing to working trees, the working tree blob will have a null hexsha
282-
as a corresponding object does not yet exist. The mode will be null as well.
283-
The path will be available, though.
284+
as a corresponding object does not yet exist. The mode will be null as well. The
285+
path will be available, though.
284286
285-
If it is listed in a diff, the working tree version of the file must
286-
differ from the version in the index or tree, and hence has been modified.
287+
If it is listed in a diff, the working tree version of the file must differ from
288+
the version in the index or tree, and hence has been modified.
287289
"""
288290

289291
# Precompiled regex.
@@ -467,17 +469,20 @@ def rename_to(self) -> Optional[str]:
467469

468470
@property
469471
def renamed(self) -> bool:
470-
"""
471-
:return: True if the blob of our diff has been renamed
472+
"""Deprecated, use :attr:`renamed_file` instead.
473+
474+
:return:
475+
``True`` if the blob of our diff has been renamed
472476
473-
:note: This property is deprecated.
477+
:note:
478+
This property is deprecated.
474479
Please use the :attr:`renamed_file` property instead.
475480
"""
476481
return self.renamed_file
477482

478483
@property
479484
def renamed_file(self) -> bool:
480-
""":return: True if the blob of our diff has been renamed"""
485+
""":return: ``True`` if the blob of our diff has been renamed"""
481486
return self.rename_from != self.rename_to
482487

483488
@classmethod
@@ -495,11 +500,18 @@ def _pick_best_path(cls, path_match: bytes, rename_match: bytes, path_fallback_m
495500

496501
@classmethod
497502
def _index_from_patch_format(cls, repo: "Repo", proc: Union["Popen", "Git.AutoInterrupt"]) -> DiffIndex:
498-
"""Create a new DiffIndex from the given process output which must be in patch format.
503+
"""Create a new :class:`DiffIndex` from the given process output which must be
504+
in patch format.
505+
506+
:param repo:
507+
The repository we are operating on.
499508
500-
:param repo: The repository we are operating on
501-
:param proc: ``git diff`` process to read from (supports :class:`Git.AutoInterrupt` wrapper)
502-
:return: git.DiffIndex
509+
:param proc:
510+
``git diff`` process to read from
511+
(supports :class:`Git.AutoInterrupt <git.cmd.Git.AutoInterrupt>` wrapper).
512+
513+
:return:
514+
:class:`DiffIndex`
503515
"""
504516

505517
# FIXME: Here SLURPING raw, need to re-phrase header-regexes linewise.
@@ -540,14 +552,14 @@ def _index_from_patch_format(cls, repo: "Repo", proc: Union["Popen", "Git.AutoIn
540552
a_path = cls._pick_best_path(a_path, rename_from, a_path_fallback)
541553
b_path = cls._pick_best_path(b_path, rename_to, b_path_fallback)
542554

543-
# Our only means to find the actual text is to see what has not been matched by our regex,
544-
# and then retro-actively assign it to our index.
555+
# Our only means to find the actual text is to see what has not been matched
556+
# by our regex, and then retro-actively assign it to our index.
545557
if previous_header is not None:
546558
index[-1].diff = text[previous_header.end() : _header.start()]
547559
# END assign actual diff
548560

549-
# Make sure the mode is set if the path is set. Otherwise the resulting blob is invalid.
550-
# We just use the one mode we should have parsed.
561+
# Make sure the mode is set if the path is set. Otherwise the resulting blob
562+
# is invalid. We just use the one mode we should have parsed.
551563
a_mode = old_mode or deleted_file_mode or (a_path and (b_mode or new_mode or new_file_mode))
552564
b_mode = b_mode or new_mode or new_file_mode or (b_path and a_mode)
553565
index.append(
@@ -611,7 +623,7 @@ def _handle_diff_line(lines_bytes: bytes, repo: "Repo", index: DiffIndex) -> Non
611623
rename_from = None
612624
rename_to = None
613625

614-
# NOTE: We cannot conclude from the existence of a blob to change type
626+
# NOTE: We cannot conclude from the existence of a blob to change type,
615627
# as diffs with the working do not have blobs yet.
616628
if change_type == "D":
617629
b_blob_id = None # Optional[str]
@@ -655,11 +667,17 @@ def _handle_diff_line(lines_bytes: bytes, repo: "Repo", index: DiffIndex) -> Non
655667

656668
@classmethod
657669
def _index_from_raw_format(cls, repo: "Repo", proc: "Popen") -> "DiffIndex":
658-
"""Create a new DiffIndex from the given process output which must be in raw format.
670+
"""Create a new :class:`DiffIndex` from the given process output which must be
671+
in raw format.
672+
673+
:param repo:
674+
The repository we are operating on.
659675
660-
:param repo: The repository we are operating on
661-
:param proc: Process to read output from
662-
:return: git.DiffIndex
676+
:param proc:
677+
Process to read output from.
678+
679+
:return:
680+
:class:`DiffIndex`
663681
"""
664682
# handles
665683
# :100644 100644 687099101... 37c5e30c8... M .gitignore

‎git/exc.py

Copy file name to clipboardExpand all lines: git/exc.py
+11-7Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -81,16 +81,20 @@ class UnsafeOptionError(GitError):
8181

8282

8383
class CommandError(GitError):
84-
"""Base class for exceptions thrown at every stage of `Popen()` execution.
84+
"""Base class for exceptions thrown at every stage of :class:`~subprocess.Popen`
85+
execution.
8586
8687
:param command:
8788
A non-empty list of argv comprising the command-line.
8889
"""
8990

90-
#: A unicode print-format with 2 `%s for `<cmdline>` and the rest,
91-
#: e.g.
92-
#: "'%s' failed%s"
9391
_msg = "Cmd('%s') failed%s"
92+
"""Format string with 2 ``%s`` for ``<cmdline>`` and the rest.
93+
94+
For example: ``"'%s' failed%s"``
95+
96+
Subclasses may override this attribute, provided it is still in this form.
97+
"""
9498

9599
def __init__(
96100
self,
@@ -132,8 +136,8 @@ def __str__(self) -> str:
132136

133137

134138
class GitCommandNotFound(CommandError):
135-
"""Thrown if we cannot find the `git` executable in the PATH or at the path given by
136-
the GIT_PYTHON_GIT_EXECUTABLE environment variable."""
139+
"""Thrown if we cannot find the ``git`` executable in the :envvar:`PATH` or at the
140+
path given by the :envvar:`GIT_PYTHON_GIT_EXECUTABLE` environment variable."""
137141

138142
def __init__(self, command: Union[List[str], Tuple[str], str], cause: Union[str, Exception]) -> None:
139143
super().__init__(command, cause)
@@ -184,7 +188,7 @@ def __str__(self) -> str:
184188

185189

186190
class CacheError(GitError):
187-
"""Base for all errors related to the git index, which is called cache
191+
"""Base for all errors related to the git index, which is called "cache"
188192
internally."""
189193

190194

0 commit comments

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