More wording improvements (in git module)

EliahKagan · EliahKagan · commit f444470bc261 · 2023-10-22T21:14:25.000-04:00
This futher improves some wording in docstrings and comments in a
handful of places within the git module.
diff --git a/git/cmd.py b/git/cmd.py
@@ -610,7 +610,7 @@ class CatFileContentStream:
         stream once our sized content region is empty.
 
         If not all data are read to the end of the object's lifetime, we read the
-        rest to assure the underlying stream continues to work.
+        rest to ensure the underlying stream continues to work.
         """
 
         __slots__: Tuple[str, ...] = ("_stream", "_nbr", "_size")
diff --git a/git/config.py b/git/config.py
@@ -56,7 +56,7 @@
 T_OMD_value = TypeVar("T_OMD_value", str, bytes, int, float, bool)
 
 if sys.version_info[:3] < (3, 7, 2):
-    # typing.Ordereddict not added until py 3.7.2
+    # typing.Ordereddict not added until Python 3.7.2.
     from collections import OrderedDict
 
     OrderedDict_OMD = OrderedDict
@@ -73,13 +73,10 @@
 log = logging.getLogger("git.config")
 log.addHandler(logging.NullHandler())
 
-# invariants
-# represents the configuration level of a configuration file
-
 
+# The configuration level of a configuration file.
 CONFIG_LEVELS: ConfigLevels_Tup = ("system", "user", "global", "repository")
 
-
 # Section pattern to detect conditional includes.
 # https://git-scm.com/docs/git-config#_conditional_includes
 CONDITIONAL_INCLUDE_REGEXP = re.compile(r"(?<=includeIf )\"(gitdir|gitdir/i|onbranch):(.+)\"")
@@ -603,7 +600,7 @@ def read(self) -> None:  # type: ignore[override]
             files_to_read = [self._file_or_files]
         else:  # for lists or tuples
             files_to_read = list(self._file_or_files)
-        # end assure we have a copy of the paths to handle
+        # end ensure we have a copy of the paths to handle
 
         seen = set(files_to_read)
         num_read_include_files = 0
@@ -612,7 +609,7 @@ def read(self) -> None:  # type: ignore[override]
             file_ok = False
 
             if hasattr(file_path, "seek"):
-                # Must be a file objectfile-object.
+                # Must be a file-object.
                 file_path = cast(IO[bytes], file_path)  # TODO: Replace with assert to narrow type, once sure.
                 self._read(file_path, file_path.name)
             else:
@@ -626,7 +623,7 @@ def read(self) -> None:  # type: ignore[override]
                     continue
 
             # Read includes and append those that we didn't handle yet.
-            # We expect all paths to be normalized and absolute (and will assure that is the case).
+            # We expect all paths to be normalized and absolute (and will ensure that is the case).
             if self._has_includes():
                 for _, include_path in self._included_paths():
                     if include_path.startswith("~"):
diff --git a/git/diff.py b/git/diff.py
@@ -122,8 +122,8 @@ def diff(
               the respective tree.
             * If :class:`Index <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 <Diffable.Index>` to assure the method will
-              not by-default fail on bare repositories.
+            * It defaults to :class:`Index <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
diff --git a/git/index/base.py b/git/index/base.py
@@ -340,9 +340,9 @@ def from_tree(cls, repo: "Repo", *treeish: Treeish, **kwargs: Any) -> "IndexFile
             resolve more cases in a commonly correct manner. Specify trivial=True as kwarg
             to override that.
 
-            As the underlying git-read-tree command takes into account the current index,
-            it will be temporarily moved out of the way to assure there are no unsuspected
-            interferences.
+            As the underlying git-read-tree command takes into account the current
+            index, it will be temporarily moved out of the way to prevent any unexpected
+            interference.
         """
         if len(treeish) == 0 or len(treeish) > 3:
             raise ValueError("Please specify between 1 and 3 treeish, got %i" % len(treeish))
