From 2418d914733cc1c81407b4b9cb4c980eabec8379 Mon Sep 17 00:00:00 2001
From: Ken Dreyer <kdreyer@redhat.com>
Date: Dec 07 2021 19:55:09 +0000
Subject: hub: document getBuildLogs method


Update the getBuildLogs RPC docstring to describe the "build"
parameters and the return type. Highlight that this call is only
relevant for completed builds, not incomplete builds.

---

diff --git a/hub/kojihub.py b/hub/kojihub.py
index b15a2d0..ec011f8 100644
--- a/hub/kojihub.py
+++ b/hub/kojihub.py
@@ -4352,7 +4352,20 @@ def get_build(buildInfo, strict=False):
 
 
 def get_build_logs(build):
-    """Return a list of log files for the given build"""
+    """Return a list of log files for the given build
+
+    This method will only return logs for builds that are complete.
+    If a build is in progress, failed, or canceled, you must look at the
+    build's task logs instead (see listTaskOutput).
+
+    :param build: A build ID (int), a NVR (string), or a dict containing
+                  "name", "version" and "release".
+    :returns: a possibly-empty list of log file entries. Each entry is a dict
+              with three keys:
+                "name" (log file name)
+                "dir" (immediate parent subdirectory)
+                "path" (the full path under koji's topdir)
+    """
     buildinfo = get_build(build, strict=True)
     logdir = koji.pathinfo.build_logs(buildinfo)
     logreldir = os.path.relpath(logdir, koji.pathinfo.topdir)