From d26dac9e2f8a70eea04bca4f15adfb35009c9675 Mon Sep 17 00:00:00 2001
From: Will Woods <w@wizard.zone>
Date: Mon, 5 Apr 2021 12:53:08 -0400
Subject: [PATCH] comment cleanups etc. no code changes.

---
 COOLRPMS.md         | 10 ++++++++++
 rpmtoys/__init__.py | 26 +++++++++++++++++++-------
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/COOLRPMS.md b/COOLRPMS.md
index 892d23c..da3c9cc 100644
--- a/COOLRPMS.md
+++ b/COOLRPMS.md
@@ -23,6 +23,16 @@ stuff.
   * glibc, kernel, systemd
 * Big app with frequent updates
   * libreoffice
+* Packages that had day-2 updates on my F33 workstation:
+  * Large-ish packages with few files:
+    * nodejs-libs      (43MB, 10 files)
+    * nodejs-full-i18n (28MB, 2 files)
+    * llvm-libs        (87MB, 19 files)
+  * Largest packages:
+    * containerd  (135MB, 53 files)
+    * firefox     (255MB, 204 files)
+    * ansible     (102MB, 17851 files)
+    * nodejs-docs (62MB,  794 files)
 
 ## Interesting metadata
 
diff --git a/rpmtoys/__init__.py b/rpmtoys/__init__.py
index 1b09e66..003f155 100644
--- a/rpmtoys/__init__.py
+++ b/rpmtoys/__init__.py
@@ -89,6 +89,10 @@ def dump(self):
         }
 
     def payload_iter(self):
+        '''
+        Iterate through the files in the RPM payload using libarchive.
+        Yields a libarchive.ArchiveEntry for each file in the payload.
+        '''
         from libarchive import stream_reader
         with self.open_payload() as payload_fobj:
             with stream_reader(payload_fobj,
@@ -155,15 +159,10 @@ def _getsignatures(self):
     def checkdigests(self, hdr=True, payload=True, filedigests=True):
         '''
         Check RPM package/file/payload digests against expected values.
-        An RPM's signature header can
-        contain the following digests (see `digest()`):
+        An RPM's signature header can contain the following digests:
             sha1:   SHA1 of the hdr section
             sha256: SHA256 of the hdr section
-            md5:    MD5 of the hdr section + payload
-
-        The RPM hdr can also contain the FILEDIGESTS tag, which will have
-        digests of each file in the payload. The digest algorithm is specified
-        by the FILEDIGESTALGO tag.
+            md5:    MD5 of the hdr section & payload (obsolete, deprecated)
         '''
         result = dict()
         if hdr or payload:
@@ -194,9 +193,16 @@ def checksigs(self, keydir=None, hdr=True, payload=True):
         raise NotImplementedError
 
     def iterdigestfiles(self, algo=None):
+        '''
+        Iterate through the payload files and calculate digests for each one.
+        If `algo` is None, uses the algorithm in the rpm's FILEDIGESTALGO tag.
+        Yields (name, hexdigest) pairs for each file in the payload.
+        '''
         if algo is None:
             algo = self.hdr.getval(Tag.FILEDIGESTALGO)
         for e in self.payload_iter():
+            # TODO: if we can also get the raw headers, we could calculate
+            # PAYLOADDIGESTALT at the same time..
             if e.isreg:
                 h = gethasher(algo)
                 for block in e.get_blocks():
@@ -204,10 +210,16 @@ def iterdigestfiles(self, algo=None):
                 yield (e.name[1:], h.hexdigest())
 
     def checkfiledigests(self):
+        '''
+        The RPM hdr can also contain the FILEDIGESTS tag, which will have
+        digests of each file in the payload. The digest algorithm is specified
+        by the FILEDIGESTALGO tag.
+        '''
         dig = dict(zip(self.iterfiles(), self.getval(Tag.FILEDIGESTS)))
         return {n:dig.get(n)==d for n,d in self.iterdigestfiles()}
 
     def nfiles(self):
+        '''Return a count of the number of files in the package.'''
         return self.getcount(Tag.BASENAMES)
 
     def iterfiles(self):