Content-Length: 8636 | pFad | http://github.com/gitpython-developers/GitPython/pull/1735.patch

thub.com From aed3b59d50b7105debcb11d03c7abd8a1a4e5c96 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 6 Nov 2023 10:05:57 -0500 Subject: [PATCH] Revise and restore some module docstrings In 9ccd777, several module docstrings were converted into comments or outright deleted, apparently due to at least one of them (in git/index/fun.py) and possibly others having broken Sphinx autodoc. As discussed later in #1733, this no longer seems to be a problem, not even in git/index/fun.py where the comment included a note indicating it had. So this converts them back to docstrings, re-adding those that were removed in 9ccd777. This also revises them, partly to avoid making outdated claims, but mostly for style and clarity. It also revises some already-present module docstrings. Other than modules 9ccd777 affected, this does not add new docstrings to modules without them. One of the revisions made to some module docstrings here, to improve readability, is to remove language like "Module implementing" or "Module for", which was already used only in some places. However, this language is retained in the specific cases where it is clarifying, for example by avoiding documenting a module as if it the same thing as a single class implemented in it (which would be distracting because it would read as a mistake, and which could be confusing in cases where a developer uses an import with an "as" clause and needs to debug it because it was intended to be an "import" or "from" statement but was accidentally written as the other of those). --- git/config.py | 3 +-- git/exc.py | 2 +- git/index/base.py | 3 +++ git/index/fun.py | 3 +-- git/index/typ.py | 2 +- git/index/util.py | 2 +- git/objects/fun.py | 2 +- git/objects/tag.py | 2 +- git/objects/util.py | 2 +- git/refs/head.py | 5 +++++ git/refs/remote.py | 2 ++ git/repo/fun.py | 2 +- test/test_blob_filter.py | 2 +- test/test_exc.py | 1 - test/test_repo.py | 1 + 15 files changed, 21 insertions(+), 13 deletions(-) diff --git a/git/config.py b/git/config.py index 17a07fba9..983d71e86 100644 --- a/git/config.py +++ b/git/config.py @@ -3,8 +3,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module containing module parser implementation able to properly read and write -configuration files.""" +"""Parser for reading and writing configuration files.""" import abc import configparser as cp diff --git a/git/exc.py b/git/exc.py index 35008c29a..85113bc44 100644 --- a/git/exc.py +++ b/git/exc.py @@ -3,7 +3,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module containing all exceptions thrown throughout the git package.""" +"""Exceptions thrown throughout the git package.""" __all__ = [ # Defined in gitdb.exc: diff --git a/git/index/base.py b/git/index/base.py index dbfa2c9bf..94437ac88 100644 --- a/git/index/base.py +++ b/git/index/base.py @@ -3,6 +3,9 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ +"""Module containing IndexFile, an Index implementation facilitating all kinds of index +manipulations such as querying and merging.""" + from contextlib import ExitStack import datetime import glob diff --git a/git/index/fun.py b/git/index/fun.py index 45317429f..7b3b06269 100644 --- a/git/index/fun.py +++ b/git/index/fun.py @@ -1,8 +1,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -# Standalone functions to accompany the index implementation and make it more versatile. -# NOTE: Autodoc hates it if this is a docstring. +"""Standalone functions to accompany the index implementation and make it more versatile.""" from io import BytesIO import os diff --git a/git/index/typ.py b/git/index/typ.py index 7011fd03d..894e6f16d 100644 --- a/git/index/typ.py +++ b/git/index/typ.py @@ -1,7 +1,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module with additional types used by the index.""" +"""Additional types used by the index.""" from binascii import b2a_hex from pathlib import Path diff --git a/git/index/util.py b/git/index/util.py index 5ee20a8ef..b1aaa58fd 100644 --- a/git/index/util.py +++ b/git/index/util.py @@ -1,7 +1,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module containing index utilities.""" +"""Index utilities.""" from functools import wraps import os diff --git a/git/objects/fun.py b/git/objects/fun.py index 6d8a23d35..bf6bc21d6 100644 --- a/git/objects/fun.py +++ b/git/objects/fun.py @@ -1,7 +1,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module with functions which are supposed to be as fast as possible.""" +"""Functions that are supposed to be as fast as possible.""" from stat import S_ISDIR diff --git a/git/objects/tag.py b/git/objects/tag.py index 500879d54..f7aaaf477 100644 --- a/git/objects/tag.py +++ b/git/objects/tag.py @@ -3,7 +3,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module containing all Object-based types.""" +"""Object-based types.""" from . import base from .util import get_object_type_by_name, parse_actor_and_date diff --git a/git/objects/util.py b/git/objects/util.py index 9f42227d0..3021fec39 100644 --- a/git/objects/util.py +++ b/git/objects/util.py @@ -3,7 +3,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module for general utility functions.""" +"""General utility functions.""" # flake8: noqa F401 diff --git a/git/refs/head.py b/git/refs/head.py index fba195aaa..ebc71eb96 100644 --- a/git/refs/head.py +++ b/git/refs/head.py @@ -1,6 +1,11 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ +"""Some ref-based objects. + +Note the distinction between the :class:`HEAD` and :class:`Head` classes. +""" + from git.config import GitConfigParser, SectionConstraint from git.util import join_path from git.exc import GitCommandError diff --git a/git/refs/remote.py b/git/refs/remote.py index dd4117fa7..59d02a755 100644 --- a/git/refs/remote.py +++ b/git/refs/remote.py @@ -1,6 +1,8 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ +"""Module implementing a remote object allowing easy access to git remotes.""" + import os from git.util import join_path diff --git a/git/repo/fun.py b/git/repo/fun.py index ee831332f..63bcfdfc7 100644 --- a/git/repo/fun.py +++ b/git/repo/fun.py @@ -1,7 +1,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Module with general repository-related functions.""" +"""General repository-related functions.""" from __future__ import annotations diff --git a/test/test_blob_filter.py b/test/test_blob_filter.py index 5cc6b48c9..a91f211bf 100644 --- a/test/test_blob_filter.py +++ b/test/test_blob_filter.py @@ -1,7 +1,7 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ -"""Test the blob filter.""" +"""Tests for the blob filter.""" from pathlib import Path from typing import Sequence, Tuple diff --git a/test/test_exc.py b/test/test_exc.py index 62bb4fb6e..cecd4f342 100644 --- a/test/test_exc.py +++ b/test/test_exc.py @@ -3,7 +3,6 @@ # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ - import re import ddt diff --git a/test/test_repo.py b/test/test_repo.py index e77bf2503..e39aee05e 100644 --- a/test/test_repo.py +++ b/test/test_repo.py @@ -2,6 +2,7 @@ # # This module is part of GitPython and is released under the # 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/ + import glob import io from io import BytesIO

pFad - (p)hone/(F)rame/(a)nonymizer/(d)eclutterfier! Saves Data!