Revise docstrings/comments in most other test modules

Intentionally untouched test modules in this commit:

- Modules where there are no such changes to be made.

- Modules in test/performance/ -- will be done separately.

- test/lib/ modules (these are test *helpers* and will be done
  separately).

- test/test_util.py, because although it has a few comments that
  might be improved, it may make more sense to do that together
  with some further refactoring changes.

test/test_actor.py

@@ -14,7 +14,7 @@ def test_from_string_should_separate_name_and_email(self):
         self.assertEqual("Michael Trier", a.name)
         self.assertEqual("[email protected]", a.email)
 
-        # base type capabilities
+        # Base type capabilities
         assert a == a
         assert not (a != a)
         m = set()

test/test_base.py

@@ -4,6 +4,7 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: https://opensource.org/license/bsd-3-clause/
+
 import os
 import sys
 import tempfile
@@ -34,7 +35,7 @@ def tearDown(self):
     )
 
     def test_base_object(self):
-        # test interface of base object classes
+        # Test interface of base object classes.
         types = (Blob, Tree, Commit, TagObject)
         self.assertEqual(len(types), len(self.type_tuples))
 
@@ -61,12 +62,12 @@ def test_base_object(self):
 
             if isinstance(item, base.IndexObject):
                 num_index_objs += 1
-                if hasattr(item, "path"):  # never runs here
-                    assert not item.path.startswith("/")  # must be relative
+                if hasattr(item, "path"):  # Never runs here.
+                    assert not item.path.startswith("/")  # Must be relative.
                     assert isinstance(item.mode, int)
             # END index object check
 
-            # read from stream
+            # Read from stream.
             data_stream = item.data_stream
             data = data_stream.read()
             assert data
@@ -79,7 +80,7 @@ def test_base_object(self):
             os.remove(tmpfilename)
         # END for each object type to create
 
-        # each has a unique sha
+        # Each has a unique sha.
         self.assertEqual(len(s), num_objs)
         self.assertEqual(len(s | s), num_objs)
         self.assertEqual(num_index_objs, 2)
@@ -92,7 +93,7 @@ def test_get_object_type_by_name(self):
         self.assertRaises(ValueError, get_object_type_by_name, b"doesntexist")
 
     def test_object_resolution(self):
-        # objects must be resolved to shas so they compare equal
+        # Objects must be resolved to shas so they compare equal.
         self.assertEqual(self.rorepo.head.reference.object, self.rorepo.active_branch.object)
 
     @with_rw_repo("HEAD", bare=True)
@@ -122,7 +123,7 @@ def test_add_unicode(self, rw_repo):
 
         file_path = osp.join(rw_repo.working_dir, filename)
 
-        # verify first that we could encode file name in this environment
+        # Verify first that we could encode file name in this environment.
         try:
             file_path.encode(sys.getfilesystemencoding())
         except UnicodeEncodeError as e:
@@ -132,14 +133,14 @@ def test_add_unicode(self, rw_repo):
             fp.write(b"something")
 
         if is_win:
-            # on windows, there is no way this works, see images on
+            # On Windows, there is no way this works, see images on:
             # https://github.com/gitpython-developers/GitPython/issues/147#issuecomment-68881897
-            # Therefore, it must be added using the python implementation
+            # Therefore, it must be added using the Python implementation.
             rw_repo.index.add([file_path])
             # However, when the test winds down, rmtree fails to delete this file, which is recognized
             # as ??? only.
         else:
-            # on posix, we can just add unicode files without problems
+            # On POSIX, we can just add Unicode files without problems.
             rw_repo.git.add(rw_repo.working_dir)
         # end
         rw_repo.index.commit("message")

test/test_blob_filter.py

@@ -1,4 +1,5 @@
 """Test the blob filter."""
+
 from pathlib import Path
 from typing import Sequence, Tuple
 from unittest.mock import MagicMock

test/test_clone.py

@@ -21,7 +21,7 @@ def test_checkout_in_non_empty_dir(self, rw_dir):
         garbage_file.write_text("Garbage!")
 
         # Verify that cloning into the non-empty dir fails while complaining about
