code: fix typos and grammar

Author: ThomasWaldmann

src/borg_import/borg.py

@@ -4,8 +4,8 @@
 
 
 def get_borg_archives(repository):
-    """Get all archive metadata discovered in the Borg repository."""
-    # Get list of archives with their timestamps
+    """Return metadata for all archives discovered in the Borg repository."""
+    # Get a list of archives with their timestamps
     borg_cmdline = ["borg", "list", "--format", "{name}{TAB}{time}{NL}", repository]
     output = subprocess.check_output(borg_cmdline).decode()
 

src/borg_import/helpers/discover.py

@@ -4,7 +4,7 @@
 
 def discover(root, depth):
     """
-    recurse starting from <root> path and yield relative dir paths with wanted <depth>.
+    Recurse from the given root path and yield relative directory paths at the specified depth.
     """
 
     def _discover(root, current_dir, current_depth, wanted_depth):
@@ -23,6 +23,7 @@ def _discover(root, current_dir, current_depth, wanted_depth):
 
 
 def parser(rel_path, regex):
+    """Parse rel_path with regex and return a dict of named groups, or None if no match."""
     m = re.match(regex, rel_path)
     if m:
         return m.groupdict()

src/borg_import/helpers/names.py

@@ -3,17 +3,17 @@
 
 def make_name(*args, dt_format="%Y-%m-%dT%H:%M:%S"):
     """
-    assemble borg archive names from components.
+    Assemble Borg archive names from components.
 
-    args can be anything that converts to str, plus:
+    Arguments can be anything that converts to str, plus:
 
         - bytes objects, which are safely decoded
         - datetime objects, which are formatted using dt_format
 
-    invalid chars are replaced or removed, so the resulting archive name
+    Invalid characters are replaced or removed, so the resulting archive name
     should be valid.
 
-    E.g.:
+    Examples:
         make_name(b'hostname', b'üser', 1)
         -> 'hostname-üser-1'
 
@@ -28,12 +28,12 @@ def make_name(*args, dt_format="%Y-%m-%dT%H:%M:%S"):
             s = arg.strftime(dt_format)
         else:
             s = str(arg)
-        # we don't want to have blanks for practical shell-usage reasons:
+        # Avoid spaces for practical shell-usage reasons:
         s = s.replace(" ", "_")
-        # the slash is not allowed in archive names
+        # A slash is not allowed in archive names
         # (archive name = FUSE directory name)
         s = s.replace("/", "!")
-        # :: is repo::archive separator, not allowed in archive names
+        # "::" is the repo::archive separator, not allowed in archive names
         s = s.replace("::", ":")
         components.append(s)
     return "-".join(components)

src/borg_import/helpers/testsuite/test_names.py

@@ -4,7 +4,7 @@
 
 
 def test_make_name():
-    # str (some with invalid/unwanted chars)
+    # str (some with invalid/unwanted characters)
     assert make_name("backup name") == "backup_name"
     assert make_name("backup/name") == "backup!name"
     assert make_name("backup::name") == "backup:name"

src/borg_import/helpers/testsuite/test_timestamps.py

@@ -21,8 +21,8 @@ def test_datetime_from_string():
     dfs = datetime_from_string("1999-12-31T23:59:59")
     dt_trg = datetime(1999, 12, 31, 23, 59, 59).astimezone(tz=timezone.utc)
     assert dfs == dt_trg
-    # Of course, two datetimes can be equal in different timezones. Make
-    # sure the timezone info matches UTC, which borg itself expects.
+    # Two datetimes can be equal in different time zones. Make
+    # sure the time zone info matches UTC, which Borg itself expects.
     assert dfs.tzinfo == dt_trg.tzinfo == timezone.utc
 
     # FIXME: When this format is passed to datetime_from_string, the internal
@@ -34,7 +34,7 @@ def test_datetime_from_string():
     assert dfs == dt_trg
     assert dfs.tzinfo == dt_trg.tzinfo == timezone.utc
 
-    # rsync-time-backup format.
+    # rsync-time-backup format:
     dfs = datetime_from_string("2022-12-21-063019")
     dt_trg = datetime(2022, 12, 21, 6, 30, 19).astimezone(tz=timezone.utc)
     assert dfs == dt_trg

src/borg_import/helpers/timestamps.py

@@ -3,25 +3,24 @@
 
 def datetime_from_mtime(path):
     """