@@ -366,7 +366,7 @@ def from_tree(cls, repo: "Repo", *treeish: Treeish, **kwargs: Any) -> "IndexFile
             # Move current index out of the way - otherwise the merge may fail
             # as it considers existing entries. Moving it essentially clears the index.
             # Unfortunately there is no 'soft' way to do it.
-            # The TemporaryFileSwap assure the original file get put back.
+            # The TemporaryFileSwap ensures the original file gets put back.
 
             stack.enter_context(TemporaryFileSwap(join_path_native(repo.git_dir, "index")))
             repo.git.read_tree(*arg_list, **kwargs)
diff --git a/git/objects/submodule/root.py b/git/objects/submodule/root.py
@@ -133,7 +133,7 @@ def update(
 
         if progress is None:
             progress = RootUpdateProgress()
-        # END assure progress is set
+        # END ensure progress is set
 
         prefix = ""
         if dry_run:
@@ -300,7 +300,7 @@ def update(
                                 smr.rename(orig_name)
 
                                 # Early on, we verified that the our current tracking branch
-                                # exists in the remote. Now we have to assure that the
+                                # exists in the remote. Now we have to ensure that the
                                 # sha we point to is still contained in the new remote
                                 # tracking branch.
                                 smsha = sm.binsha
@@ -367,7 +367,7 @@ def update(
                             except OSError:
                                 # ...or reuse the existing one.
                                 tbr = git.Head(smm, sm.branch_path)
-                            # END assure tracking branch exists
+                            # END ensure tracking branch exists
 
                             tbr.set_tracking_branch(find_first_remote_branch(smmr, sm.branch_name))
                             # NOTE: All head-resetting is done in the base implementation of update
diff --git a/git/objects/tree.py b/git/objects/tree.py
@@ -180,8 +180,8 @@ def add(self, sha: bytes, mode: int, name: str, force: bool = False) -> "TreeMod
         return self
 
     def add_unchecked(self, binsha: bytes, mode: int, name: str) -> None:
-        """Add the given item to the tree. Its correctness is assumed, which
-        puts the caller into responsibility to assure the input is correct.
+        """Add the given item to the tree. Its correctness is assumed, so it is the
+        caller's responsibility to ensure that the input is correct.
 
         For more information on the parameters, see :meth:`add`.
 
diff --git a/git/repo/base.py b/git/repo/base.py
@@ -1448,7 +1448,7 @@ def archive(
         path = cast(Union[PathLike, List[PathLike], Tuple[PathLike, ...]], path)
         if not isinstance(path, (tuple, list)):
             path = [path]
-        # end assure paths is list
+        # end ensure paths is list (or tuple)
         self.git.archive("--", treeish, *path, **kwargs)
         return self
 
diff --git a/git/util.py b/git/util.py
@@ -283,7 +283,7 @@ def to_native_path_linux(path: PathLike) -> str:
 def join_path_native(a: PathLike, *p: PathLike) -> PathLike:
     R"""Like join_path, but makes sure an OS native path is returned.
 
-    This is only needed to play it safe on Windows and to assure nice paths that only
+    This is only needed to play it safe on Windows and to ensure nice paths that only
     use '\'.
     """
     return to_native_path(join_path(a, *p))
@@ -1185,8 +1185,8 @@ def __init__(cls, name: str, bases: Tuple, clsdict: Dict) -> None:
 
 
 class Iterable(metaclass=IterableClassWatcher):
-    """Defines an interface for iterable items which is to assure a uniform
-    way to retrieve and iterate items within the git repository."""
+    """Defines an interface for iterable items, so there is a uniform way to retrieve
+    and iterate items within the git repository."""
 
     __slots__ = ()
 
@@ -1221,8 +1221,8 @@ def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Any:
 
 @runtime_checkable
 class IterableObj(Protocol):
-    """Defines an interface for iterable items which is to assure a uniform
-    way to retrieve and iterate items within the git repository.
+    """Defines an interface for iterable items, so there is a uniform way to retrieve
+    and iterate items within the git repository.
 
     Subclasses = [Submodule, Commit, Reference, PushInfo, FetchInfo, Remote]
     """
