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 bc48d26

Browse filesBrowse files
EliahKaganEliahKagan
committed
Further revise other docstrings within git.objects
1 parent 08a80aa commit bc48d26
Copy full SHA for bc48d26

File tree

Expand file treeCollapse file tree

6 files changed

+60
-57
lines changed
Filter options
Expand file treeCollapse file tree

6 files changed

+60
-57
lines changed

‎git/objects/base.py

Copy file name to clipboardExpand all lines: git/objects/base.py
+6-6Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ class Object(LazyMixin):
5858
def __init__(self, repo: "Repo", binsha: bytes):
5959
"""Initialize an object by identifying it by its binary sha.
6060
61-
All keyword arguments will be set on demand if None.
61+
All keyword arguments will be set on demand if ``None``.
6262
6363
:param repo:
6464
Repository this object is located in.
@@ -83,7 +83,7 @@ def new(cls, repo: "Repo", id: Union[str, "Reference"]) -> Commit_ish:
8383
input id may have been a `~git.refs.reference.Reference` or rev-spec.
8484
8585
:param id:
86-
:class:`~git.refs.reference.Reference`, rev-spec, or hexsha
86+
:class:`~git.refs.reference.Reference`, rev-spec, or hexsha.
8787
8888
:note:
8989
This cannot be a ``__new__`` method as it would always call :meth:`__init__`
@@ -119,13 +119,13 @@ def _set_cache_(self, attr: str) -> None:
119119
super()._set_cache_(attr)
120120

121121
def __eq__(self, other: Any) -> bool:
122-
""":return: True if the objects have the same SHA1"""
122+
""":return: ``True`` if the objects have the same SHA1"""
123123
if not hasattr(other, "binsha"):
124124
return False
125125
return self.binsha == other.binsha
126126

127127
def __ne__(self, other: Any) -> bool:
128-
""":return: True if the objects do not have the same SHA1"""
128+
""":return: ``True`` if the objects do not have the same SHA1"""
129129
if not hasattr(other, "binsha"):
130130
return True
131131
return self.binsha != other.binsha
@@ -199,8 +199,8 @@ def __init__(
199199
20 byte sha1.
200200
201201
:param mode:
202-
The stat compatible file mode as int, use the :mod:`stat` module to evaluate
203-
the information.
202+
The stat-compatible file mode as :class:`int`.
203+
Use the :mod:`stat` module to evaluate the information.
204204
205205
:param path:
206206
The path to the file in the file system, relative to the git repository

‎git/objects/blob.py

Copy file name to clipboardExpand all lines: git/objects/blob.py
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ class Blob(base.IndexObject):
2727
@property
2828
def mime_type(self) -> str:
2929
"""
30-
:return: String describing the mime type of this file (based on the filename)
30+
:return:
31+
String describing the mime type of this file (based on the filename)
3132
3233
:note:
3334
Defaults to ``text/plain`` in case the actual file type is unknown.

‎git/objects/commit.py

