Merge branch 'main' into improve-readme

README.md

@@ -323,7 +323,7 @@ python3 -m venv .venv
 Next install the project in editable mode with development dependencies:
 
 ```bash
-pip install -m .[dev]
+pip install -e '.[dev]'
 ```
 
 Note: You may need to install the development package for `libgpgme` on your

src/bmaptool/BmapCopy.py

@@ -40,11 +40,11 @@
 it is beneficial to distributor them as compressed files along with the bmap.
 
 Here is an example. Suppose you have a 4GiB image which contains only 100MiB of
-user data and you need to flash it to a slow USB stick. With bmap you end up
+user data, and you need to flash it to a slow USB stick. With bmap you end up
 copying only a little bit more than 100MiB of data from the image to the USB
 stick (namely, you copy only mapped blocks). This is a lot faster than copying
 all 4GiB of data. We say that it is a bit more than 100MiB because things like
-file-system meta-data (inode tables, superblocks, etc), partition table, etc
+file-system meta-data (inode tables, superblocks, etc.), partition table, etc.
 also contribute to the mapped blocks and are also copied.
 """
 
@@ -181,13 +181,13 @@ class BmapCopy(object):
     to the destination file.
 
     When the bmap is provided, it is not necessary to specify image size,
-    because the size is contained in the bmap. Otherwise, it is benefitial to
+    because the size is contained in the bmap. Otherwise, it is beneficial to
     specify the size because it enables extra sanity checks and makes it
     possible to provide the progress bar.
 
     When the image size is known either from the bmap or the caller specified
     it to the class constructor, all the image geometry description attributes
-    ('blocks_cnt', etc) are initialized by the class constructor and available
+    ('blocks_cnt', etc.) are initialized by the class constructor and available
     for the user.
 
     However, when the size is not known, some of  the image geometry
@@ -308,8 +308,8 @@ def set_psplash_pipe(self, path):
         functionality which might or might not be available even if requested.
         When used as a boot service, the unavailability of the psplash service
         (due to various reasons: no screen, racing issues etc.) should not
-        break the writting process. This is why this implementation is done as
-        a best effort.
+        break the writing process. This is why this implementation is done as
+        a best-effort.
         """
 
         if os.path.exists(path) and stat.S_ISFIFO(os.stat(path).st_mode):
@@ -321,7 +321,7 @@ def set_psplash_pipe(self, path):
 
     def set_progress_indicator(self, file_obj, format_string):
         """
-        Setup the progress indicator which shows how much data has been copied
+        Set up the progress indicator which shows how much data has been copied
         in percent.
 
         The 'file_obj' argument is the console file object where the progress
@@ -368,7 +368,7 @@ def _verify_bmap_checksum(self):
 
         correct_chksum = self._xml.find(self._bmap_cs_attrib_name).text.strip()
 
-        # Before verifying the shecksum, we have to substitute the checksum
+        # Before verifying the checksum, we have to substitute the checksum
         # value stored in the file with all zeroes. For these purposes we
         # create private memory mapping of the bmap file.
         mapped_bmap = mmap.mmap(self._f_bmap.fileno(), 0, access=mmap.ACCESS_COPY)
@@ -399,7 +399,7 @@ def _parse_bmap(self):
         try:
             self._xml = ElementTree.parse(self._f_bmap)
         except ElementTree.ParseError as err:
-            # Extrace the erroneous line with some context
+            # Extract the erroneous line with some context
             self._f_bmap.seek(0)
             xml_extract = ""
             for num, line in enumerate(self._f_bmap):
@@ -450,7 +450,7 @@ def _parse_bmap(self):
             # was SHA1. Version 2.0 started supporting arbitrary checksum
             # types. A new "ChecksumType" tag was introduce to specify the
             # checksum function name. And all XML tags which contained "sha1"
-            # in their name were renamed to something more neutral. This was an
+            # in their name were renamed to something more neutral. This was a
             # change incompatible with previous formats.
             #
             # There is a special format version 1.4, which should not have been
@@ -523,7 +523,7 @@ def _update_progress(self, blocks_written):
             self._progress_file.write(progress)
             self._progress_file.flush()
 
-        # Update psplash progress when configured. This is using a best effort
+        # Update psplash progress when configured. This is using a best-effort
         # strategy to not affect the writing process when psplash breaks, is
         # not available early enough or screen is not available.
         if self._psplash_pipe and self.mapped_cnt:
@@ -845,7 +845,7 @@ def __init__(self, image, dest, bmap=None, image_size=None):
             os.minor(st_rdev),
         )
 
-        # Check if the 'queue' sub-directory exists. If yes, then our block
+        # Check if the 'queue' subdirectory exists. If yes, then our block
         # device is entire disk. Otherwise, it is a partition, in which case we
         # need to go one level up in the sysfs hierarchy.
         if not os.path.exists(self._sysfs_base + "queue"):
@@ -872,7 +872,7 @@ def copy(self, sync=True, verify=True):
         # 1. Switch to the 'none' (the successor of 'noop' since the switch to
         #    multiqueue schedulers) I/O scheduler if it is available - sequential
         #    write to the block device becomes a lot faster comparing to CFQ.
-        # 2. Limit the write buffering - we do not need the kernel to buffer a lot of
+        # 2. Limit write buffering - we do not need the kernel to buffer a lot of
         #    the data we send to the block device, because we write sequentially.
         #    Excessive buffering would make some systems quite unresponsive.
         #    This was observed e.g. in Fedora 17.

src/bmaptool/BmapCreate.py

@@ -18,7 +18,7 @@
 This module implements the block map (bmap) creation functionality and provides
 the corresponding API in form of the 'BmapCreate' class.
 
-The idea is that while images files may generally be very large (e.g., 4GiB),
+The idea is that while image files may generally be very large (e.g., 4GiB),
 they may nevertheless contain only little real data, e.g., 512MiB. This data
 are files, directories, file-system meta-data, partition table, etc. When
 copying the image to the target device, you do not have to copy all the 4GiB of
@@ -264,7 +264,7 @@ def _bmap_file_start(self):
             "    <!-- The block map which consists of elements which may either be a\n"
         )
         xml += "         range of blocks or a single block. The 'chksum' attribute\n"
-        xml += "         (if present) is the checksum of this blocks range. -->\n"
+        xml += "         (if present) is the checksum of this block range. -->\n"
         xml += "    <BlockMap>\n"
         # pylint: enable=C0301
 

src/bmaptool/BmapHelpers.py

@@ -88,7 +88,7 @@ def get_block_size(file_obj):
 
 def program_is_available(name):
     """
