Add modules functions and update function documentation

src/pylorax/api/projects.py

@@ -22,7 +22,13 @@ import time
 TIME_FORMAT = "%Y-%m-%dT%H:%M:%S"
 
 def api_time(t):
-    """Convert time since epoch to a string"""
+    """Convert time since epoch to a string
+
+    :param t: Seconds since epoch
+    :type t: int
+    :returns: Time string
+    :rtype: str
+    """
     return time.strftime(TIME_FORMAT, time.localtime(t))
 
 
@@ -31,8 +37,10 @@ def api_changelog(changelog):
 
     :param changelog: A list of time, author, string tuples.
     :type changelog: tuple
-    :returns: The most recent changelog text
+    :returns: The most recent changelog text or ""
     :rtype: str
+
+    This returns only the most recent changelog entry.
     """
     try:
         entry = changelog[0][2]
@@ -42,7 +50,15 @@ def api_changelog(changelog):
 
 
 def yaps_to_project(yaps):
-    """Extract the details from a YumAvailablePackageSqlite object"""
+    """Extract the details from a YumAvailablePackageSqlite object
+
+    :param yaps: Yum object with package details
+    :type yaps: YumAvailablePackageSqlite
+    :returns: A dict with the name, summary, description, and url.
+    :rtype: dict
+
+    upstream_vcs is hard-coded to UPSTREAM_VCS
+    """
     return {"name":         yaps.name,
             "summary":      yaps.summary,
             "description":  yaps.description,
@@ -51,7 +67,15 @@ def yaps_to_project(yaps):
 
 
 def yaps_to_project_info(yaps):
-    """Extract the details from a YumAvailablePackageSqlite object"""
+    """Extract the details from a YumAvailablePackageSqlite object
+
+    :param yaps: Yum object with package details
+    :type yaps: YumAvailablePackageSqlite
+    :returns: A dict with the project details, as well as epoch, release, arch, build_time, changelog, ...
+    :rtype: dict
+
+    metadata entries are hard-coded to {}
+    """
     build = {"epoch":      yaps.epoch,
              "release":    yaps.release,
              "arch":       yaps.arch,
@@ -74,7 +98,13 @@ def yaps_to_project_info(yaps):
 
 
 def tm_to_dep(tm):
-    """Extract the info from a TransactionMember object"""
+    """Extract the info from a TransactionMember object
+
+    :param tm: A Yum transaction object
+    :type tm: TransactionMember
+    :returns: A dict with name, epoch, version, release, arch
+    :rtype: dict
+    """
     return {"name":     tm.name,
             "epoch":    tm.epoch,
             "version":  tm.version,
@@ -82,16 +112,27 @@ def tm_to_dep(tm):
             "arch":     tm.arch}
 
 
+def yaps_to_module(yaps):
+    """Extract the name from a YumAvailablePackageSqlite object
+
+    :param yaps: Yum object with package details
+    :type yaps: YumAvailablePackageSqlite
+    :returns: A dict with name, and group_type
+    :rtype: dict
+
+    group_type is hard-coded to "rpm"
+    """
+    return {"name": yaps.name,
+            "group_type": "rpm"}
+
+
 def projects_list(yb):
     """Return a list of projects
 
     :param yb: yum base object
     :type yb: YumBase
-    :returns: List of project information
-    :rtype: List of Dicts
-
-    Returns a list of dicts with these fields:
-        name, summary, description, homepage, upstream_vcs
+    :returns: List of project info dicts with name, summary, description, homepage, upstream_vcs
+    :rtype: list of dicts
     """
     ybl = yb.doPackageLists(pkgnarrow="available", showdups=False)
     return sorted(map(yaps_to_project, ybl.available), key=lambda p: p["name"].lower())
@@ -104,9 +145,8 @@ def projects_info(yb, project_names):
     :type yb: YumBase
     :param project_names: List of names of projects to get info about
     :type project_names: str
-    :returns: List of project details
-    :rtype: List of Dicts
-
+    :returns: List of project info dicts with yaps_to_project as well as epoch, version, release, etc.
+    :rtype: list of dicts
     """
     ybl = yb.doPackageLists(pkgnarrow="available", patterns=project_names, showdups=False)
     return sorted(map(yaps_to_project_info, ybl.available), key=lambda p: p["name"].lower())
@@ -119,11 +159,9 @@ def projects_depsolve(yb, project_names):
     :type yb: YumBase
     :param project_names: The projects to find the dependencies for
     :type project_names: List of Strings
-    :returns: ...
-    :rtype: ...
+    :returns: NEVRA's of the project and its dependencies
+    :rtype: list of dicts
     """
-    # TODO - Catch yum tracebacks here
-
     # This resets the transaction
     yb.closeRpmDB()
     for p in project_names:
@@ -144,12 +182,13 @@ def modules_list(yb):
     :param limit: Maximum number of modules to return
     :type limit: int
     :returns: List of module information and total count
-    :rtype: Tuple of a List of Dicts and an Int
+    :rtype: tuple of a list of dicts and an Int
 
     Modules don't exist in RHEL7 so this only returns projects
     and sets the type to "rpm"
     """
-    pass
+    ybl = yb.doPackageLists(pkgnarrow="available", showdups=False)
+    return sorted(map(yaps_to_module, ybl.available), key=lambda p: p["name"].lower())
 
 
 def modules_info(yb, module_names):
@@ -159,5 +198,14 @@ def modules_info(yb, module_names):
     :type yb: YumBase
     :param module_names: Names of the modules to get info about
     :type module_names: str
+    :returns: List of dicts with module details and dependencies.
+    :rtype: list of dicts
     """
-    pass
+    # Get the info about each module
+    ybl = yb.doPackageLists(pkgnarrow="available", patterns=module_names, showdups=False)
+    modules = sorted(map(yaps_to_project, ybl.available), key=lambda p: p["name"].lower())
+
+    # Add the dependency info to each one
+    for module in modules:
+        module["dependencies"] = projects_depsolve(yb, [module["name"]])
+    return modules