Copy file name to clipboardExpand all lines: git/objects/commit.py
+14-14Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -108,20 +108,20 @@ def __init__(
108108
encoding: Union[str, None] = None,
109109
gpgsig: Union[str, None] = None,
110110
) -> None:
111-
R"""Instantiate a new :class:`Commit`. All keyword arguments taking None as
111+
R"""Instantiate a new :class:`Commit`. All keyword arguments taking ``None`` as
112112
default will be implicitly set on first query.
113113
114114
:param binsha:
115-
20 byte sha1
115+
20 byte sha1.
116116
117117
:param parents: tuple(Commit, ...)
118118
A tuple of commit ids or actual :class:`Commit`\s.
119119
120120
:param tree:
121121
A :class:`~git.objects.tree.Tree` object.
122122
123-
:param author: :class:`~git.util.Actor`
124-
The author Actor object
123+
:param author:
124+
The author :class:`~git.util.Actor` object.
125125
126126
:param authored_date: int_seconds_since_epoch
127127
The authored DateTime - use :func:`time.gmtime` to convert it into a
@@ -130,8 +130,8 @@ def __init__(
130130
:param author_tz_offset: int_seconds_west_of_utc
131131
The timezone that the `authored_date` is in.
132132
133-
:param committer: :class:`~git.util.Actor`
134-
The committer string.
133+
:param committer:
134+
The committer string, as an :class:`~git.util.Actor` object.
135135
136136
:param committed_date: int_seconds_since_epoch
137137
The committed DateTime - use :func:`time.gmtime` to convert it into a
@@ -209,7 +209,7 @@ def _calculate_sha_(cls, repo: "Repo", commit: "Commit") -> bytes:
209209
return istream.binsha
210210

211211
def replace(self, **kwargs: Any) -> "Commit":
212-
"""Create new commit object from existing commit object.
212+
"""Create new commit object from an existing commit object.
213213
214214
Any values provided as keyword arguments will replace the corresponding
215215
attribute in the new object.
@@ -295,7 +295,7 @@ def iter_items(
295295
R"""Find all commits matching the given criteria.
296296
297297
:param repo:
298-
The Repo
298+
The :class:`~git.repo.base.Repo`.
299299
300300
:param rev:
301301
Revision specifier, see git-rev-parse for viable options.
@@ -378,7 +378,7 @@ def stats(self) -> Stats:
378378

379379
@property
380380
def trailers(self) -> Dict[str, str]:
381-
"""Get the trailers of the message as a dictionary
381+
"""Deprecated. Get the trailers of the message as a dictionary.
382382
383383
:note: This property is deprecated, please use either :attr:`trailers_list` or
384384
:attr:`trailers_dict``.
@@ -396,7 +396,7 @@ def trailers_list(self) -> List[Tuple[str, str]]:
396396
Git messages can contain trailer information that are similar to RFC 822 e-mail
397397
headers (see: https://git-scm.com/docs/git-interpret-trailers).
398398
399-
This functions calls ``git interpret-trailers --parse`` onto the message to
399+
This function calls ``git interpret-trailers --parse`` onto the message to
400400
extract the trailer information, returns the raw trailer data as a list.
401401
402402
Valid message with trailer::
@@ -444,7 +444,7 @@ def trailers_dict(self) -> Dict[str, List[str]]:
444444
Git messages can contain trailer information that are similar to RFC 822 e-mail
445445
headers (see: https://git-scm.com/docs/git-interpret-trailers).
446446
447-
This functions calls ``git interpret-trailers --parse`` onto the message to
447+
This function calls ``git interpret-trailers --parse`` onto the message to
448448
extract the trailer information. The key value pairs are stripped of leading and
449449
trailing whitespaces before they get saved into a dictionary.
450450
@@ -481,7 +481,7 @@ def trailers_dict(self) -> Dict[str, List[str]]:
481481
def _iter_from_process_or_stream(cls, repo: "Repo", proc_or_stream: Union[Popen, IO]) -> Iterator["Commit"]:
482482
"""Parse out commit information into a list of :class:`Commit` objects.
483483
484-
We expect one-line per commit, and parse the actual commit information directly
484+
We expect one line per commit, and parse the actual commit information directly
485485
from our lighting fast object database.
486486
487487
:param proc:
@@ -555,11 +555,11 @@ def create_from_tree(
555555
:param parent_commits:
556556
Optional :class:`Commit` objects to use as parents for the new commit. If
557557
empty list, the commit will have no parents at all and become a root commit.
558-
If None, the current head commit will be the parent of the new commit
558+
If ``None``, the current head commit will be the parent of the new commit
559559
object.
560560
561561
:param head:
562-
If True, the HEAD will be advanced to the new commit automatically.
562+
If ``True``, the HEAD will be advanced to the new commit automatically.
563563
Otherwise the HEAD will remain pointing on the previous commit. This could
564564
lead to undesired results when diffing files.
565565

‎git/objects/fun.py

Copy file name to clipboardExpand all lines: git/objects/fun.py
+8-6Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ def tree_entries_from_data(data: bytes) -> List[EntryTup]:
128128

129129

130130
def _find_by_name(tree_data: MutableSequence[EntryTupOrNone], name: str, is_dir: bool, start_at: int) -> EntryTupOrNone:
131-
"""Return data entry matching the given name and tree mode or None.
131+
"""Return data entry matching the given name and tree mode or ``None``.
132132
133133
Before the item is returned, the respective data item is set None in the `tree_data`
134134
list to mark it done.
@@ -172,7 +172,8 @@ def traverse_trees_recursive(
172172
odb: "GitCmdObjectDB", tree_shas: Sequence[Union[bytes, None]], path_prefix: str
173173
) -> List[Tuple[EntryTupOrNone, ...]]:
174174
"""
175-
:return: list of list with entries according to the given binary tree-shas.
175+
:return:
176+
List of list with entries according to the given binary tree-shas.
176177
177178
The result is encoded in a list
178179
of n tuple|None per blob/commit, (n == len(tree_shas)), where:
@@ -181,12 +182,12 @@ def traverse_trees_recursive(
181182
* [1] == mode as int
182183
* [2] == path relative to working tree root
183184
184-
The entry tuple is None if the respective blob/commit did not exist in the given
185-
tree.
185+
The entry tuple is ``None`` if the respective blob/commit did not exist in the
186+
given tree.
186187
187188
:param tree_shas:
188189
Iterable of shas pointing to trees. All trees must be on the same level. A
189-
tree-sha may be None in which case None.
190+
tree-sha may be ``None`` in which case ``None``.
190191
191192
:param path_prefix:
192193
A prefix to be added to the returned paths on this level.
@@ -257,7 +258,8 @@ def traverse_trees_recursive(
257258

258259
def traverse_tree_recursive(odb: "GitCmdObjectDB", tree_sha: bytes, path_prefix: str) -> List[EntryTup]:
259260
"""
260-
:return: list of entries of the tree pointed to by the binary `tree_sha`.
261+
:return:
262+
List of entries of the tree pointed to by the binary `tree_sha`.
261263
262264
An entry has the following format:
263265

‎git/objects/tree.py

Copy file name to clipboardExpand all lines: git/objects/tree.py
+11-12Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -97,17 +97,17 @@ def add(self, sha: bytes, mode: int, name: str, force: bool = False) -> "TreeMod
9797
9898
If an item with the given name already exists, nothing will be done, but a
9999
:class:`ValueError` will be raised if the sha and mode of the existing item do
100-
not match the one you add, unless `force` is True.
100+
not match the one you add, unless `force` is ``True``.
101101
102102
:param sha:
103103
The 20 or 40 byte sha of the item to add.
104104
105105
:param mode:
106-
int representing the stat compatible mode of the item.
106+
:class:`int` representing the stat-compatible mode of the item.
107107
108108
:param force:
109-
If True, an item with your name and information will overwrite any existing
110-
item with the same name, no matter which information it has.
109+
If ``True``, an item with your name and information will overwrite any
110+
existing item with the same name, no matter which information it has.
111111
112112
:return:
113113
self
@@ -164,11 +164,10 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
164164
R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and
165165
other :class:`~git.objects.tree.Tree`\s.
166166
167-
Tree as a list::
167+
Tree as a list:
168168
169-
Access a specific blob using the ``tree['filename']`` notation.
170-
171-
You may likewise access by index, like ``blob = tree[0]``.
169+
* Access a specific blob using the ``tree['filename']`` notation.
170+
* You may likewise access by index, like ``blob = tree[0]``.
172171
"""
173172

174173
type: Literal["tree"] = "tree"
@@ -235,7 +234,7 @@ def join(self, file: str) -> IndexObjUnion:
235234
or :class:`~git.objects.submodule.base.Submodule`
236235
237236
:raise KeyError:
238-
If the given file or tree does not exist in tree.
237+
If the given file or tree does not exist in this tree.
239238
"""
240239
msg = "Blob or Tree named %r not found"
241240
if "/" in file:
@@ -275,12 +274,12 @@ def __truediv__(self, file: str) -> IndexObjUnion:
275274

276275
@property
277276
def trees(self) -> List["Tree"]:
278-
""":return: list(Tree, ...) list of trees directly below this tree"""
277+
""":return: list(Tree, ...) List of trees directly below this tree"""
279278
return [i for i in self if i.type == "tree"]
280279

281280
@property
282281
def blobs(self) -> List[Blob]:
283-
""":return: list(Blob, ...) list of blobs directly below this tree"""
282+
""":return: list(Blob, ...) List of blobs directly below this tree"""
284283
return [i for i in self if i.type == "blob"]
285284

286285
@property
@@ -342,7 +341,7 @@ def list_traverse(self, *args: Any, **kwargs: Any) -> IterableList[IndexObjUnion
342341
:class:`~git.util.IterableList`IterableList with the results of the
343342
traversal as produced by :meth:`traverse`
344343
345-
Tree -> IterableList[Union['Submodule', 'Tree', 'Blob']]
344+
Tree -> IterableList[Union[Submodule, Tree, Blob]]
346345
"""
347346
return super()._list_traverse(*args, **kwargs)
348347

‎git/objects/util.py

Copy file name to clipboardExpand all lines: git/objects/util.py
+19-18Lines changed: 19 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -95,9 +95,9 @@ def mode_str_to_int(modestr: Union[bytes, str]) -> int:
9595
used.
9696
9797
:return:
98-
String identifying a mode compatible to the mode methods ids of the stat module
99-
regarding the rwx permissions for user, group and other, special flags and file
100-
system flags, such as whether it is a symlink.
98+
String identifying a mode compatible to the mode methods ids of the :mod:`stat`
99+
module regarding the rwx permissions for user, group and other, special flags
100+
and file system flags, such as whether it is a symlink.
101101
"""
102102
mode = 0
103103
for iteration, char in enumerate(reversed(modestr[-6:])):
@@ -401,7 +401,7 @@ class Tree:: (cls, Tree) -> Tuple[Tree, ...]
401401
def list_traverse(self, *args: Any, **kwargs: Any) -> Any:
402402
"""Traverse self and collect all items found.
403403
404-
Calling this directly only the abstract base class, including via a ``super()``
404+
Calling this directly on the abstract base class, including via a ``super()``
405405
proxy, is deprecated. Only overridden implementations should be called.
406406
"""
407407
warnings.warn(
@@ -418,12 +418,13 @@ def _list_traverse(
418418
) -> IterableList[Union["Commit", "Submodule", "Tree", "Blob"]]:
419419
"""Traverse self and collect all items found.
420420
421-
:return: :class:`~git.util.IterableList` with the results of the traversal as
421+
:return:
422+
:class:`~git.util.IterableList` with the results of the traversal as
422423
produced by :meth:`traverse`::
423424
424-
Commit -> IterableList["Commit"]
425-
Submodule -> IterableList["Submodule"]
426-
Tree -> IterableList[Union["Submodule", "Tree", "Blob"]]
425+
Commit -> IterableList[Commit]
426+
Submodule -> IterableList[Submodule]
427+
Tree -> IterableList[Union[Submodule, Tree, Blob]]
427428
"""
428429
# Commit and Submodule have id.__attribute__ as IterableObj.
429430
# Tree has id.__attribute__ inherited from IndexObject.
@@ -476,32 +477,32 @@ def _traverse(
476477
"""Iterator yielding items found when traversing self.
477478
478479
:param predicate:
479-
A function ``f(i,d)`` that returns False if item i at depth ``d`` should not
480-
be included in the result.
480+
A function ``f(i,d)`` that returns ``False`` if item i at depth ``d`` should
481+
not be included in the result.
481482
482483
:param prune:
483-
A function ``f(i,d)`` that returns True if the search should stop at item
484-
``i`` at depth ``d``. Item ``i`` will not be returned.
484+
A function ``f(i,d)`` that returns ``True`` if the search should stop at
485+
item ``i`` at depth ``d``. Item ``i`` will not be returned.
485486
486487
:param depth:
487488
Defines at which level the iteration should not go deeper if -1, there is no
488489
limit if 0, you would effectively only get self, the root of the iteration
489490
i.e. if 1, you would only get the first level of predecessors/successors.
490491
491492
:param branch_first:
492-
If True, items will be returned branch first, otherwise depth first.
493+
If ``True``, items will be returned branch first, otherwise depth first.
493494
494495
:param visit_once:
495-
If True, items will only be returned once, although they might be
496+
If ``True``, items will only be returned once, although they might be
496497
encountered several times. Loops are prevented that way.
497498
498499
:param ignore_self:
499-
If True, self will be ignored and automatically pruned from the result.
500-
Otherwise it will be the first item to be returned. If `as_edge` is True, the
501-
source of the first edge is None
500+
If ``True``, self will be ignored and automatically pruned from the result.
501+
Otherwise it will be the first item to be returned. If `as_edge` is
502+
``True``, the source of the first edge is ``None``.
502503
503504
:param as_edge:
504-
If True, return a pair of items, first being the source, second the
505+
If ``True``, return a pair of items, first being the source, second the
505506
destination, i.e. tuple(src, dest) with the edge spanning from source to
506507
destination.
507508

0 commit comments

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