-        # the target directory not being empty/non-existent
+        # the target directory not being empty/non-existent.
         try:
             self.rorepo.clone(non_empty_dir)
         except git.GitCommandError as exc:

test/test_commit.py

@@ -4,6 +4,7 @@
 #
 # This module is part of GitPython and is released under
 # the BSD License: https://opensource.org/license/bsd-3-clause/
+
 import copy
 from datetime import datetime
 from io import BytesIO
@@ -28,18 +29,20 @@
 
 class TestCommitSerialization(TestBase):
     def assert_commit_serialization(self, rwrepo, commit_id, print_performance_info=False):
-        """traverse all commits in the history of commit identified by commit_id and check
+        """Traverse all commits in the history of commit identified by commit_id and check
         if the serialization works.
-        :param print_performance_info: if True, we will show how fast we are"""
-        ns = 0  # num serializations
-        nds = 0  # num deserializations
+
+        :param print_performance_info: If True, we will show how fast we are.
+        """
+        ns = 0  # Number of serializations.
+        nds = 0  # Number of deserializations.
 
         st = time.time()
         for cm in rwrepo.commit(commit_id).traverse():
             nds += 1
 
-            # assert that we deserialize commits correctly, hence we get the same
-            # sha on serialization
+            # Assert that we deserialize commits correctly, hence we get the same
+            # sha on serialization.
             stream = BytesIO()
             cm._serialize(stream)
             ns += 1
