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 a0fa2bd

Browse filesBrowse files
EliahKaganEliahKagan
committed
Improve deprecation messages and other docstrings
- Fix spacing in deprecation messages. - Update versions in deprecation messages to reflect SemVer. - Add and fix up docstrings for methods with some deprecated uses. - Add a couple missing docstrings on nearby attributes and methods. - Convert is_<platform> deprecation comment to three docstrings. - Avoid wrongly claiming is_darwin still uses os.name (see #1732). - Convert some other comments to docstrings. - Make disembodied """-strings docstrings or comments, per intent. - Move some comments that were misplaced during auto-formatting. This commit builds on the changes in 94a85d1 (#1782).
1 parent 86d0177 commit a0fa2bd
Copy full SHA for a0fa2bd

File tree

5 files changed

+99
-63
lines changed
Filter options

5 files changed

+99
-63
lines changed

‎git/compat.py

Copy file name to clipboardExpand all lines: git/compat.py
+30-7Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,18 +28,41 @@
2828
# ---------------------------------------------------------------------------
2929

3030

31-
# DEPRECATED attributes providing shortcuts to operating system checks based on os.name.
32-
#
33-
# These are deprecated because it is clearer, and helps avoid bugs, to write out the
34-
# os.name or sys.platform checks explicitly, especially in cases where it matters which
35-
# is used. For example, is_win is False on Cygwin, but is often assumed True. To detect
36-
# Cygwin, use sys.platform == "cygwin". (Also, in the past, is_darwin was unreliable.)
37-
#
3831
is_win = os.name == "nt"
32+
"""Deprecated alias for ``os.name == "nt"`` to check for native Windows.
33+
34+
This is deprecated because it is clearer to write out :attr:`os.name` or
35+
:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
36+
used.
37+
38+
:note: ``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To
39+
detect Cygwin, use ``sys.platform == "cygwin"``.
40+
"""
41+
3942
is_posix = os.name == "posix"
43+
"""Deprecated alias for ``os.name == "posix"`` to check for Unix-like ("POSIX") systems.
44+
45+
This is deprecated because it clearer to write out :attr:`os.name` or
46+
:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
47+
used.
48+
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).
52+
"""
53+
4054
is_darwin = sys.platform == "darwin"
55+
"""Deprecated alias for ``sys.platform == "darwin"`` to check for macOS (Darwin).
56+
57+
This is deprecated because it clearer to write out :attr:`os.name` or
58+
:attr:`sys.platform` checks explicitly.
59+
60+
:note: For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
61+
``sys.platform == "darwin"`.
62+
"""
4163

4264
defenc = sys.getfilesystemencoding()
65+
"""The encoding used to convert between Unicode and bytes filenames."""
4366

4467

4568
@overload

‎git/diff.py

Copy file name to clipboardExpand all lines: git/diff.py
+9-6Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
55

66
import re
7+
78
from git.cmd import handle_process_output
89
from git.compat import defenc
910
from git.util import finalize_process, hex_to_bin
@@ -208,13 +209,15 @@ class DiffIndex(List[T_Diff]):
208209
The class improves the diff handling convenience.
209210
"""
210211

211-
# Change type invariant identifying possible ways a blob can have changed:
212-
# A = Added
213-
# D = Deleted
214-
# R = Renamed
215-
# M = Modified
216-
# T = Changed in the type
217212
change_type = ("A", "C", "D", "R", "M", "T")
213+
"""Change type invariant identifying possible ways a blob can have changed:
214+
215+
* ``A`` = Added
216+
* ``D`` = Deleted
217+
* ``R`` = Renamed
218+
* ``M`` = Modified
219+
* ``T`` = Changed in the type
220+
"""
218221

219222
def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]:
220223
"""

‎git/objects/commit.py

Copy file name to clipboardExpand all lines: git/objects/commit.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -352,8 +352,8 @@ def stats(self) -> Stats:
352352
def trailers(self) -> Dict[str, str]:
353353
"""Get the trailers of the message as a dictionary
354354
355-
:note: This property is deprecated, please use either ``Commit.trailers_list``
356-
or ``Commit.trailers_dict``.
355+
:note: This property is deprecated, please use either :attr:`trailers_list` or
356+
:attr:`trailers_dict``.
357357
358358
:return:
359359
Dictionary containing whitespace stripped trailer information. Only contains

‎git/objects/util.py

Copy file name to clipboardExpand all lines: git/objects/util.py
+54-44Lines changed: 54 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,9 @@ class TraverseNT(NamedTuple):
6262
T_TIobj = TypeVar("T_TIobj", bound="TraversableIterableObj") # For TraversableIterableObj.traverse()
6363

6464
TraversedTup = Union[
65-
Tuple[Union["Traversable", None], "Traversable"], # For commit, submodule
66-
"TraversedTreeTup",
67-
] # for tree.traverse()
65+
Tuple[Union["Traversable", None], "Traversable"], # For Commit, Submodule.
66+
"TraversedTreeTup", # For Tree.traverse().
67+
]
6868

6969
# --------------------------------------------------------------------
7070

@@ -380,11 +380,15 @@ class Tree:: (cls, Tree) -> Tuple[Tree, ...]
380380

381381
@abstractmethod
382382
def list_traverse(self, *args: Any, **kwargs: Any) -> Any:
383-
""" """
383+
"""Traverse self and collect all items found.
384+
385+
Calling this directly only the abstract base class, including via a ``super()``
386+
proxy, is deprecated. Only overridden implementations should be called.
387+
"""
384388
warnings.warn(
385389
"list_traverse() method should only be called from subclasses."
386-
"Calling from Traversable abstract class will raise NotImplementedError in 3.1.20"
387-
"Builtin sublclasses are 'Submodule', 'Tree' and 'Commit",
390+
" Calling from Traversable abstract class will raise NotImplementedError in 4.0.0."
391+
" The concrete subclasses in GitPython itself are 'Commit', 'RootModule', 'Submodule', and 'Tree'.",
388392
DeprecationWarning,
389393
stacklevel=2,
390394
)
@@ -393,12 +397,14 @@ def list_traverse(self, *args: Any, **kwargs: Any) -> Any:
393397
def _list_traverse(
394398
self, as_edge: bool = False, *args: Any, **kwargs: Any
395399
) -> IterableList[Union["Commit", "Submodule", "Tree", "Blob"]]:
396-
"""
400+
"""Traverse self and collect all items found.
401+
397402
:return: IterableList with the results of the traversal as produced by
398-
traverse()
399-
Commit -> IterableList['Commit']
400-
Submodule -> IterableList['Submodule']
401-
Tree -> IterableList[Union['Submodule', 'Tree', 'Blob']]
403+
:meth:`traverse`::
404+
405+
Commit -> IterableList['Commit']
406+
Submodule -> IterableList['Submodule']
407+
Tree -> IterableList[Union['Submodule', 'Tree', 'Blob']]
402408
"""
403409
# Commit and Submodule have id.__attribute__ as IterableObj.
404410
# Tree has id.__attribute__ inherited from IndexObject.
@@ -421,11 +427,15 @@ def _list_traverse(
421427

422428
@abstractmethod
423429
def traverse(self, *args: Any, **kwargs: Any) -> Any:
424-
""" """
430+
"""Iterator yielding items found when traversing self.
431+
432+
Calling this directly on the abstract base class, including via a ``super()``
433+
proxy, is deprecated. Only overridden implementations should be called.
434+
"""
425435
warnings.warn(
426436
"traverse() method should only be called from subclasses."
427-
"Calling from Traversable abstract class will raise NotImplementedError in 3.1.20"
428-
"Builtin sublclasses are 'Submodule', 'Tree' and 'Commit",
437+
" Calling from Traversable abstract class will raise NotImplementedError in 4.0.0."
438+
" The concrete subclasses in GitPython itself are 'Commit', 'RootModule', 'Submodule', and 'Tree'.",
429439
DeprecationWarning,
430440
stacklevel=2,
431441
)
@@ -441,7 +451,7 @@ def _traverse(
441451
ignore_self: int = 1,
442452
as_edge: bool = False,
443453
) -> Union[Iterator[Union["Traversable", "Blob"]], Iterator[TraversedTup]]:
444-
""":return: Iterator yielding items found when traversing self
454+
"""Iterator yielding items found when traversing self.
445455
446456
:param predicate: f(i,d) returns False if item i at depth d should not be
447457
included in the result.
@@ -471,18 +481,18 @@ def _traverse(
471481
if True, return a pair of items, first being the source, second the
472482
destination, i.e. tuple(src, dest) with the edge spanning from source to
473483
destination
474-
"""
475484
476-
"""
477-
Commit -> Iterator[Union[Commit, Tuple[Commit, Commit]]
478-
Submodule -> Iterator[Submodule, Tuple[Submodule, Submodule]]
479-
Tree -> Iterator[Union[Blob, Tree, Submodule,
480-
Tuple[Union[Submodule, Tree], Union[Blob, Tree, Submodule]]]
481-
482-
ignore_self=True is_edge=True -> Iterator[item]
483-
ignore_self=True is_edge=False --> Iterator[item]
484-
ignore_self=False is_edge=True -> Iterator[item] | Iterator[Tuple[src, item]]
485-
ignore_self=False is_edge=False -> Iterator[Tuple[src, item]]
485+
:return: Iterator yielding items found when traversing self::
486+
487+
Commit -> Iterator[Union[Commit, Tuple[Commit, Commit]]
488+
Submodule -> Iterator[Submodule, Tuple[Submodule, Submodule]]
489+
Tree -> Iterator[Union[Blob, Tree, Submodule,
490+
Tuple[Union[Submodule, Tree], Union[Blob, Tree, Submodule]]]
491+
492+
ignore_self=True is_edge=True -> Iterator[item]
493+
ignore_self=True is_edge=False --> Iterator[item]
494+
ignore_self=False is_edge=True -> Iterator[item] | Iterator[Tuple[src, item]]
495+
ignore_self=False is_edge=False -> Iterator[Tuple[src, item]]
486496
"""
487497

488498
visited = set()
@@ -547,7 +557,7 @@ class Serializable(Protocol):
547557
def _serialize(self, stream: "BytesIO") -> "Serializable":
548558
"""Serialize the data of this object into the given data stream.
549559
550-
:note: A serialized object would ``_deserialize`` into the same object.
560+
:note: A serialized object would :meth:`_deserialize` into the same object.
551561
552562
:param stream: a file-like object
553563
@@ -627,24 +637,24 @@ def traverse(
627637
ignore_self: int = 1,
628638
as_edge: bool = False,
629639
) -> Union[Iterator[T_TIobj], Iterator[Tuple[T_TIobj, T_TIobj]], Iterator[TIobj_tuple]]:
630-
"""For documentation, see util.Traversable._traverse()"""
640+
"""For documentation, see :meth:`Traversable._traverse`."""
641+
642+
## To typecheck instead of using cast:
643+
#
644+
# import itertools
645+
# from git.types import TypeGuard
646+
# def is_commit_traversed(inp: Tuple) -> TypeGuard[Tuple[Iterator[Tuple['Commit', 'Commit']]]]:
647+
# for x in inp[1]:
648+
# if not isinstance(x, tuple) and len(x) != 2:
649+
# if all(isinstance(inner, Commit) for inner in x):
650+
# continue
651+
# return True
652+
#
653+
# ret = super(Commit, self).traverse(predicate, prune, depth, branch_first, visit_once, ignore_self, as_edge)
654+
# ret_tup = itertools.tee(ret, 2)
655+
# assert is_commit_traversed(ret_tup), f"{[type(x) for x in list(ret_tup[0])]}"
656+
# return ret_tup[0]
631657

632-
"""
633-
# To typecheck instead of using cast.
634-
import itertools
635-
from git.types import TypeGuard
636-
def is_commit_traversed(inp: Tuple) -> TypeGuard[Tuple[Iterator[Tuple['Commit', 'Commit']]]]:
637-
for x in inp[1]:
638-
if not isinstance(x, tuple) and len(x) != 2:
639-
if all(isinstance(inner, Commit) for inner in x):
640-
continue
641-
return True
642-
643-
ret = super(Commit, self).traverse(predicate, prune, depth, branch_first, visit_once, ignore_self, as_edge)
644-
ret_tup = itertools.tee(ret, 2)
645-
assert is_commit_traversed(ret_tup), f"{[type(x) for x in list(ret_tup[0])]}"
646-
return ret_tup[0]
647-
"""
648658
return cast(
649659
Union[Iterator[T_TIobj], Iterator[Tuple[Union[None, T_TIobj], T_TIobj]]],
650660
super()._traverse(predicate, prune, depth, branch_first, visit_once, ignore_self, as_edge), # type: ignore

‎git/util.py

Copy file name to clipboardExpand all lines: git/util.py
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1233,10 +1233,10 @@ def __init__(cls, name: str, bases: Tuple, clsdict: Dict) -> None:
12331233
for base in bases:
12341234
if type(base) is IterableClassWatcher:
12351235
warnings.warn(
1236-
f"GitPython Iterable subclassed by {name}. "
1237-
"Iterable is deprecated due to naming clash since v3.1.18"
1238-
" and will be removed in 3.1.20, "
1239-
"Use IterableObj instead \n",
1236+
f"GitPython Iterable subclassed by {name}."
1237+
" Iterable is deprecated due to naming clash since v3.1.18"
1238+
" and will be removed in 4.0.0."
1239+
" Use IterableObj instead.",
12401240
DeprecationWarning,
12411241
stacklevel=2,
12421242
)

0 commit comments

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