More docstring revisions in second-level modules and git.__init__

Author: EliahKagan

git/__init__.py

@@ -127,7 +127,7 @@ def refresh(path: Optional[PathLike] = None) -> None:
         immediately, relative to the current directory.
 
     :note:
-        The *path* parameter is usually omitted and cannot be used to specify a custom
+        The `path` parameter is usually omitted and cannot be used to specify a custom
         command whose location is looked up in a path search on each call. See
         :meth:`Git.refresh <git.cmd.Git.refresh>` for details on how to achieve this.
 

git/cmd.py

@@ -106,7 +106,7 @@ def handle_process_output(
     decode_streams: bool = True,
     kill_after_timeout: Union[None, float] = None,
 ) -> None:
-    """Register for notifications to learn that process output is ready to read, and
+    R"""Register for notifications to learn that process output is ready to read, and
     dispatch lines to the respective line handlers.
 
     This function returns once the finalizer returns.
@@ -126,8 +126,11 @@ def handle_process_output(
     :param decode_streams:
         Assume stdout/stderr streams are binary and decode them before pushing their
         contents to handlers.
-        Set this to ``False`` if ``universal_newlines == True`` (then streams are in
-        text mode) or if decoding must happen later (i.e. for :class:`~git.diff.Diff`s).
+
+        This defaults to ``True``. Set it to ``False``:
+
+        - if ``universal_newlines == True``, as then streams are in text mode, or
+        - if decoding must happen later, such as for :class:`~git.diff.Diff`\s.
 
     :param kill_after_timeout:
         :class:`float` or ``None``, Default = ``None``
@@ -379,15 +382,14 @@ def __setstate__(self, d: Dict[str, Any]) -> None:
 
     :note:
         The git executable is actually found during the refresh step in the top level
-        :mod:`__init__`. It can also be changed by explicitly calling
-        :func:`git.refresh`.
+        ``__init__``. It can also be changed by explicitly calling :func:`git.refresh`.
     """
 
     _refresh_token = object()  # Since None would match an initial _version_info_token.
 
     @classmethod
     def refresh(cls, path: Union[None, PathLike] = None) -> bool:
-        """This gets called by the refresh function (see the top level __init__).
+        """This gets called by the refresh function (see the top level ``__init__``).
 
         :param path:
             Optional path to the git executable. If not absolute, it is resolved
@@ -868,8 +870,7 @@ def __init__(self, working_dir: Union[None, PathLike] = None):
         self.cat_file_all: Union[None, TBD] = None
 
     def __getattr__(self, name: str) -> Any:
-        """A convenience method as it allows to call the command as if it was
-        an object.
+        """A convenience method as it allows to call the command as if it was an object.
 
         :return:
             Callable object that will execute call :meth:`_call_process` with your
@@ -899,7 +900,7 @@ def working_dir(self) -> Union[None, PathLike]:
     @property
     def version_info(self) -> Tuple[int, ...]:
         """
-        :return:  tuple with integers representing the major, minor and additional
+        :return: Tuple with integers representing the major, minor and additional
             version numbers as parsed from ``git version``. Up to four fields are used.
 
             This value is generated on demand and is cached.
@@ -1021,7 +1022,7 @@ def execute(
         :param output_stream:
             If set to a file-like object, data produced by the git command will be
             copied to the given stream instead of being returned as a string.
-            This feature only has any effect if `as_process` is False.
+            This feature only has any effect if `as_process` is ``False``.
 
         :param stdout_as_string:
             If ``False``, the command's standard output will be bytes. Otherwise, it
@@ -1030,10 +1031,10 @@ def execute(
 
         :param kill_after_timeout:
             Specifies a timeout in seconds for the git command, after which the process
-            should be killed. This will have no effect if `as_process` is set to True.
-            It is set to None by default and will let the process run until the timeout
-            is explicitly specified. Uses of this feature should be carefully
-            considered, due to the following limitations:
+            should be killed. This will have no effect if `as_process` is set to
+            ``True``. It is set to ``None`` by default and will let the process run
+            until the timeout is explicitly specified. Uses of this feature should be
+            carefully considered, due to the following limitations:
 
             1. This feature is not supported at all on Windows.
             2. Effectiveness may vary by operating system. ``ps --ppid`` is used to
@@ -1099,7 +1100,7 @@ def execute(
 
         :note:
            If you add additional keyword arguments to the signature of this method,
-           you must update the execute_kwargs tuple housed in this module.
+           you must update the ``execute_kwargs`` variable housed in this module.
         """
         # Remove password for the command if present.
         redacted_command = remove_password_if_present(command)
@@ -1420,9 +1421,10 @@ def _call_process(
         :param kwargs:
             Contains key-values for the following:
 
-            - The :meth:`execute()` kwds, as listed in :var:`execute_kwargs`.
+            - The :meth:`execute()` kwds, as listed in ``execute_kwargs``.
             - "Command options" to be converted by :meth:`transform_kwargs`.
-            - The ``insert_kwargs_after`` key which its value must match one of ``*args``.
+            - The ``insert_kwargs_after`` key which its value must match one of
+              ``*args``.
 
             It also contains any command options, to be appended after the matched arg.
 

git/config.py

@@ -411,7 +411,7 @@ def release(self) -> None:
         not be used anymore afterwards.
 
         In Python 3, it's required to explicitly release locks and flush changes, as
-        :meth:`__del__` is not called deterministically anymore.
+        ``__del__`` is not called deterministically anymore.
         """
         # Checking for the lock here makes sure we do not raise during write()
         # in case an invalid parser was created who could not get a lock.
@@ -539,7 +539,7 @@ def _included_paths(self) -> List[Tuple[str, str]]:
         """List all paths that must be included to configuration.
 
         :return:
-            The list of paths, where each path is a tuple of ``(option, value)``.
+            The list of paths, where each path is a tuple of (option, value).
         """
         paths = []
 
@@ -591,9 +591,6 @@ def read(self) -> None:  # type: ignore[override]
         This will ignore files that cannot be read, possibly leaving an empty
         configuration.
 
-        :return:
-            Nothing
-
         :raise IOError:
             If a file cannot be handled.
         """
@@ -765,7 +762,7 @@ def add_section(self, section: str) -> None:
 
     @property
     def read_only(self) -> bool:
-        """:return: True if this instance may change the configuration file"""
+        """:return: ``True`` if this instance may change the configuration file"""
         return self._read_only
 
     # FIXME: Figure out if default or return type can really include bool.
@@ -918,7 +915,7 @@ def add_value(self, section: str, option: str, value: Union[str, bytes, int, flo
         return self
 
     def rename_section(self, section: str, new_name: str) -> "GitConfigParser":
-        """Rename the given section to new_name.
+        """Rename the given section to `new_name`.
 
         :raise ValueError:
             If:

git/db.py

@@ -54,7 +54,8 @@ def stream(self, binsha: bytes) -> OStream:
 
     def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
         """
-        :return: Full binary 20 byte sha from the given partial hexsha
+        :return:
+            Full binary 20 byte sha from the given partial hexsha
 
         :raise gitdb.exc.AmbiguousObjectName:
 

git/diff.py

@@ -121,9 +121,9 @@ def diff(
             * If ``None``, we will be compared to the working tree.
             * If :class:`~git.index.base.Treeish`, it will be compared against the
               respective tree.
-            * If :class:`~Diffable.Index`, it will be compared against the index.
+            * If :class:`Diffable.Index`, it will be compared against the index.
             * If :attr:`git.NULL_TREE`, it will compare against the empty tree.
-            * It defaults to :class:`~Diffable.Index` so that the method will not by
+            * It defaults to :class:`Diffable.Index` so that the method will not by
               default fail on bare repositories.
 
         :param paths:
@@ -280,11 +280,11 @@ class Diff:
     Working Tree Blobs:
 
         When comparing to working trees, the working tree blob will have a null hexsha
-        as a corresponding object does not yet exist. The mode will be null as well.
-        The path will be available, though.
+        as a corresponding object does not yet exist. The mode will be null as well. The
+        path will be available, though.
 
-        If it is listed in a diff, the working tree version of the file must
-        differ from the version in the index or tree, and hence has been modified.
+        If it is listed in a diff, the working tree version of the file must differ from
+        the version in the index or tree, and hence has been modified.
     """
 
     # Precompiled regex.
@@ -468,7 +468,8 @@ def rename_to(self) -> Optional[str]:
 
     @property
     def renamed(self) -> bool:
-        """
+        """Deprecated, use :attr:`renamed_file` instead.
+
         :return:
             ``True`` if the blob of our diff has been renamed
 
@@ -480,7 +481,7 @@ def renamed(self) -> bool:
 
     @property
     def renamed_file(self) -> bool:
-        """:return: True if the blob of our diff has been renamed"""
+        """:return: ``True`` if the blob of our diff has been renamed"""
         return self.rename_from != self.rename_to
 
     @classmethod

git/remote.py

@@ -338,7 +338,7 @@ class FetchInfo(IterableObj):
 
     @classmethod
     def refresh(cls) -> Literal[True]:
-        """This gets called by the refresh function (see the top level __init__)."""
+        """This gets called by the refresh function (see the top level ``__init__``)."""
         # Clear the old values in _flag_map.
         with contextlib.suppress(KeyError):
             del cls._flag_map["t"]
@@ -386,19 +386,22 @@ def _from_line(cls, repo: "Repo", line: str, fetch_line: str) -> "FetchInfo":
         """Parse information from the given line as returned by ``git-fetch -v`` and
         return a new :class:`FetchInfo` object representing this information.
 
-        We can handle a line as follows:
-        "%c %-\\*s %-\\*s -> %s%s"
+        We can handle a line as follows::
 
-        Where c is either ' ', !, +, -, \\*, or =
-        ! means error
-        + means success forcing update
-        - means a tag was updated
-        * means birth of new branch or tag
-        = means the head was up to date (and not moved)
-        ' ' means a fast-forward
+            %c %-*s %-*s -> %s%s
 
-        fetch line is the corresponding line from FETCH_HEAD, like
-        acb0fa8b94ef421ad60c8507b634759a472cd56c    not-for-merge   branch '0.1.7RC' of /tmp/tmpya0vairemote_repo
+        Where ``c`` is either a space, ``!``, ``+``, ``-``, ``*``, or ``=``:
+
+        - '!' means error
+        - '+' means success forcing update
+        - '-' means a tag was updated
+        - '*' means birth of new branch or tag
+        - '=' means the head was up to date (and not moved)
+        - ' ' means a fast-forward
+
+        `fetch_line` is the corresponding line from FETCH_HEAD, like::
+
+            acb0fa8b94ef421ad60c8507b634759a472cd56c    not-for-merge   branch '0.1.7RC' of /tmp/tmpya0vairemote_repo
         """
         match = cls._re_fetch_result.match(line)
         if match is None:
@@ -625,7 +628,7 @@ def exists(self) -> bool:
 
     @classmethod
     def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Iterator["Remote"]:
-        """:return: Iterator yielding Remote objects of the given repository"""
+        """:return: Iterator yielding :class:`Remote` objects of the given repository"""
         for section in repo.config_reader("repository").sections():
             if not section.startswith("remote "):
                 continue
@@ -639,7 +642,7 @@ def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Iterator["Remote
     def set_url(
         self, new_url: str, old_url: Optional[str] = None, allow_unsafe_protocols: bool = False, **kwargs: Any
     ) -> "Remote":
-        """Configure URLs on current remote (cf command ``git remote set-url``).
+        """Configure URLs on current remote (cf. command ``git remote set-url``).
 
         This command manages URLs on the remote.
 
@@ -1020,7 +1023,7 @@ def fetch(
             facility.
 
         :param progress:
-            See :meth:`push` method.
+            See the :meth:`push` method.
 
         :param verbose:
             Boolean for verbose output.
@@ -1081,8 +1084,8 @@ def pull(
         allow_unsafe_options: bool = False,
         **kwargs: Any,
     ) -> IterableList[FetchInfo]:
-        """Pull changes from the given branch, being the same as a fetch followed
-        by a merge of branch with your local branch.
+        """Pull changes from the given branch, being the same as a fetch followed by a
+        merge of branch with your local branch.
 
         :param refspec:
             See :meth:`fetch` method.
@@ -1157,7 +1160,7 @@ def push(
 
         :param kill_after_timeout:
             To specify a timeout in seconds for the git command, after which the process
-            should be killed. It is set to None by default.
+            should be killed. It is set to ``None`` by default.
 
         :param allow_unsafe_protocols:
             Allow unsafe protocols to be used, like ``ext``.

git/util.py

@@ -762,9 +762,9 @@ def update(self, *args: Any, **kwargs: Any) -> None:
 
 
 class Actor:
-    """Actors hold information about a person acting on the repository. They
-    can be committers and authors or anything with a name and an email as mentioned in
-    the git log entries."""
+    """Actors hold information about a person acting on the repository. They can be
+    committers and authors or anything with a name and an email as mentioned in the git
+    log entries."""
 
     # PRECOMPILED REGEX
     name_only_regex = re.compile(r"<(.*)>")