From 0d6c68af35d1d4a9da95b189db1da68fdcee40b8 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 1 Mar 2024 14:04:54 -0500 Subject: [PATCH 1/8] Fix ref to git.refresh in refresh methods' docstrings --- git/cmd.py | 4 +++- git/remote.py | 5 ++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/git/cmd.py b/git/cmd.py index 6574cbb34..6e71e37fd 100644 --- a/git/cmd.py +++ b/git/cmd.py @@ -389,7 +389,9 @@ def __setstate__(self, d: Dict[str, Any]) -> None: @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 :func:`git.refresh` function. + + See the top level ``__init__.py``. :param path: Optional path to the git executable. If not absolute, it is resolved diff --git a/git/remote.py b/git/remote.py index 6ce720ee3..c1b2c11f7 100644 --- a/git/remote.py +++ b/git/remote.py @@ -338,7 +338,10 @@ 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 :func:`git.refresh` function. + + See the top level ``__init__.py``. + """ # Clear the old values in _flag_map. with contextlib.suppress(KeyError): del cls._flag_map["t"] From 65657421014ebcf89e29734ca2383346063c8363 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 1 Mar 2024 14:21:35 -0500 Subject: [PATCH 2/8] Further expand refresh methods' docstrings --- git/cmd.py | 7 +++++-- git/remote.py | 5 +++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/git/cmd.py b/git/cmd.py index 6e71e37fd..4fd6dc7cd 100644 --- a/git/cmd.py +++ b/git/cmd.py @@ -389,9 +389,12 @@ def __setstate__(self, d: Dict[str, Any]) -> None: @classmethod def refresh(cls, path: Union[None, PathLike] = None) -> bool: - """This gets called by the :func:`git.refresh` function. + """Update information about the git executable :class:`Git` objects will use. - See the top level ``__init__.py``. + Called by the :func:`git.refresh` function in the top level ``__init__``. + + This gets called by the :func:`git.refresh` function in the top-level + ``__init__``. :param path: Optional path to the git executable. If not absolute, it is resolved diff --git a/git/remote.py b/git/remote.py index c1b2c11f7..2c671582b 100644 --- a/git/remote.py +++ b/git/remote.py @@ -338,9 +338,10 @@ class FetchInfo(IterableObj): @classmethod def refresh(cls) -> Literal[True]: - """This gets called by the :func:`git.refresh` function. + """Update information about which ``git fetch`` flags are supported by the git + executable being used. - See the top level ``__init__.py``. + Called by the :func:`git.refresh` function in the top level ``__init__``. """ # Clear the old values in _flag_map. with contextlib.suppress(KeyError): From c0a27c027d2e04e3379f68f9e3299f30730559c1 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 1 Mar 2024 14:41:01 -0500 Subject: [PATCH 3/8] Better document overrides in GitCmdObjectDB --- git/db.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/git/db.py b/git/db.py index bf0de40de..15e791e6c 100644 --- a/git/db.py +++ b/git/db.py @@ -38,11 +38,12 @@ def __init__(self, root_path: PathLike, git: "Git") -> None: self._git = git def info(self, binsha: bytes) -> OInfo: + """Get a git object header (using git itself).""" hexsha, typename, size = self._git.get_object_header(bin_to_hex(binsha)) return OInfo(hex_to_bin(hexsha), typename, size) def stream(self, binsha: bytes) -> OStream: - """For now, all lookup is done by git itself""" + """Get git object data as a stream supporting ``read()`` (using git itself).""" hexsha, typename, size, stream = self._git.stream_object_data(bin_to_hex(binsha)) return OStream(hex_to_bin(hexsha), typename, size, stream) From fc59e5eafde730c9380266335edb278a23630ee8 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Fri, 1 Mar 2024 18:59:39 -0500 Subject: [PATCH 4/8] Improve stream_object_data and _parse_object_header docstrings This slightly adjusts working and formatting of these methods of the Git class, for clarity. --- git/cmd.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/git/cmd.py b/git/cmd.py index 4fd6dc7cd..41b88bd54 100644 --- a/git/cmd.py +++ b/git/cmd.py @@ -1491,7 +1491,9 @@ def _call_process( def _parse_object_header(self, header_line: str) -> Tuple[str, str, int]: """ :param header_line: - type_string size_as_int + A line of the form:: + + type_string size_as_int :return: (hex_sha, type_string, size_as_int) @@ -1581,7 +1583,7 @@ def get_object_data(self, ref: str) -> Tuple[str, str, int, bytes]: return (hexsha, typename, size, data) def stream_object_data(self, ref: str) -> Tuple[str, str, int, "Git.CatFileContentStream"]: - """Similar to :meth:`get_object_header`, but returns the data as a stream. + """Similar to :meth:`get_object_data`, but returns the data as a stream. :return: (hexsha, type_string, size_as_int, stream) From 7044ff6b9c5381c5506fd1f2a71546641ed259f7 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Sat, 2 Mar 2024 01:48:30 -0500 Subject: [PATCH 5/8] Include top-level git.refresh in API Reference For #1854. --- doc/source/reference.rst | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/doc/source/reference.rst b/doc/source/reference.rst index 68a7f0ba4..6ee25c04d 100644 --- a/doc/source/reference.rst +++ b/doc/source/reference.rst @@ -3,13 +3,16 @@ API Reference ============= -Version -------- +Top-Level +--------- .. py:data:: git.__version__ Current GitPython version. +.. automodule:: git + :members: refresh + Objects.Base ------------ @@ -17,7 +20,7 @@ Objects.Base :members: :undoc-members: :special-members: - + Objects.Blob ------------ @@ -25,7 +28,7 @@ Objects.Blob :members: :undoc-members: :special-members: - + Objects.Commit -------------- @@ -33,7 +36,7 @@ Objects.Commit :members: :undoc-members: :special-members: - + Objects.Tag ----------- @@ -73,7 +76,7 @@ Objects.Submodule.root :members: :undoc-members: :special-members: - + Objects.Submodule.util ---------------------- @@ -81,7 +84,7 @@ Objects.Submodule.util :members: :undoc-members: :special-members: - + Objects.Util ------------- @@ -105,7 +108,7 @@ Index.Functions :members: :undoc-members: :special-members: - + Index.Types ----------- @@ -113,7 +116,7 @@ Index.Types :members: :undoc-members: :special-members: - + Index.Util ------------- @@ -121,7 +124,7 @@ Index.Util :members: :undoc-members: :special-members: - + GitCmd ------ @@ -137,7 +140,7 @@ Config :members: :undoc-members: :special-members: - + Diff ---- @@ -154,7 +157,7 @@ Exceptions :undoc-members: :special-members: - + Refs.symbolic ------------- @@ -162,7 +165,7 @@ Refs.symbolic :members: :undoc-members: :special-members: - + Refs.reference -------------- @@ -178,7 +181,7 @@ Refs.head :members: :undoc-members: :special-members: - + Refs.tag ------------ @@ -186,7 +189,7 @@ Refs.tag :members: :undoc-members: :special-members: - + Refs.remote ------------ @@ -194,7 +197,7 @@ Refs.remote :members: :undoc-members: :special-members: - + Refs.log ------------ @@ -202,7 +205,7 @@ Refs.log :members: :undoc-members: :special-members: - + Remote ------ @@ -218,7 +221,7 @@ Repo.Base :members: :undoc-members: :special-members: - + Repo.Functions -------------- From 24160d1c7217622ec9b4de49ee2bf710e385ba0e Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Sat, 2 Mar 2024 03:11:15 -0500 Subject: [PATCH 6/8] Add git.compat, git.db, and git.types in API Reference For #1854 (along with 7044ff6). --- doc/source/reference.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/source/reference.rst b/doc/source/reference.rst index 6ee25c04d..13dd38d02 100644 --- a/doc/source/reference.rst +++ b/doc/source/reference.rst @@ -230,6 +230,30 @@ Repo.Functions :undoc-members: :special-members: +Compat +------ + +.. automodule:: git.compat + :members: + :undoc-members: + :special-members: + +DB +-- + +.. automodule:: git.db + :members: + :undoc-members: + :special-members: + +Types +----- + +.. automodule:: git.types + :members: + :undoc-members: + :special-members: + Util ---- From d1da48d512a9f68ced06e47998295c6b910eb640 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Sat, 2 Mar 2024 03:14:03 -0500 Subject: [PATCH 7/8] Fix unterminated double-backtick in a git.compat docstring Adding git.compat in reference.rst revealed this (and makes this fix necessary for the documentation to build). --- git/compat.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/git/compat.py b/git/compat.py index 3167cecdc..7753fe8b2 100644 --- a/git/compat.py +++ b/git/compat.py @@ -61,7 +61,7 @@ :note: For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while - ``sys.platform == "darwin"`. + ``sys.platform == "darwin"``. """ defenc = sys.getfilesystemencoding() From c4a6618eefcc5c2610bb0e247e02d188ac10663f Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Sat, 2 Mar 2024 11:14:03 +0100 Subject: [PATCH 8/8] Remove duplicate information in docstring --- git/cmd.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/git/cmd.py b/git/cmd.py index 41b88bd54..c7cec48d7 100644 --- a/git/cmd.py +++ b/git/cmd.py @@ -393,9 +393,6 @@ def refresh(cls, path: Union[None, PathLike] = None) -> bool: Called by the :func:`git.refresh` function in the top level ``__init__``. - This gets called by the :func:`git.refresh` function in the top-level - ``__init__``. - :param path: Optional path to the git executable. If not absolute, it is resolved immediately, relative to the current directory. (See note below.)