thub.com
From 94a85d1159e6374e901df4e3bd284cf55b623e66 Mon Sep 17 00:00:00 2001
From: Eliah Kagan
Date: Fri, 22 Dec 2023 14:31:28 -0500
Subject: [PATCH 1/2] 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.
---
git/cmd.py | 25 ++++++++++++++++---------
git/config.py | 20 ++++++++++++--------
git/diff.py | 2 +-
git/index/base.py | 6 ++++--
git/index/fun.py | 4 +++-
git/objects/submodule/base.py | 11 ++++++-----
git/repo/base.py | 31 ++++++++++++++++++++-----------
git/util.py | 4 ++--
8 files changed, 64 insertions(+), 39 deletions(-)
diff --git a/git/cmd.py b/git/cmd.py
index 27148d3d6..9518c2c8c 100644
--- a/git/cmd.py
+++ b/git/cmd.py
@@ -273,23 +273,30 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
# CONFIGURATION
- git_exec_name = "git" # Default that should work on Linux and Windows.
+ git_exec_name = "git"
+ """Default git command that should work on Linux, Windows, and other systems."""
- # Enables debugging of GitPython's git commands.
GIT_PYTHON_TRACE = os.environ.get("GIT_PYTHON_TRACE", False)
+ """Enables debugging of GitPython's git commands."""
- # If True, a shell will be used when executing git commands.
- # This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126
- # and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required.
- # Override this value using `Git.USE_SHELL = True`.
USE_SHELL = False
+ """If True, a shell will be used when executing git commands.
+
+ This should only be desirable on Windows, see https://github.com/gitpython-developers/GitPython/pull/126
+ and check `git/test_repo.py:TestRepo.test_untracked_files()` TC for an example where it is required.
+
+ Override this value using ``Git.USE_SHELL = True``.
+ """
- # Provide the full path to the git executable. Otherwise it assumes git is in the path.
_git_exec_env_var = "GIT_PYTHON_GIT_EXECUTABLE"
_refresh_env_var = "GIT_PYTHON_REFRESH"
+
GIT_PYTHON_GIT_EXECUTABLE = None
- # Note that the git executable is actually found during the refresh step in
- # the top level __init__.
+ """Provide the full path to the git executable. Otherwise it assumes git is in the path.
+
+ Note that the git executable is actually found during the refresh step in
+ the top level ``__init__``.
+ """
@classmethod
def refresh(cls, path: Union[None, PathLike] = None) -> bool:
diff --git a/git/config.py b/git/config.py
index 5708a7385..2730ddaf3 100644
--- a/git/config.py
+++ b/git/config.py
@@ -65,12 +65,14 @@
log.addHandler(logging.NullHandler())
-# The configuration level of a configuration file.
CONFIG_LEVELS: ConfigLevels_Tup = ("system", "user", "global", "repository")
+"""The configuration level of a configuration file."""
-# Section pattern to detect conditional includes.
-# https://git-scm.com/docs/git-config#_conditional_includes
CONDITIONAL_INCLUDE_REGEXP = re.compile(r"(?<=includeIf )\"(gitdir|gitdir/i|onbranch):(.+)\"")
+"""Section pattern to detect conditional includes.
+
+See: https://git-scm.com/docs/git-config#_conditional_includes
+"""
class MetaParserBuilder(abc.ABCMeta): # noqa: B024
@@ -283,12 +285,14 @@ class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
"""
# { Configuration
- # The lock type determines the type of lock to use in new configuration readers.
- # They must be compatible to the LockFile interface.
- # A suitable alternative would be the BlockingLockFile
t_lock = LockFile
- re_comment = re.compile(r"^\s*[#;]")
+ """The lock type determines the type of lock to use in new configuration readers.
+ They must be compatible to the LockFile interface.
+ A suitable alternative would be the :class:`~git.util.BlockingLockFile`.
+ """
+
+ re_comment = re.compile(r"^\s*[#;]")
# } END configuration
optvalueonly_source = r"\s*(?P