-    discover backup timestamp from a (single) filesystem object.
+    Discover the backup timestamp from a (single) filesystem object.
 
-    e.g. from a root/TIMESTAMP file created by "touch" at backup time,
+    For example, from a root/TIMESTAMP file created by "touch" at backup time,
     or from root/ (assuming that the directory timestamp was modified
     at backup time).
     """
     t = path.stat().st_mtime
-    # Borg needs tz-aware timestamps in UTC timezone.
+    # Borg needs timezone-aware timestamps in UTC.
     return datetime.fromtimestamp(t, tz=timezone.utc)
 
 
 def datetime_from_string(s):
     """
-    parse datetime from a string
+    Parse a datetime from a string.
 
-    returns a tz-aware datetime object in UTC timezone if the format could be
-    parsed.
+    Return a timezone-aware datetime object in UTC if the format could be parsed.
 
-    raises ValueError if not.
+    Raise ValueError otherwise.
     """
     s = s.strip()
     for ts_format in [
@@ -40,36 +39,36 @@ def datetime_from_string(s):
     ]:
         try:
             if ts_format in ("%a %b %d %H:%M:%S %Z %Y",) and "UTC" in s:
-                # %Z returns a naive datetime, despite a timezone being specified.
+                # %Z returns a naive datetime, despite a time zone being specified.
                 # However, strptime %Z only tends to work on local times and
                 # UTC.
                 #
                 # Per astimezone docs:
                 # If self is naive, it is presumed to represent time in the
-                # system timezone.
+                # system time zone.
                 #
-                # If we had a UTC timezone, prevent conversion to aware
-                # datetime from assuming a local timezone before conversion
+                # If we had a UTC time zone, prevent conversion to an aware
+                # datetime from assuming a local time zone before conversion
                 # to UTC.
                 return datetime.strptime(s, ts_format).replace(tzinfo=timezone.utc)
             else:
                 # If "UTC" wasn't specified using the above ts_format, assume
-                # the timezone specified was local and hope for the best.
+                # the time zone specified was local and hope for the best.
                 # This handles all other ts_formats as well, which are assumed
-                # to be local since they don't carry timezone.
+                # to be local since they don't carry a time zone.
                 return datetime.strptime(s, ts_format).astimezone(tz=timezone.utc)
         except ValueError:
-            # didn't work with this format, try next
+            # Didn't work with this format; try the next.
             pass
     else:
         raise ValueError("could not parse %r" % s)
 
 
 def datetime_from_file(path):
     """
-    discover backup timestamp from contents of a file.
+    Discover the backup timestamp from the contents of a file.
 
-    e.g. root/TIMESTAMP contains: Mon Oct 31 23:35:50 CET 2016
+    For example, root/TIMESTAMP contains: Mon Oct 31 23:35:50 CET 2016
     """
     with path.open() as f:
         ts = f.readline().strip()

src/borg_import/main.py

@@ -33,7 +33,7 @@ def borg_import(args, archive_name, path, timestamp=None):
     except subprocess.CalledProcessError as cpe:
         if cpe.returncode != 1:
             raise
-        log.debug("Borg exited with a warning (being quiet about it since Borg spoke already)")
+        log.debug("Borg exited with a warning (not repeating details since Borg already reported them)")
 
 
 def list_borg_archives(args):
@@ -72,7 +72,7 @@ class rsnapshotImporter(Importer):
 
     The directory is called "borg-import-dir" inside the rsnapshot root,
     and borg-import will note which snapshot is currently located there
-    in a file called "borg-import-dir.snapshot" besides it, in case
+    in a file called "borg-import-dir.snapshot" beside it, in case
     things go wrong.
 
     Otherwise nothing in the rsnapshot root is modified, and neither
@@ -146,7 +146,7 @@ def import_rsnapshot(self, args):
 
 class rsynchlImporter(Importer):
     name = "rsynchl"
-    description = "import rsync+hardlink backups"
+    description = "import rsync-with-hard-links backups"
     epilog = """
     Imports from rsync backup sets by renaming each snapshot to a common
     name independent of the snapshot, which allows the Borg files cache