-    This is a helper function which check if the external program 'name' is
+    This is a helper function which checks if the external program 'name' is
     available in the system.
     """
 

src/bmaptool/CLI.py

@@ -238,7 +238,7 @@ def verify_detached_bmap_signature(args, bmap_obj, bmap_path):
 def verify_clearsign_bmap_signature(args, bmap_obj):
     """
     This is a helper function for 'verify_bmap_signature()' which handles the
-    clarsign signature case.
+    clearsign signature case.
     """
 
     if args.bmap_sig:
@@ -307,7 +307,7 @@ def verify_bmap_signature(args, bmap_obj, bmap_path):
     In case of the clearsign signature, the bmap file has "invalid" format,
     meaning that the proper bmap XML contents is in the GPG clearsign
     container. The XML contents has to be extracted from the container before
-    further processing. And this is be done even if user specified the
+    further processing. And this is done even if user specified the
     --no-sig-verify option. This function returns an open file object with the
     extracted XML bmap file contents in this case. Otherwise, this function
     returns None.
@@ -464,7 +464,7 @@ def open_files(args):
     # We just create the "/dev/misspelled" file, write the data there, and
     # report success. Later on the user finds out that the image was not really
     # written to the device, and gets confused. Similar confusion may happen if
-    # the destination file is not a special device for some reasons.
+    # the destination file is not a special device for some reason.
     if os.path.normpath(args.dest).startswith("/dev/"):
         if not os.path.exists(args.dest):
             log.warning(
@@ -478,7 +478,7 @@ def open_files(args):
             )
 
     # Try to open the destination file. If it does not exist, a new regular
-    # file will be created. If it exists and it is a regular file - it'll be
+    # file will be created. If it exists, and it is a regular file, it'll be
     # truncated. If this is a block device, it'll just be opened.
     dest_is_blkdev = False
     try:
@@ -623,7 +623,7 @@ def create_command(args):
     target device.
     """
 
-    # Create and setup the output stream
+    # Create and set up the output stream
     if args.output:
         try:
             output = open(args.output, "w+")
@@ -724,7 +724,7 @@ def parse_arguments():
     parser_copy.add_argument("--bmap-sig", help=text)
 
     # The --no-sig-verify option
-    text = "do not verify bmap file GPG signatrue"
+    text = "do not verify bmap file GPG signature"
     parser_copy.add_argument("--no-sig-verify", action="store_true", help=text)
 
     # The --no-verify option
@@ -778,7 +778,7 @@ def __init__(self, fmt=None, datefmt=None):
 
         def format(self, record):
             """
-            The formatter which which simply prefixes all debugging messages
+            The formatter which simply prefixes all debugging messages
             with a time-stamp.
             """
 

src/bmaptool/Filemap.py

@@ -132,7 +132,7 @@ def _open_image_file(self):
 
     def block_is_mapped(self, block):  # pylint: disable=W0613,R0201
         """
-        This method has has to be implemented by child classes. It returns
+        This method has to be implemented by child classes. It returns
         'True' if block number 'block' of the image file is mapped and 'False'
         otherwise.
         """
@@ -141,7 +141,7 @@ def block_is_mapped(self, block):  # pylint: disable=W0613,R0201
 
     def block_is_unmapped(self, block):  # pylint: disable=W0613,R0201
         """
-        This method has has to be implemented by child classes. It returns
+        This method has to be implemented by child classes. It returns
         'True' if block number 'block' of the image file is not mapped (hole)
         and 'False' otherwise.
         """
@@ -150,7 +150,7 @@ def block_is_unmapped(self, block):  # pylint: disable=W0613,R0201
 
     def get_mapped_ranges(self, start, count):  # pylint: disable=W0613,R0201
         """
-        This method has has to be implemented by child classes. This is a
+        This method has to be implemented by child classes. This is a
         generator which yields ranges of mapped blocks in the file. The ranges
         are tuples of 2 elements: [first, last], where 'first' is the first
         mapped block and 'last' is the last mapped block.
@@ -163,7 +163,7 @@ def get_mapped_ranges(self, start, count):  # pylint: disable=W0613,R0201
 
     def get_unmapped_ranges(self, start, count):  # pylint: disable=W0613,R0201
         """
-        This method has has to be implemented by child classes. Just like
+        This method has to be implemented by child classes. Just like
         'get_mapped_ranges()', but yields unmapped block ranges instead
         (holes).
         """
@@ -181,7 +181,7 @@ def _lseek(file_obj, offset, whence):
     'file_obj' and with specified 'offset' and 'whence'. The 'whence'
     argument is supposed to be either '_SEEK_DATA' or '_SEEK_HOLE'. When
     there is no more data or hole starting from 'offset', this function
-    returns '-1'.  Otherwise the data or hole position is returned."""
+    returns '-1'.  Otherwise, the data or hole position is returned."""
 
     try:
         return os.lseek(file_obj.fileno(), offset, whence)
@@ -207,7 +207,7 @@ class FilemapSeek(_FilemapBase):
     """
 
     def __init__(self, image):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
 
         # Call the base class constructor first
         _FilemapBase.__init__(self, image)
@@ -259,7 +259,7 @@ def _probe_seek_hole(self):
         tmp_obj.close()
 
     def block_is_mapped(self, block):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         offs = _lseek(self._f_image, block * self.block_size, _SEEK_DATA)
         if offs == -1:
             result = False
@@ -270,7 +270,7 @@ def block_is_mapped(self, block):
         return result
 
     def block_is_unmapped(self, block):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         return not self.block_is_mapped(block)
 
     def _get_ranges(self, start, count, whence1, whence2):
@@ -301,15 +301,15 @@ def _get_ranges(self, start, count, whence1, whence2):
             yield (start_blk, end_blk)
 
     def get_mapped_ranges(self, start, count):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         _log.debug(
             "FilemapSeek: get_mapped_ranges(%d,  %d(%d))"
             % (start, count, start + count - 1)
         )
         return self._get_ranges(start, count, _SEEK_DATA, _SEEK_HOLE)
 
     def get_unmapped_ranges(self, start, count):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         _log.debug(
             "FilemapSeek: get_unmapped_ranges(%d,  %d(%d))"
             % (start, count, start + count - 1)
@@ -336,8 +336,8 @@ def get_unmapped_ranges(self, start, count):
 # reading the block map
 _FIEMAP_FLAG_SYNC = 0x00000001
 # Size of the buffer for 'struct fiemap_extent' elements which will be used
-# when invoking the FIEMAP ioctl. The larger is the buffer, the less times the
-# FIEMAP ioctl will be invoked.
+# when invoking the FIEMAP ioctl. With a larger buffer, the FIEMAP ioctl will
+# be invoked fewer times.
 _FIEMAP_BUFFER_SIZE = 256 * 1024
 
 
@@ -352,8 +352,8 @@ class FilemapFiemap(_FilemapBase):
 
     def __init__(self, image):
         """
-        Initialize a class instance. The 'image' argument is full the file
-        object to operate on.
+        Initialize a class instance. The 'image' argument is the file object
+        to operate on.
         """
 
         # Call the base class constructor first
@@ -433,7 +433,7 @@ def _invoke_fiemap(self, block, count):
         return struct.unpack(_FIEMAP_FORMAT, self._buf[:_FIEMAP_SIZE])
 
     def block_is_mapped(self, block):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         struct_fiemap = self._invoke_fiemap(block, 1)
 
         # The 3rd element of 'struct_fiemap' is the 'fm_mapped_extents' field.
@@ -444,7 +444,7 @@ def block_is_mapped(self, block):
         return result
 
     def block_is_unmapped(self, block):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         return not self.block_is_mapped(block)
 
     def _unpack_fiemap_extent(self, index):
@@ -505,7 +505,7 @@ def _do_get_mapped_ranges(self, start, count):
             block = extent_block + extent_count
 
     def get_mapped_ranges(self, start, count):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         _log.debug(
             "FilemapFiemap: get_mapped_ranges(%d,  %d(%d))"
             % (start, count, start + count - 1)
@@ -531,7 +531,7 @@ def get_mapped_ranges(self, start, count):
         yield (first_prev, last_prev)
 
     def get_unmapped_ranges(self, start, count):
-        """Refer the '_FilemapBase' class for the documentation."""
+        """Refer to the '_FilemapBase' class for the documentation."""
         _log.debug(
             "FilemapFiemap: get_unmapped_ranges(%d,  %d(%d))"
             % (start, count, start + count - 1)