FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Convert constant and attribute comments to docstrings · gitpython-developers/GitPython@94a85d1 · GitHub

/ GitPython Public

Commit 94a85d1

Browse files
EliahKagan
committed
Convert constant and attribute comments to docstrings
These are "non-reified docstrings" as described in #1734. They are not made part of the data model, but most editors will display them, including on symbols present in code of other projects that use the GitPython library. A number of these have already been added, but this adds what will probably be most of the remaining ones. For the most part, this doesn't create documentation where there wasn't any, but instead converts existing comments to "docstrings." In a handful of cases, they are expanded, reworded, or a docstring added. This also fixes some small style inconsistencies that were missed in #1725, and moves a comment that had become inadvertently displaced due to autoformatting to the item it was meant for. The major omission here is HIDE_WINDOWS_KNOWN_ERRORS and HIDE_WINDOWS_FREEZE_ERRORS. This doesn't convert the comments above them to "docstrings," for a few reasons. They are not specific to either of the symbols, they are oriented toward considerations that are not really relevant except when developing GitPython itself, and they are out of date. Also, because HIDE_WINDOWS_KNOWN_ERRORS is listed in __all__, increasing the level of documentation for it might be taken as a committment to preserve some aspect of its current behavior, which could interfere with progress on #790. So I've kept those comments as comments, and unchanged, for now.
1 parent d986a59 commit 94a85d1

8 files changed

Lines changed: 64 additions & 39 deletions

File tree

‎git/cmd.py‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -273,23 +273,30 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
273273

274274
# CONFIGURATION
275275

276-
git_exec_name = "git" # Default that should work on Linux and Windows.
276+
git_exec_name = "git"
277+
"""Default git command that should work on Linux, Windows, and other systems."""
277278

278-
# Enables debugging of GitPython's git commands.
279279
GIT_PYTHON_TRACE = os.environ.get("GIT_PYTHON_TRACE", False)
280+
"""Enables debugging of GitPython's git commands."""
280281

281-
# If True, a shell will be used when executing git commands.
282-
# This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126
283-
# and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required.
284-
# Override this value using `Git.USE_SHELL = True`.
285282
USE_SHELL = False
283+
"""If True, a shell will be used when executing git commands.
284+
285+
This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126
286+
and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required.
287+
288+
Override this value using ``Git.USE_SHELL = True``.
289+
"""
286290

287-
# Provide the full path to the git executable. Otherwise it assumes git is in the path.
288291
_git_exec_env_var = "GIT_PYTHON_GIT_EXECUTABLE"
289292
_refresh_env_var = "GIT_PYTHON_REFRESH"
293+
290294
GIT_PYTHON_GIT_EXECUTABLE = None
291-
# Note that the git executable is actually found during the refresh step in
292-
# the top level __init__.
295+
"""Provide the full path to the git executable. Otherwise it assumes git is in the path.
296+
297+
Note that the git executable is actually found during the refresh step in
298+
the top level ``__init__``.
299+
"""
293300

294301
@classmethod
295302
def refresh(cls, path: Union[None, PathLike] = None) -> bool:

‎git/config.py‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,14 @@
6565
log.addHandler(logging.NullHandler())
6666

6767

68-
# The configuration level of a configuration file.
6968
CONFIG_LEVELS: ConfigLevels_Tup = ("system", "user", "global", "repository")
69+
"""The configuration level of a configuration file."""
7070

71-
# Section pattern to detect conditional includes.
72-
# https://git-scm.com/docs/git-config#_conditional_includes
7371
CONDITIONAL_INCLUDE_REGEXP = re.compile(r"(?<=includeIf )\"(gitdir|gitdir/i|onbranch):(.+)\"")
72+
"""Section pattern to detect conditional includes.
73+
74+
See: https://git-scm.com/docs/git-config#_conditional_includes
75+
"""
7476

7577

7678
class MetaParserBuilder(abc.ABCMeta): # noqa: B024
@@ -283,12 +285,14 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
283285
"""
284286

285287
# { Configuration
286-
# The lock type determines the type of lock to use in new configuration readers.
287-
# They must be compatible to the LockFile interface.
288-
# A suitable alternative would be the BlockingLockFile
289288
t_lock = LockFile
290-
re_comment = re.compile(r"^\s*[#;]")
289+
"""The lock type determines the type of lock to use in new configuration readers.
291290
291+
They must be compatible to the LockFile interface.
292+
A suitable alternative would be the :class:`~git.util.BlockingLockFile`.
293+
"""
294+
295+
re_comment = re.compile(r"^\s*[#;]")
292296
# } END configuration
293297

294298
optvalueonly_source = r"\s*(?P<option>[^:=\s][^:=]*)"
@@ -299,8 +303,8 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
299303

300304
del optvalueonly_source
301305

302-
# list of RawConfigParser methods able to change the instance
303306
_mutating_methods_ = ("add_section", "remove_section", "remove_option", "set")
307+
"""List of RawConfigParser methods able to change the instance."""
304308

305309
def __init__(
306310
self,

‎git/diff.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@
4949

5050
__all__ = ("Diffable", "DiffIndex", "Diff", "NULL_TREE")
5151

52-
# Special object to compare against the empty tree in diffs.
5352
NULL_TREE = object()
53+
"""Special object to compare against the empty tree in diffs."""
5454

5555
_octal_byte_re = re.compile(rb"\\([0-9]{3})")
5656

‎git/index/base.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,9 +142,11 @@ class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
142142

143143
__slots__ = ("repo", "version", "entries", "_extension_data", "_file_path")
144144

145-
_VERSION = 2 # Latest version we support.
145+
_VERSION = 2
146+
"""The latest version we support."""
146147

147-
S_IFGITLINK = S_IFGITLINK # A submodule.
148+
S_IFGITLINK = S_IFGITLINK
149+
"""Flags for a submodule."""
148150

149151
def __init__(self, repo: "Repo", file_path: Union[PathLike, None] = None) -> None:
150152
"""Initialize this Index instance, optionally from the given ``file_path``.