@@ -159,7 +159,7 @@ class rsynchlImporter(Importer):
 
     The directory is called "borg-import-dir" inside the specified root,
     and borg-import will note which snapshot is currently located there
-    in a file called "borg-import-dir.snapshot" besides it, in case
+    in a file called "borg-import-dir.snapshot" beside it, in case
     things go wrong.
 
     Otherwise nothing in the rsync root is modified, and neither
@@ -237,7 +237,7 @@ class rsyncTmBackupImporter(Importer):
 
     The directory is called "borg-import-dir" inside the specified root,
     and borg-import will note which snapshot is currently located there
-    in a file called "borg-import-dir.snapshot" besides it, in case
+    in a file called "borg-import-dir.snapshot" beside it, in case
     things go wrong.
 
     Otherwise nothing in the rsync root is modified, and neither
@@ -305,7 +305,7 @@ class borgImporter(Importer):
     This is useful when a Borg repository needs to be rebuilt and all archives
     transferred from the old repository to a new one.
 
-    The importer extracts each archive from the source repository to a intermediate
+    The importer extracts each archive from the source repository to an intermediate
     directory inside the current work directory (make sure there is enough space!)
     and then creates a new archive with the same name and timestamp in the destination
     repository.
@@ -419,7 +419,7 @@ def build_parser():
 
 def main():
     if not shutil.which("borg"):
-        print("The 'borg' command can't be found in the PATH. Please correctly install borgbackup first.")
+        print("The 'borg' command cannot be found in PATH. Please install BorgBackup first.")
         print("See instructions at https://borgbackup.readthedocs.io/en/stable/installation.html")
         return 1
 

src/borg_import/rsnapshots.py

@@ -6,7 +6,7 @@
 
 
 def get_snapshots(root):
-    """Get all snapshot metadata discovered in the rsnapshot root directory."""
+    """Return metadata for all snapshots discovered in the rsnapshot root directory."""
     regex = re.compile(r"(?P<snapshot_id>.+)/(?P<backup_set>.+)")
     for path in discover(str(root), 2):
         parsed = parser(path, regex)

src/borg_import/rsync_tmbackup.py

@@ -7,11 +7,11 @@
 
 
 def get_tmbackup_snapshots(root, prefix):
-    """Get all snapshot metadata discovered in the rsync root directory."""
+    """Return metadata for all snapshots discovered in the rsync root directory."""
     regex = re.compile(r"(?P<snapshot_date>.+)")
 
     if not Path("backup.marker").exists():
-        raise FileNotFoundError("backup.marker file should exist for rsync-time-backup import")
+        raise FileNotFoundError("The backup.marker file must exist for rsync-time-backup import")
 
     for path in discover(str(root), 1):
         parsed = parser(path, regex)
@@ -24,9 +24,9 @@ def get_tmbackup_snapshots(root, prefix):
             )
             yield meta
         elif parsed["snapshot_date"] in ("latest",):
-            # latest is a symlink to the most recent build. Import it anyway
-            # in case user wants to do borg mount/has existing references
-            # to latest.
+            # "latest" is a symlink to the most recent backup. Import it anyway
+            # in case the user wants to do borg mount or has existing references
+            # to "latest".
             abs_path = root / path
             timestamp = Path("latest").resolve().name
             meta = dict(

src/borg_import/rsynchl.py

@@ -6,7 +6,7 @@
 
 
 def get_rsyncsnapshots(root):
-    """Get all snapshot metadata discovered in the rsync root directory."""
+    """Return metadata for all snapshots discovered in the rsync root directory."""
     regex = re.compile(r"(?P<snapshot_name>.+)")
     for path in discover(str(root), 1):
         parsed = parser(path, regex)