From a040edbf09a5fd2d2355c7042d313edcad74eb40 Mon Sep 17 00:00:00 2001 From: Eliah Kagan Date: Mon, 30 Oct 2023 07:40:01 -0400 Subject: [PATCH] Shorten some docstring references with tilde notation This uses the Sphinx ~ notation to express references like: :class:`Z ` In the abbreviated form, which Sphinx renders the same way: :class:`~a.b.c.Z` (This commit also makes some other polishing changes to affected and nearby text.) --- git/diff.py | 20 +++++++++----------- git/objects/base.py | 2 +- git/objects/submodule/base.py | 18 ++++++++++-------- git/refs/head.py | 4 ++-- git/refs/reference.py | 4 ++-- git/refs/symbolic.py | 32 +++++++++++++++++--------------- git/refs/tag.py | 4 ++-- git/remote.py | 20 ++++++++++---------- git/repo/base.py | 35 +++++++++++++++++------------------ 9 files changed, 70 insertions(+), 69 deletions(-) diff --git a/git/diff.py b/git/diff.py index acf32af7d..275534bbf 100644 --- a/git/diff.py +++ b/git/diff.py @@ -118,12 +118,12 @@ def diff( This the item to compare us with. * If None, we will be compared to the working tree. - * If :class:`Treeish `, it will be compared against - the respective tree. - * If :class:`Index `, it will be compared against the index. + * 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 :attr:`git.NULL_TREE`, it will compare against the empty tree. - * It defaults to :class:`Index ` so that the method will not - by default fail on bare repositories. + * It defaults to :class:`~Diffable.Index` so that the method will not by + default fail on bare repositories. :param paths: This a list of paths or a single path to limit the diff to. It will only @@ -141,11 +141,9 @@ def diff( :return: git.DiffIndex :note: - On a bare repository, 'other' needs to be provided - as :class:`Index `, - or as :class:`Tree ` - or :class:`Commit `, or a git command error will - occur. + On a bare repository, 'other' needs to be provided as + :class:`~Diffable.Index`, or as :class:`~git.objects.tree.Tree` or + :class:`~git.objects.commit.Commit`, or a git command error will occur. """ args: List[Union[PathLike, Diffable, Type["Diffable.Index"], object]] = [] args.append("--abbrev=40") # We need full shas. @@ -222,7 +220,7 @@ class DiffIndex(List[T_Diff]): def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]: """ :return: - iterator yielding :class:`Diff` instances that match the given `change_type` + Iterator yielding :class:`Diff` instances that match the given `change_type` :param change_type: Member of :attr:`DiffIndex.change_type`, namely: diff --git a/git/objects/base.py b/git/objects/base.py index 0d88aa185..a771f9fbf 100644 --- a/git/objects/base.py +++ b/git/objects/base.py @@ -178,7 +178,7 @@ def __init__( ) -> None: """Initialize a newly instanced IndexObject. - :param repo: The :class:`Repo ` we are located in. + :param repo: The :class:`~git.repo.base.Repo` we are located in. :param binsha: 20 byte sha1. :param mode: The stat compatible file mode as int, use the :mod:`stat` module to evaluate diff --git a/git/objects/submodule/base.py b/git/objects/submodule/base.py index 41abe9223..018f9a39c 100644 --- a/git/objects/submodule/base.py +++ b/git/objects/submodule/base.py @@ -113,14 +113,16 @@ def __init__( ) -> None: """Initialize this instance with its attributes. - We only document the parameters that differ - from :class:`IndexObject `. - - :param repo: Our parent repository - :param binsha: binary sha referring to a commit in the remote repository, see url parameter - :param parent_commit: see set_parent_commit() - :param url: The url to the remote repository which is the submodule - :param branch_path: full (relative) path to ref to checkout when cloning the remote repository + We only document the parameters that differ from + :class:`~git.objects.base.IndexObject`. + + :param repo: Our parent repository. + :param binsha: Binary sha referring to a commit in the remote repository. See + the ``url`` parameter. + :param parent_commit: See :meth:`set_parent_commit`. + :param url: The URL to the remote repository which is the submodule. + :param branch_path: Full (relative) path to ref to checkout when cloning the + remote repository. """ super(Submodule, self).__init__(repo, binsha, mode, path) self.size = 0 diff --git a/git/refs/head.py b/git/refs/head.py index 194f51e78..30ff336d5 100644 --- a/git/refs/head.py +++ b/git/refs/head.py @@ -231,8 +231,8 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]: :param force: If True, changes to the index and the working tree will be discarded. - If False, :class:`GitCommandError ` will be - raised in that situation. + If False, :class:`~git.exc.GitCommandError` will be raised in that + situation. :param kwargs: Additional keyword arguments to be passed to git checkout, e.g. diff --git a/git/refs/reference.py b/git/refs/reference.py index ca265c0e4..8a0262ea4 100644 --- a/git/refs/reference.py +++ b/git/refs/reference.py @@ -40,8 +40,8 @@ def wrapper(self: T_References, *args: Any) -> _T: class Reference(SymbolicReference, LazyMixin, IterableObj): """A named reference to any object. - Subclasses may apply restrictions though, e.g., a :class:`Head ` - can only point to commits. + Subclasses may apply restrictions though, e.g., a :class:`~git.refs.head.Head` can + only point to commits. """ __slots__ = () diff --git a/git/refs/symbolic.py b/git/refs/symbolic.py index 7866772e3..6e4b657d6 100644 --- a/git/refs/symbolic.py +++ b/git/refs/symbolic.py @@ -59,7 +59,7 @@ class SymbolicReference: """Special case of a reference that is symbolic. This does not point to a specific commit, but to another - :class:`Head `, which itself specifies a commit. + :class:`~git.refs.head.Head`, which itself specifies a commit. A typical example for a symbolic reference is ``HEAD``. """ @@ -345,7 +345,7 @@ def set_object( If the reference does not exist, it will be created. :param object: A refspec, a :class:`SymbolicReference` or an - :class:`Object ` instance. + :class:`~git.objects.base.Object` instance. :class:`SymbolicReference` instances will be dereferenced beforehand to obtain the object they point to. :param logmsg: If not None, the message will be used in the reflog entry to be @@ -396,10 +396,10 @@ def set_reference( symbolic one. :param ref: - A :class:`SymbolicReference` instance, - an :class:`Object ` instance, or a refspec string. - Only if the ref is a :class:`SymbolicReference` instance, we will point to - it. Everything else is dereferenced to obtain the actual object. + A :class:`SymbolicReference` instance, an :class:`~git.objects.base.Object` + instance, or a refspec string. Only if the ref is a + :class:`SymbolicReference` instance, we will point to it. Everything else is + dereferenced to obtain the actual object. :param logmsg: If set to a string, the message will be used in the reflog. Otherwise, a reflog entry is not written for the changed reference. @@ -514,7 +514,7 @@ def log_append( :param message: A message describing the change. :param newbinsha: The sha the ref points to now. If None, our current commit sha will be used. - :return: The added :class:`RefLogEntry ` instance. + :return: The added :class:`~git.refs.log.RefLogEntry` instance. """ # NOTE: We use the committer of the currently active commit - this should be # correct to allow overriding the committer on a per-commit level. @@ -540,7 +540,7 @@ def log_entry(self, index: int) -> "RefLogEntry": .. note:: This method must read part of the reflog during execution, hence it should be used sparingly, or only if you need just one index. - In that case, it will be faster than the ``log()`` method. + In that case, it will be faster than the :meth:`log` method. """ return RefLog.entry_at(RefLog.path(self), index) @@ -816,8 +816,8 @@ def iter_items( which is not detached and pointing to a valid ref. The list is lexicographically sorted. The returned objects are instances of - concrete subclasses, such as :class:`Head ` or - :class:`TagReference `. + concrete subclasses, such as :class:`~git.refs.head.Head` or + :class:`~git.refs.tag.TagReference`. """ return (r for r in cls._iter_items(repo, common_path) if r.__class__ is SymbolicReference or not r.is_detached) @@ -826,14 +826,16 @@ def from_path(cls: Type[T_References], repo: "Repo", path: PathLike) -> T_Refere """ Make a symbolic reference from a path. - :param path: Full ``.git``-directory-relative path name to the Reference to instantiate. + :param path: Full ``.git``-directory-relative path name to the Reference to + instantiate. - :note: Use :meth:`to_full_path` if you only have a partial path of a known Reference type. + :note: Use :meth:`to_full_path` if you only have a partial path of a known + Reference type. :return: - Instance of type :class:`Reference `, - :class:`Head `, or :class:`Tag `, - depending on the given path. + Instance of type :class:`~git.refs.reference.Reference`, + :class:`~git.refs.head.Head`, or :class:`~git.refs.tag.Tag`, depending on + the given path. """ if not path: raise ValueError("Cannot create Reference from %r" % path) diff --git a/git/refs/tag.py b/git/refs/tag.py index 3c269d9ba..d00adc121 100644 --- a/git/refs/tag.py +++ b/git/refs/tag.py @@ -89,8 +89,8 @@ def create( The prefix ``refs/tags`` is implied. :param ref: - A reference to the :class:`Object ` you want to - tag. The Object can be a commit, tree or blob. + A reference to the :class:`~git.objects.base.Object` you want to tag. + The Object can be a commit, tree or blob. :param logmsg: If not None, the message will be used in your tag object. This will also diff --git a/git/remote.py b/git/remote.py index 08101bb6c..880e87232 100644 --- a/git/remote.py +++ b/git/remote.py @@ -210,9 +210,9 @@ def old_commit(self) -> Union[str, SymbolicReference, Commit_ish, None]: def remote_ref(self) -> Union[RemoteReference, TagReference]: """ :return: - Remote :class:`Reference ` or - :class:`TagReference ` in the local repository - corresponding to the :attr:`remote_ref_string` kept in this instance. + Remote :class:`~git.refs.reference.Reference` or + :class:`~git.refs.tag.TagReference` in the local repository corresponding to + the :attr:`remote_ref_string` kept in this instance. """ # Translate heads to a local remote. Tags stay as they are. if self.remote_ref_string.startswith("refs/tags"): @@ -1093,7 +1093,7 @@ def push( `Click here `__ for a description of all arguments given to the function. * An instance of a class derived from :class:`git.RemoteProgress` that - overrides the :meth:`update ` method. + overrides the :meth:`~git.RemoteProgress.update` method. :note: No further progress information is returned after push returns. @@ -1109,14 +1109,14 @@ def push( :param kwargs: Additional arguments to be passed to git-push. :return: - A :class:`PushInfoList` object, where each list member - represents an individual head which had been updated on the remote side. + A :class:`PushInfoList` object, where each list member represents an + individual head which had been updated on the remote side. If the push contains rejected heads, these will have the :attr:`PushInfo.ERROR` bit set in their flags. - If the operation fails completely, the length of the returned PushInfoList will - be 0. - Call :meth:`raise_if_error ` on the returned - object to raise on any failure. + If the operation fails completely, the length of the returned PushInfoList + will be 0. + Call :meth:`~PushInfoList.raise_if_error` on the returned object to raise on + any failure. """ kwargs = add_progress(kwargs, self.repo.git, progress) diff --git a/git/repo/base.py b/git/repo/base.py index 51c83d720..411a321ee 100644 --- a/git/repo/base.py +++ b/git/repo/base.py @@ -387,7 +387,7 @@ def heads(self) -> "IterableList[Head]": def references(self) -> "IterableList[Reference]": """A list of Reference objects representing tags, heads and remote references. - :return: IterableList(Reference, ...) + :return: ``git.IterableList(Reference, ...)`` """ return Reference.list_items(self) @@ -400,11 +400,11 @@ def references(self) -> "IterableList[Reference]": @property def index(self) -> "IndexFile": """ - :return: :class:`IndexFile ` representing this - repository's index. + :return: A :class:`~git.index.base.IndexFile` representing this repository's + index. :note: This property can be expensive, as the returned - :class:`IndexFile ` will be reinitialized. + :class:`~git.index.base.IndexFile` will be reinitialized. It is recommended to reuse the object. """ return IndexFile(self) @@ -520,7 +520,7 @@ def create_head( :note: For more documentation, please see the :meth:`Head.create ` method. - :return: Newly created :class:`Head ` Reference + :return: Newly created :class:`~git.refs.head.Head` Reference """ return Head.create(self, path, commit, logmsg, force) @@ -544,7 +544,7 @@ def create_tag( :note: For more documentation, please see the :meth:`TagReference.create ` method. - :return: :class:`TagReference ` object + :return: :class:`~git.refs.tag.TagReference` object """ return TagReference.create(self, path, ref, message, force, **kwargs) @@ -558,7 +558,7 @@ def create_remote(self, name: str, url: str, **kwargs: Any) -> Remote: For more information, please see the documentation of the :meth:`Remote.create ` method. - :return: :class:`Remote ` reference + :return: :class:`~git.remote.Remote` reference """ return Remote.create(self, name, url, **kwargs) @@ -599,8 +599,8 @@ def config_reader( ) -> GitConfigParser: """ :return: - :class:`GitConfigParser ` allowing to read the - full git configuration, but not to write it. + :class:`~git.config.GitConfigParser` allowing to read the full git + configuration, but not to write it. The configuration will include values from the system, user and repository configuration files. @@ -633,11 +633,10 @@ def _config_reader( def config_writer(self, config_level: Lit_config_levels = "repository") -> GitConfigParser: """ :return: - A :class:`GitConfigParser ` allowing to write - values of the specified configuration file level. Config writers should be - retrieved, used to change the configuration, and written right away as they - will lock the configuration file in question and prevent other's to write - it. + A :class:`~git.config.GitConfigParser` allowing to write values of the + specified configuration file level. Config writers should be retrieved, used + to change the configuration, and written right away as they will lock the + configuration file in question and prevent other's to write it. :param config_level: One of the following values: @@ -720,10 +719,10 @@ def merge_base(self, *rev: TBD, **kwargs: Any) -> List[Union[Commit_ish, None]]: :param rev: At least two revs to find the common ancestor for. :param kwargs: Additional arguments to be passed to the ``repo.git.merge_base()`` command which does all the work. - :return: A list of :class:`Commit ` objects. If - ``--all`` was not passed as a keyword argument, the list will have at max - one :class:`Commit `, or is empty if no common - merge base exists. + :return: A list of :class:`~git.objects.commit.Commit` objects. If ``--all`` was + not passed as a keyword argument, the list will have at max one + :class:`~git.objects.commit.Commit`, or is empty if no common merge base + exists. :raises ValueError: If not at least two revs are provided. """ if len(rev) < 2: