From 75c5fa6355eab322494e38e6462ba627790198cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20P=C3=B6hn?= <michael.poehn@fsfe.org>
Date: Wed, 20 Sep 2017 00:58:19 +0200
Subject: [PATCH] added some docstrings and error messages

---
 fdroidserver/common.py | 16 ++++++++++++++--
 fdroidserver/index.py  | 13 +++++++++----
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/fdroidserver/common.py b/fdroidserver/common.py
index 94789024..8b35d49e 100644
--- a/fdroidserver/common.py
+++ b/fdroidserver/common.py
@@ -517,6 +517,18 @@ apk_release_filename_with_sigfp = re.compile('(?P<appid>[a-zA-Z0-9_\.]+)_(?P<ver
 
 
 def apk_parse_release_filename(apkname):
+    """Parses the name of an APK file according the F-Droids APK naming
+    scheme and returns the tokens.
+
+    WARNING: Returned values don't necessarily represent the APKs actual
+    properties, the are just paresed from the file name.
+
+    :returns: A triplet containing (appid, versionCode, signer), where appid
+        should be the package name, versionCode should be the integer
+        represion of the APKs version and signer should be the first 7 hex
+        digists of the sha256 signing key fingerprint which was used to sign
+        this APK.
+    """
     m = apk_release_filename_with_sigfp.match(apkname)
     if m:
         return m.group('appid'), m.group('vercode'), m.group('sigfp')
@@ -2037,7 +2049,7 @@ def signer_fingerprint_short(sig):
     Extracts the first 7 hexadecimal digits of sha256 signing-key fingerprint
     for a given pkcs7 signature.
 
-    :param sig: Contents of an APK signature.
+    :param sig: Contents of an APK signing certificate.
     :returns: shortened signing-key fingerprint.
     """
     return signer_fingerprint(sig)[:7]
@@ -2194,7 +2206,7 @@ def apk_strip_signatures(signed_apk, strip_manifest=False):
 
 
 def apk_implant_signatures(apkpath, signaturefile, signedfile, manifest):
-    """Implats a signature from out metadata into an APK.
+    """Implats a signature from metadata into an APK.
 
     Note: this changes there supplied APK in place. So copy it if you
     need the original to be preserved.
diff --git a/fdroidserver/index.py b/fdroidserver/index.py
index 4266fa59..3ff990a9 100644
--- a/fdroidserver/index.py
+++ b/fdroidserver/index.py
@@ -242,6 +242,13 @@ def make_v1(apps, packages, repodir, repodict, requestsdict, fdroid_signing_key_
 
 
 def v1_sort_packages(packages, repodir, fdroid_signing_key_fingerprints):
+    """Sorts the supplied list to ensure a deterministic sort order for
+    package entries in the index file. This sort-order also expresses
+    installation preference to the clients.
+    (First in this list = first to install)
+
+    :param packages: list of packages which need to be sorted before but into index file.
+    """
 
     GROUP_DEV_SIGNED = 1
     GROUP_FDROID_SIGNED = 2
@@ -270,7 +277,7 @@ def v1_sort_packages(packages, repodir, fdroid_signing_key_fingerprints):
     packages.sort(key=v1_sort_keys)
 
 
-def make_v0(apps, apks, repodir, repodict, requestsdict):
+def make_v0(apps, apks, repodir, repodict, requestsdict, fdroid_signing_key_fingerprints):
     """
     aka index.jar aka index.xml
     """
@@ -354,8 +361,6 @@ def make_v0(apps, apks, repodir, repodict, requestsdict):
             root.appendChild(element)
             element.setAttribute('packageName', packageName)
 
-    fdroid_signed = load_sigkeys(repodir)
-
     for appid, appdict in apps.items():
         app = metadata.App(appdict)
 
@@ -369,7 +374,7 @@ def make_v0(apps, apks, repodir, repodict, requestsdict):
             if apk.get('versionCode') and apk.get('packageName') == appid:
                 apksbyversion[apk['versionCode']].append(apk)
         for versionCode, apksforver in apksbyversion.items():
-            fdroidsig = fdroid_signed.get(appid, {}).get('signer')
+            fdroidsig = fdroid_signing_key_fingerprints.get(appid, {}).get('signer')
             fdroid_signed_apk = None
             name_match_apk = None
             for x in apksforver: