diff --git a/git/objects/base.py b/git/objects/base.py index df56a4bac..5cee8e405 100644 --- a/git/objects/base.py +++ b/git/objects/base.py @@ -58,7 +58,7 @@ class Object(LazyMixin): def __init__(self, repo: "Repo", binsha: bytes): """Initialize an object by identifying it by its binary sha. - All keyword arguments will be set on demand if None. + All keyword arguments will be set on demand if ``None``. :param repo: Repository this object is located in. @@ -83,7 +83,7 @@ def new(cls, repo: "Repo", id: Union[str, "Reference"]) -> Commit_ish: input id may have been a `~git.refs.reference.Reference` or rev-spec. :param id: - :class:`~git.refs.reference.Reference`, rev-spec, or hexsha + :class:`~git.refs.reference.Reference`, rev-spec, or hexsha. :note: This cannot be a ``__new__`` method as it would always call :meth:`__init__` @@ -119,13 +119,13 @@ def _set_cache_(self, attr: str) -> None: super()._set_cache_(attr) def __eq__(self, other: Any) -> bool: - """:return: True if the objects have the same SHA1""" + """:return: ``True`` if the objects have the same SHA1""" if not hasattr(other, "binsha"): return False return self.binsha == other.binsha def __ne__(self, other: Any) -> bool: - """:return: True if the objects do not have the same SHA1""" + """:return: ``True`` if the objects do not have the same SHA1""" if not hasattr(other, "binsha"): return True return self.binsha != other.binsha @@ -199,8 +199,8 @@ def __init__( 20 byte sha1. :param mode: - The stat compatible file mode as int, use the :mod:`stat` module to evaluate - the information. + The stat-compatible file mode as :class:`int`. + Use the :mod:`stat` module to evaluate the information. :param path: The path to the file in the file system, relative to the git repository diff --git a/git/objects/blob.py b/git/objects/blob.py index 50c12f0d7..253ceccb5 100644 --- a/git/objects/blob.py +++ b/git/objects/blob.py @@ -27,7 +27,8 @@ class Blob(base.IndexObject): @property def mime_type(self) -> str: """ - :return: String describing the mime type of this file (based on the filename) + :return: + String describing the mime type of this file (based on the filename) :note: Defaults to ``text/plain`` in case the actual file type is unknown. diff --git a/git/objects/commit.py b/git/objects/commit.py index e6aa7ac39..b5b1c540d 100644 --- a/git/objects/commit.py +++ b/git/objects/commit.py @@ -108,11 +108,11 @@ def __init__( encoding: Union[str, None] = None, gpgsig: Union[str, None] = None, ) -> None: - R"""Instantiate a new :class:`Commit`. All keyword arguments taking None as + R"""Instantiate a new :class:`Commit`. All keyword arguments taking ``None`` as default will be implicitly set on first query. :param binsha: - 20 byte sha1 + 20 byte sha1. :param parents: tuple(Commit, ...) A tuple of commit ids or actual :class:`Commit`\s. @@ -120,8 +120,8 @@ def __init__( :param tree: A :class:`~git.objects.tree.Tree` object. - :param author: :class:`~git.util.Actor` - The author Actor object + :param author: + The author :class:`~git.util.Actor` object. :param authored_date: int_seconds_since_epoch The authored DateTime - use :func:`time.gmtime` to convert it into a @@ -130,8 +130,8 @@ def __init__( :param author_tz_offset: int_seconds_west_of_utc The timezone that the `authored_date` is in. - :param committer: :class:`~git.util.Actor` - The committer string. + :param committer: + The committer string, as an :class:`~git.util.Actor` object. :param committed_date: int_seconds_since_epoch The committed DateTime - use :func:`time.gmtime` to convert it into a @@ -209,7 +209,7 @@ def _calculate_sha_(cls, repo: "Repo", commit: "Commit") -> bytes: return istream.binsha def replace(self, **kwargs: Any) -> "Commit": - """Create new commit object from existing commit object. + """Create new commit object from an existing commit object. Any values provided as keyword arguments will replace the corresponding attribute in the new object. @@ -295,7 +295,7 @@ def iter_items( R"""Find all commits matching the given criteria. :param repo: - The Repo + The :class:`~git.repo.base.Repo`. :param rev: Revision specifier, see git-rev-parse for viable options. @@ -378,7 +378,7 @@ def stats(self) -> Stats: @property def trailers(self) -> Dict[str, str]: - """Get the trailers of the message as a dictionary + """Deprecated. Get the trailers of the message as a dictionary. :note: This property is deprecated, please use either :attr:`trailers_list` or :attr:`trailers_dict``. @@ -396,7 +396,7 @@ def trailers_list(self) -> List[Tuple[str, str]]: Git messages can contain trailer information that are similar to RFC 822 e-mail headers (see: https://git-scm.com/docs/git-interpret-trailers). - This functions calls ``git interpret-trailers --parse`` onto the message to + This function calls ``git interpret-trailers --parse`` onto the message to extract the trailer information, returns the raw trailer data as a list. Valid message with trailer:: @@ -444,7 +444,7 @@ def trailers_dict(self) -> Dict[str, List[str]]: Git messages can contain trailer information that are similar to RFC 822 e-mail headers (see: https://git-scm.com/docs/git-interpret-trailers). - This functions calls ``git interpret-trailers --parse`` onto the message to + This function calls ``git interpret-trailers --parse`` onto the message to extract the trailer information. The key value pairs are stripped of leading and trailing whitespaces before they get saved into a dictionary. @@ -481,7 +481,7 @@ def trailers_dict(self) -> Dict[str, List[str]]: def _iter_from_process_or_stream(cls, repo: "Repo", proc_or_stream: Union[Popen, IO]) -> Iterator["Commit"]: """Parse out commit information into a list of :class:`Commit` objects. - We expect one-line per commit, and parse the actual commit information directly + We expect one line per commit, and parse the actual commit information directly from our lighting fast object database. :param proc: @@ -555,11 +555,11 @@ def create_from_tree( :param parent_commits: Optional :class:`Commit` objects to use as parents for the new commit. If empty list, the commit will have no parents at all and become a root commit. - If None, the current head commit will be the parent of the new commit + If ``None``, the current head commit will be the parent of the new commit object. :param head: - If True, the HEAD will be advanced to the new commit automatically. + If ``True``, the HEAD will be advanced to the new commit automatically. Otherwise the HEAD will remain pointing on the previous commit. This could lead to undesired results when diffing files. diff --git a/git/objects/fun.py b/git/objects/fun.py index d349737de..ad5bc9a88 100644 --- a/git/objects/fun.py +++ b/git/objects/fun.py @@ -128,7 +128,7 @@ def tree_entries_from_data(data: bytes) -> List[EntryTup]: def _find_by_name(tree_data: MutableSequence[EntryTupOrNone], name: str, is_dir: bool, start_at: int) -> EntryTupOrNone: - """Return data entry matching the given name and tree mode or None. + """Return data entry matching the given name and tree mode or ``None``. Before the item is returned, the respective data item is set None in the `tree_data` list to mark it done. @@ -172,7 +172,8 @@ def traverse_trees_recursive( odb: "GitCmdObjectDB", tree_shas: Sequence[Union[bytes, None]], path_prefix: str ) -> List[Tuple[EntryTupOrNone, ...]]: """ - :return: list of list with entries according to the given binary tree-shas. + :return: + List of list with entries according to the given binary tree-shas. The result is encoded in a list of n tuple|None per blob/commit, (n == len(tree_shas)), where: @@ -181,12 +182,12 @@ def traverse_trees_recursive( * [1] == mode as int * [2] == path relative to working tree root - The entry tuple is None if the respective blob/commit did not exist in the given - tree. + The entry tuple is ``None`` if the respective blob/commit did not exist in the + given tree. :param tree_shas: Iterable of shas pointing to trees. All trees must be on the same level. A - tree-sha may be None in which case None. + tree-sha may be ``None`` in which case ``None``. :param path_prefix: A prefix to be added to the returned paths on this level. @@ -257,7 +258,8 @@ def traverse_trees_recursive( def traverse_tree_recursive(odb: "GitCmdObjectDB", tree_sha: bytes, path_prefix: str) -> List[EntryTup]: """ - :return: list of entries of the tree pointed to by the binary `tree_sha`. + :return: + List of entries of the tree pointed to by the binary `tree_sha`. An entry has the following format: diff --git a/git/objects/tree.py b/git/objects/tree.py index da682b8cd..69cd6ef3f 100644 --- a/git/objects/tree.py +++ b/git/objects/tree.py @@ -97,17 +97,17 @@ def add(self, sha: bytes, mode: int, name: str, force: bool = False) -> "TreeMod If an item with the given name already exists, nothing will be done, but a :class:`ValueError` will be raised if the sha and mode of the existing item do - not match the one you add, unless `force` is True. + not match the one you add, unless `force` is ``True``. :param sha: The 20 or 40 byte sha of the item to add. :param mode: - int representing the stat compatible mode of the item. + :class:`int` representing the stat-compatible mode of the item. :param force: - If True, an item with your name and information will overwrite any existing - item with the same name, no matter which information it has. + If ``True``, an item with your name and information will overwrite any + existing item with the same name, no matter which information it has. :return: self @@ -164,11 +164,10 @@ class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable): R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and other :class:`~git.objects.tree.Tree`\s. - Tree as a list:: + Tree as a list: - Access a specific blob using the ``tree['filename']`` notation. - - You may likewise access by index, like ``blob = tree[0]``. + * Access a specific blob using the ``tree['filename']`` notation. + * You may likewise access by index, like ``blob = tree[0]``. """ type: Literal["tree"] = "tree" @@ -235,7 +234,7 @@ def join(self, file: str) -> IndexObjUnion: or :class:`~git.objects.submodule.base.Submodule` :raise KeyError: - If the given file or tree does not exist in tree. + If the given file or tree does not exist in this tree. """ msg = "Blob or Tree named %r not found" if "/" in file: @@ -275,12 +274,12 @@ def __truediv__(self, file: str) -> IndexObjUnion: @property def trees(self) -> List["Tree"]: - """:return: list(Tree, ...) list of trees directly below this tree""" + """:return: list(Tree, ...) List of trees directly below this tree""" return [i for i in self if i.type == "tree"] @property def blobs(self) -> List[Blob]: - """:return: list(Blob, ...) list of blobs directly below this tree""" + """:return: list(Blob, ...) List of blobs directly below this tree""" return [i for i in self if i.type == "blob"] @property @@ -342,7 +341,7 @@ def list_traverse(self, *args: Any, **kwargs: Any) -> IterableList[IndexObjUnion :class:`~git.util.IterableList`IterableList with the results of the traversal as produced by :meth:`traverse` - Tree -> IterableList[Union['Submodule', 'Tree', 'Blob']] + Tree -> IterableList[Union[Submodule, Tree, Blob]] """ return super()._list_traverse(*args, **kwargs) diff --git a/git/objects/util.py b/git/objects/util.py index 7ad20d66e..6f46bab18 100644 --- a/git/objects/util.py +++ b/git/objects/util.py @@ -95,9 +95,9 @@ def mode_str_to_int(modestr: Union[bytes, str]) -> int: used. :return: - String identifying a mode compatible to the mode methods ids of the stat module - regarding the rwx permissions for user, group and other, special flags and file - system flags, such as whether it is a symlink. + String identifying a mode compatible to the mode methods ids of the :mod:`stat` + module regarding the rwx permissions for user, group and other, special flags + and file system flags, such as whether it is a symlink. """ mode = 0 for iteration, char in enumerate(reversed(modestr[-6:])): @@ -401,7 +401,7 @@ class Tree:: (cls, Tree) -> Tuple[Tree, ...] def list_traverse(self, *args: Any, **kwargs: Any) -> Any: """Traverse self and collect all items found. - Calling this directly only the abstract base class, including via a ``super()`` + Calling this directly on the abstract base class, including via a ``super()`` proxy, is deprecated. Only overridden implementations should be called. """ warnings.warn( @@ -418,12 +418,13 @@ def _list_traverse( ) -> IterableList[Union["Commit", "Submodule", "Tree", "Blob"]]: """Traverse self and collect all items found. - :return: :class:`~git.util.IterableList` with the results of the traversal as + :return: + :class:`~git.util.IterableList` with the results of the traversal as produced by :meth:`traverse`:: - Commit -> IterableList["Commit"] - Submodule -> IterableList["Submodule"] - Tree -> IterableList[Union["Submodule", "Tree", "Blob"]] + Commit -> IterableList[Commit] + Submodule -> IterableList[Submodule] + Tree -> IterableList[Union[Submodule, Tree, Blob]] """ # Commit and Submodule have id.__attribute__ as IterableObj. # Tree has id.__attribute__ inherited from IndexObject. @@ -476,12 +477,12 @@ def _traverse( """Iterator yielding items found when traversing self. :param predicate: - A function ``f(i,d)`` that returns False if item i at depth ``d`` should not - be included in the result. + A function ``f(i,d)`` that returns ``False`` if item i at depth ``d`` should + not be included in the result. :param prune: - A function ``f(i,d)`` that returns True if the search should stop at item - ``i`` at depth ``d``. Item ``i`` will not be returned. + A function ``f(i,d)`` that returns ``True`` if the search should stop at + item ``i`` at depth ``d``. Item ``i`` will not be returned. :param depth: Defines at which level the iteration should not go deeper if -1, there is no @@ -489,19 +490,19 @@ def _traverse( i.e. if 1, you would only get the first level of predecessors/successors. :param branch_first: - If True, items will be returned branch first, otherwise depth first. + If ``True``, items will be returned branch first, otherwise depth first. :param visit_once: - If True, items will only be returned once, although they might be + If ``True``, items will only be returned once, although they might be encountered several times. Loops are prevented that way. :param ignore_self: - If True, self will be ignored and automatically pruned from the result. - Otherwise it will be the first item to be returned. If `as_edge` is True, the - source of the first edge is None + If ``True``, self will be ignored and automatically pruned from the result. + Otherwise it will be the first item to be returned. If `as_edge` is + ``True``, the source of the first edge is ``None``. :param as_edge: - If True, return a pair of items, first being the source, second the + If ``True``, return a pair of items, first being the source, second the destination, i.e. tuple(src, dest) with the edge spanning from source to destination.