@@ -71,13 +74,13 @@ def assert_commit_serialization(self, rwrepo, commit_id, print_performance_info=
             streamlen = stream.tell()
             stream.seek(0)
 
-            # reuse istream
+            # Reuse istream.
             istream.size = streamlen
             istream.stream = stream
             istream.binsha = None
             nc.binsha = rwrepo.odb.store(istream).binsha
 
-            # if it worked, we have exactly the same contents !
+            # If it worked, we have exactly the same contents!
             self.assertEqual(nc.hexsha, cm.hexsha)
         # END check commits
         elapsed = time.time() - st
@@ -94,7 +97,7 @@ def assert_commit_serialization(self, rwrepo, commit_id, print_performance_info=
 class TestCommit(TestCommitSerialization):
     def test_bake(self):
         commit = self.rorepo.commit("2454ae89983a4496a445ce347d7a41c0bb0ea7ae")
-        # commits have no dict
+        # Commits have no dict.
         self.assertRaises(AttributeError, setattr, commit, "someattr", 1)
         commit.author  # bake
 
@@ -148,7 +151,7 @@ def check_entries(d):
             check_entries(d)
         # END for each stated file
 
-        # assure data is parsed properly
+        # Check that data is parsed properly.
         michael = Actor._from_string("Michael Trier <[email protected]>")
         self.assertEqual(commit.author, michael)
         self.assertEqual(commit.committer, michael)
@@ -162,9 +165,9 @@ def test_renames(self):
         commit = self.rorepo.commit("185d847ec7647fd2642a82d9205fb3d07ea71715")
         files = commit.stats.files
 
-        # when a file is renamed, the output of git diff is like "dir/{old => new}"
-        # unless we disable rename with --no-renames, which produces two lines
-        # one with the old path deletes and another with the new added
+        # When a file is renamed, the output of git diff is like "dir/{old => new}"
+        # unless we disable rename with --no-renames, which produces two lines,
+        # one with the old path deletes and another with the new added.
         self.assertEqual(len(files), 2)
 
         def check_entries(path, changes):
@@ -190,7 +193,7 @@ def check_entries(path, changes):
         # END for each stated file
 
     def test_unicode_actor(self):
-        # assure we can parse unicode actors correctly
+        # Check that we can parse Unicode actors correctly.
         name = "Üäöß ÄußÉ"
         self.assertEqual(len(name), 9)
         special = Actor._from_string("%s <[email protected]>" % name)
@@ -205,7 +208,7 @@ def test_traversal(self):
         p00 = p0.parents[0]
         p10 = p1.parents[0]
 
-        # basic branch first, depth first
+        # Basic branch first, depth first.
         dfirst = start.traverse(branch_first=False)
         bfirst = start.traverse(branch_first=True)
         self.assertEqual(next(dfirst), p0)
@@ -216,7 +219,7 @@ def test_traversal(self):
         self.assertEqual(next(bfirst), p00)
         self.assertEqual(next(bfirst), p10)
 
-        # at some point, both iterations should stop
+        # At some point, both iterations should stop.
         self.assertEqual(list(bfirst)[-1], first)
 
         stoptraverse = self.rorepo.commit("254d04aa3180eb8b8daf7b7ff25f010cd69b4e7d").traverse(
@@ -235,40 +238,39 @@ def test_traversal(self):
         stoptraverse = self.rorepo.commit("254d04aa3180eb8b8daf7b7ff25f010cd69b4e7d").traverse(as_edge=True)
         self.assertEqual(len(next(stoptraverse)), 2)
 
-        # ignore self
+        # Ignore self
         self.assertEqual(next(start.traverse(ignore_self=False)), start)
 
-        # depth
+        # Depth
         self.assertEqual(len(list(start.traverse(ignore_self=False, depth=0))), 1)
 
-        # prune
+        # Prune
         self.assertEqual(next(start.traverse(branch_first=1, prune=lambda i, d: i == p0)), p1)
 
-        # predicate
+        # Predicate
         self.assertEqual(next(start.traverse(branch_first=1, predicate=lambda i, d: i == p1)), p1)
 
-        # traversal should stop when the beginning is reached
+        # Traversal should stop when the beginning is reached.
         self.assertRaises(StopIteration, next, first.traverse())
 
-        # parents of the first commit should be empty ( as the only parent has a null
-        # sha )
+        # Parents of the first commit should be empty (as the only parent has a null sha)
         self.assertEqual(len(first.parents), 0)
 
     def test_iteration(self):
-        # we can iterate commits
+        # We can iterate commits.
         all_commits = Commit.list_items(self.rorepo, self.rorepo.head)
         assert all_commits
         self.assertEqual(all_commits, list(self.rorepo.iter_commits()))
 
-        # this includes merge commits
+        # This includes merge commits.
         mcomit = self.rorepo.commit("d884adc80c80300b4cc05321494713904ef1df2d")
         assert mcomit in all_commits
 
-        # we can limit the result to paths
+        # We can limit the result to paths.
         ltd_commits = list(self.rorepo.iter_commits(paths="CHANGES"))
         assert ltd_commits and len(ltd_commits) < len(all_commits)
 
-        # show commits of multiple paths, resulting in a union of commits
+        # Show commits of multiple paths, resulting in a union of commits.
         less_ltd_commits = list(Commit.iter_items(self.rorepo, "master", paths=("CHANGES", "AUTHORS")))
         assert len(ltd_commits) < len(less_ltd_commits)
 
@@ -280,7 +282,7 @@ def __init__(self, *args, **kwargs):
         assert type(child_commits[0]) is Child
 
     def test_iter_items(self):
-        # pretty not allowed
+        # pretty not allowed.
         self.assertRaises(ValueError, Commit.iter_items, self.rorepo, "master", pretty="raw")
 
     def test_rev_list_bisect_all(self):
@@ -311,14 +313,14 @@ def test_ambiguous_arg_iteration(self, rw_dir):
         touch(path)
         rw_repo.index.add([path])
         rw_repo.index.commit("initial commit")
-        list(rw_repo.iter_commits(rw_repo.head.ref))  # should fail unless bug is fixed
+        list(rw_repo.iter_commits(rw_repo.head.ref))  # Should fail unless bug is fixed.
 
     def test_count(self):
         self.assertEqual(self.rorepo.tag("refs/tags/0.1.5").commit.count(), 143)
 
     def test_list(self):
         # This doesn't work anymore, as we will either attempt getattr with bytes, or compare 20 byte string
-        # with actual 20 byte bytes. This usage makes no sense anyway
+        # with actual 20 byte bytes. This usage makes no sense anyway.
         assert isinstance(
             Commit.list_items(self.rorepo, "0.1.5", max_count=5)["5117c9c8a4d3af19a9958677e45cda9269de1541"],
             Commit,
@@ -340,7 +342,7 @@ def test_equality(self):
         self.assertNotEqual(commit2, commit3)
 
     def test_iter_parents(self):
-        # should return all but ourselves, even if skip is defined
+        # Should return all but ourselves, even if skip is defined.
         c = self.rorepo.commit("0.1.5")
         for skip in (0, 1):
             piter = c.iter_parents(skip=skip)
@@ -355,17 +357,17 @@ def test_name_rev(self):
 
     @with_rw_repo("HEAD", bare=True)
     def test_serialization(self, rwrepo):
-        # create all commits of our repo
+        # Create all commits of our repo.
         self.assert_commit_serialization(rwrepo, "0.1.6")
 
     def test_serialization_unicode_support(self):
         self.assertEqual(Commit.default_encoding.lower(), "utf-8")
 
-        # create a commit with unicode in the message, and the author's name
-        # Verify its serialization and deserialization
+        # Create a commit with Unicode in the message, and the author's name.
+        # Verify its serialization and deserialization.
         cmt = self.rorepo.commit("0.1.6")
-        assert isinstance(cmt.message, str)  # it automatically decodes it as such
-        assert isinstance(cmt.author.name, str)  # same here
+        assert isinstance(cmt.message, str)  # It automatically decodes it as such.
+        assert isinstance(cmt.author.name, str)  # Same here.
 
         cmt.message = "üäêèß"
         self.assertEqual(len(cmt.message), 5)
@@ -383,8 +385,8 @@ def test_serialization_unicode_support(self):
 
         self.assertEqual(cmt.author.name, ncmt.author.name)
         self.assertEqual(cmt.message, ncmt.message)
-        # actually, it can't be printed in a shell as repr wants to have ascii only
-        # it appears
+        # Actually, it can't be printed in a shell as repr wants to have ascii only
+        # it appears.
         cmt.author.__repr__()
 
     def test_invalid_commit(self):
@@ -498,14 +500,14 @@ def test_trailers(self):
         KEY_2 = "Key"
         VALUE_2 = "Value with inner spaces"
 
-        # Check the following trailer example is extracted from multiple msg variations
+        # Check that the following trailer example is extracted from multiple msg variations.
         TRAILER = f"{KEY_1}: {VALUE_1_1}\n{KEY_2}: {VALUE_2}\n{KEY_1}: {VALUE_1_2}"
         msgs = [
             f"Subject\n\n{TRAILER}\n",
             f"Subject\n  \nSome body of a function\n \n{TRAILER}\n",
             f"Subject\n  \nSome body of a function\n\nnon-key: non-value\n\n{TRAILER}\n",
             (
-                # check when trailer has inconsistent whitespace
+                # Check when trailer has inconsistent whitespace.
                 f"Subject\n  \nSome multiline\n body of a function\n\nnon-key: non-value\n\n"
                 f"{KEY_1}:{VALUE_1_1}\n{KEY_2} :      {VALUE_2}\n{KEY_1}:    {VALUE_1_2}\n"
             ),
@@ -523,7 +525,7 @@ def test_trailers(self):
                 KEY_2: [VALUE_2],
             }
 
-        # check that trailer stays empty for multiple msg combinations
+        # Check that the trailer stays empty for multiple msg combinations.
         msgs = [
             "Subject\n",
             "Subject\n\nBody with some\nText\n",
@@ -539,7 +541,7 @@ def test_trailers(self):
             assert commit.trailers_list == []
             assert commit.trailers_dict == {}
 
-        # check that only the last key value paragraph is evaluated
+        # Check that only the last key value paragraph is evaluated.
         commit = copy.copy(self.rorepo.commit("master"))
         commit.message = f"Subject\n\nMultiline\nBody\n\n{KEY_1}: {VALUE_1_1}\n\n{KEY_2}: {VALUE_2}\n"
         assert commit.trailers_list == [(KEY_2, VALUE_2)]