‎git/index/fun.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,9 @@
4949
# ------------------------------------------------------------------------------------
5050

5151

52-
S_IFGITLINK = S_IFLNK | S_IFDIR # A submodule.
52+
S_IFGITLINK = S_IFLNK | S_IFDIR
53+
"""Flags for a submodule."""
54+
5355
CE_NAMEMASK_INV = ~CE_NAMEMASK
5456

5557
__all__ = (

‎git/objects/submodule/base.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,9 @@ class UpdateProgress(RemoteProgress):
7777
UPDWKTREE = UpdateProgress.UPDWKTREE
7878

7979

80-
# IndexObject comes via util module, its a 'hacky' fix thanks to pythons import
81-
# mechanism which cause plenty of trouble of the only reason for packages and
82-
# modules is refactoring - subpackages shouldn't depend on parent packages
80+
# IndexObject comes via the util module. It's a 'hacky' fix thanks to Python's import
81+
# mechanism, which causes plenty of trouble if the only reason for packages and
82+
# modules is refactoring - subpackages shouldn't depend on parent packages.
8383
class Submodule(IndexObject, TraversableIterableObj):
8484
"""Implements access to a git submodule. They are special in that their sha
8585
represents a commit in the submodule's repository which is to be checked out
@@ -95,10 +95,11 @@ class Submodule(IndexObject, TraversableIterableObj):
9595
k_modules_file = ".gitmodules"
9696
k_head_option = "branch"
9797
k_head_default = "master"
98-
k_default_mode = stat.S_IFDIR | stat.S_IFLNK # Submodules are directories with link-status.
98+
k_default_mode = stat.S_IFDIR | stat.S_IFLNK
99+
"""Submodule flags. Submodules are directories with link-status."""
99100

100-
# This is a bogus type for base class compatibility.
101101
type: Literal["submodule"] = "submodule" # type: ignore
102+
"""This is a bogus type for base class compatibility."""
102103

103104
__slots__ = ("_parent_commit", "_url", "_branch_path", "_name", "__weakref__")
104105

‎git/repo/base.py‎

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -114,17 +114,18 @@ class Repo:
114114
'working_tree_dir' is the working tree directory, but will return None
115115
if we are a bare repository.
116116
117-
'git_dir' is the .git repository directory, which is always set."""
117+
'git_dir' is the .git repository directory, which is always set.
118+
"""
118119

119120
DAEMON_EXPORT_FILE = "git-daemon-export-ok"
120121

121-
git = cast("Git", None) # Must exist, or __del__ will fail in case we raise on `__init__()`
122+
git = cast("Git", None) # Must exist, or __del__ will fail in case we raise on `__init__()`.
122123
working_dir: PathLike
123124
_working_tree_dir: Optional[PathLike] = None
124125
git_dir: PathLike
125126
_common_dir: PathLike = ""
126127

127-
# precompiled regex
128+
# Precompiled regex
128129
re_whitespace = re.compile(r"\s+")
129130
re_hexsha_only = re.compile(r"^[0-9A-Fa-f]{40}$")
130131
re_hexsha_shortened = re.compile(r"^[0-9A-Fa-f]{4,40}$")
@@ -133,24 +134,32 @@ class Repo:
133134
re_tab_full_line = re.compile(r"^\t(.*)$")
134135

135136
unsafe_git_clone_options = [
136-
# This option allows users to execute arbitrary commands.
137-
# https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---upload-packltupload-packgt
137+
# Executes arbitrary commands:
138138
"--upload-pack",
139139
"-u",
140-
# Users can override configuration variables
141-
# like `protocol.allow` or `core.gitProxy` to execute arbitrary commands.
142-
# https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---configltkeygtltvaluegt
140+
# Can override configuration variables that execute arbitrary commands:
143141
"--config",
144142
"-c",
145143
]
144+
"""Options to ``git clone`` that allow arbitrary commands to be executed.
146145
147-
# invariants
148-
# represents the configuration level of a configuration file
146+
The ``--upload-pack``/``-u`` option allows users to execute arbitrary commands
147+
directly:
148+
https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---upload-packltupload-packgt
149+
150+
The ``--config``/``-c`` option allows users to override configuration variables like
151+
``protocol.allow`` and ``core.gitProxy`` to execute arbitrary commands:
152+
https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---configltkeygtltvaluegt
153+
"""
154+
155+
# Invariants
149156
config_level: ConfigLevels_Tup = ("system", "user", "global", "repository")
157+
"""Represents the configuration level of a configuration file."""
150158

151159
# Subclass configuration
152-
# Subclasses may easily bring in their own custom types by placing a constructor or type here
153160
GitCommandWrapperType = Git
161+
"""Subclasses may easily bring in their own custom types by placing a constructor or
162+
type here."""
154163

155164
def __init__(
156165
self,

‎git/util.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -557,8 +557,8 @@ class RemoteProgress:
557557
"_cur_line",
558558
"_seen_ops",
559559
"error_lines", # Lines that started with 'error:' or 'fatal:'.
560-
"other_lines",
561-
) # Lines not denoting progress (i.e.g. push-infos).
560+
"other_lines", # Lines not denoting progress (i.e.g. push-infos).
561+
)
562562
re_op_absolute = re.compile(r"(remote: )?([\w\s]+):\s+()(\d+)()(.*)")
563563
re_op_relative = re.compile(r"(remote: )?([\w\s]+):\s+(\d+)% \((\d+)/(\d+)\)(.*)")
564564

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL