Update docstirngs and python version

Signed-off-by: Ayan Sinha Mahapatra <ayansmahapatra@gmail.com>

Author: AyanSinhaMahapatra

setup.cfg

@@ -37,7 +37,7 @@ zip_safe = false
 
 setup_requires = setuptools_scm[toml] >= 4
 
-python_requires = >=3.8
+python_requires = >=3.9
 
 install_requires =
     attrs >= 18.1, !=20.1.0

src/commoncode/hash.py

@@ -26,42 +26,8 @@
 Checksums are operating on files.
 """
 
-
-class Hashable:
-    """
-    A mixin for hashers that provides the base methods.
-    """
-
-    # digest_size = length of binary digest for this hash
-    # binh = binary hasher module
-    # msg_len = length in bytes of the messages hashed
-    # total_length = total length in bytes of the messages hashed
-
-    def digest(self):
-        """
-        Return a bytes string digest for this hash.
-        """
-        if not self.msg_len:
-            return
-        return self.binh.digest()[: self.digest_size]
-
-    def hexdigest(self):
-        """
-        Return a string hex digest for this hash.
-        """
-        return self.msg_len and binascii.hexlify(self.digest()).decode("utf-8")
-
-    def b64digest(self):
-        """
-        Return a string base64 digest for this hash.
-        """
-        return self.msg_len and urlsafe_b64encode(self.digest()).decode("utf-8")
-
-    def intdigest(self):
-        """
-        Return a int digest for this hash.
-        """
-        return self.msg_len and int(bin_to_num(self.digest()))
+# This is ~16 MB
+FILE_CHUNK_SIZE = 2**24
 
 
 def _hash_mod(bitsize, hmodule):
@@ -78,9 +44,15 @@ def __init__(self, msg=None, **kwargs):
             Return a hasher, populated with an initial ``msg`` bytes string.
             Close on the bitsize and hmodule
             """
+            # length of binary digest for this hash
             self.digest_size = bitsize // 8
+
+            # binh = binary hasher module
             self.binh = hmodule()
+
+            # msg_len = length in bytes of the message hashed
             self.msg_len = 0
+
             if msg:
                 self.update(msg)
 
@@ -95,13 +67,43 @@ def update(self, msg=None):
     return hasher
 
 
+class Hashable:
+    """
+    A mixin for hashers that provides the base methods.
+    """
+
+    def digest(self):
+        """
+        Return a bytes string digest for this hash.
+        """
+        if not self.msg_len:
+            return
+        return self.binh.digest()[: self.digest_size]
+
+    def hexdigest(self):
+        """
+        Return a string hex digest for this hash.
+        """
+        return self.msg_len and binascii.hexlify(self.digest()).decode("utf-8")
+
+    def b64digest(self):
+        """
+        Return a string base64 digest for this hash.
+        """
+        return self.msg_len and urlsafe_b64encode(self.digest()).decode("utf-8")
+
+    def intdigest(self):
+        """
+        Return a int digest for this hash.
+        """
+        return self.msg_len and int(bin_to_num(self.digest()))
+
+
 # for FIPS support, we declare that "usedforsecurity" is False
 sys_v0 = sys.version_info[0]
 sys_v1 = sys.version_info[1]
-if sys_v0 == 3 and sys_v1 >= 9:
-    md5_hasher = partial(hashlib.md5, usedforsecurity=False)
-else:
-    md5_hasher = hashlib.md5
+md5_hasher = partial(hashlib.md5, usedforsecurity=False)
+
 
 # Base hashers for each bit size
 _hashmodules_by_bitsize = {
@@ -135,6 +137,9 @@ def __init__(self, msg=None, total_length=0, **kwargs):
         Initialize a sha1_git_hasher with an optional ``msg`` byte string. The ``total_length`` of
         all content that will be hashed, combining the ``msg`` length plus any later call to
         update() with additional messages.
+
+        Here ``total_length`` is total length in bytes of all the messages (chunks) hashed
+        in contrast to  ``msg_len`` which is the length in bytes for the optional message.
         """
         self.digest_size = 160 // 8
         self.msg_len = 0
@@ -235,6 +240,19 @@ def checksum_from_chunks(chunks, name, total_length=0, base64=False):
     return hasher.hexdigest()
 
 
+def binary_chunks(location, size=FILE_CHUNK_SIZE):
+    """
+    Read file at ``location`` as binary and yield bytes of up to ``size`` length in bytes,
+    defaulting to 2**24 bytes, e.g., about 16 MB.
+    """
+    with open(location, "rb") as f:
+        while True:
+            chunk = f.read(size)
+            if not chunk:
+                break
+            yield chunk
+
+
 def md5(location):
     return checksum(location, name="md5", base64=False)
 
@@ -259,26 +277,16 @@ def sha1_git(location):
     return checksum(location, name="sha1_git", base64=False)
 
 
-def binary_chunks(location, size=2**24):
-    """
-    Read file at ``location`` as binary and yield bytes of up to ``size`` length in bytes,
-    defaulting to 2**24 bytes, e.g., about 16 MB.
-    """
-    with open(location, "rb") as f:
-        while True:
-            chunk = f.read(size)
-            if not chunk:
-                break
-            yield chunk
-
-
 def multi_checksums(location, checksum_names=("md5", "sha1", "sha256", "sha512", "sha1_git")):
     """
     Return a mapping of hexdigest checksum strings keyed by checksum algorithm name from hashing the
     content of the file at ``location``. Use the ``checksum_names`` list of checksum names. The
     mapping is guaranted to contains all the requested names as keys. If the location is not a file,
     or if the file is empty, the values are None.
-    The purpose of this function is
+
+    The purpose of this function is to return a set of checksums for a supported set of checksum
+    algorithms for a given location. This is an API function used in ScanCode --info plugin to get
+    checksum values. 
     """
     if not filetype.is_file(location):
         return {name: None for name in checksum_names}