some docstrings and cleanup

CHANGELOG.md

@@ -4,6 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 ### Added
+- add `scriptworker.utils.filepaths_in_dir`
 - added setup.cfg for wheels
 - added `scriptworker.client.validate_artifact_url`.
 

scriptworker/task.py

@@ -206,6 +206,8 @@ async def complete_task(context, result):
 
 
 async def kill(pid, sleep_time=1):
+    """Kill `pid`.
+    """
     siglist = [signal.SIGINT, signal.SIGTERM]
     while True:
         sig = signal.SIGKILL
@@ -220,6 +222,11 @@ async def kill(pid, sleep_time=1):
 
 
 def max_timeout(context, proc, timeout):
+    """Make sure the proc pid's process and process group are killed.
+    """
+    # We may be called with proc1.  proc1 may finish, and proc2 may start
+    # before this function is called.  Make sure we're still running the
+    # proc we were called with.
     if proc != context.proc:
         return
     pid = context.proc.pid

scriptworker/utils.py

@@ -38,6 +38,8 @@ async def request(context, url, timeout=60, method='get', good=(200, ),
 
 async def retry_request(*args, retry_exceptions=(ScriptWorkerRetryException, ),
                         **kwargs):
+    """Retry the `request` function
+    """
     return await retry_async(request, retry_exceptions=retry_exceptions,
                              args=args, kwargs=kwargs)
 
@@ -80,6 +82,8 @@ def cleanup(context):
 
 async def retry_async(func, attempts=5, sleeptime_callback=None,
                       retry_exceptions=(Exception, ), args=(), kwargs=None):
+    """Retry `func`, where `func` is an awaitable.
+    """
     kwargs = kwargs or {}
     sleeptime_callback = sleeptime_callback or calculateSleepTime
     attempt = 1
@@ -98,6 +102,8 @@ async def retry_async(func, attempts=5, sleeptime_callback=None,
 
 def create_temp_creds(client_id, access_token, start=None, expires=None,
                       scopes=None, name=None):
+    """Create temp TC creds from our permanent creds.
+    """
     now = arrow.utcnow().replace(minutes=-10)
     start = start or now.datetime
     expires = expires or now.replace(days=31).datetime
@@ -113,6 +119,9 @@ def create_temp_creds(client_id, access_token, start=None, expires=None,
 
 
 async def raise_future_exceptions(tasks):
+    """Given a list of futures, await them, then raise their exceptions if
+    any.  Without something like this, any exceptions will be ignored.
+    """
     await asyncio.wait(tasks)
     for task in tasks:
         exc = task.exception()

tests/__init__.py

@@ -11,10 +11,20 @@
 
 
 def read(path):
+    """Return the contents of a file.
+    """
     with open(path, "r") as fh:
         return fh.read()
 
 
+def touch(path):
+    """ Create an empty file.  Different from the system 'touch' in that it
+    will overwrite an existing file.
+    """
+    with open(path, "w") as fh:
+        print(path, file=fh, end="")
+
+
 class SuccessfulQueue(object):
     result = "yay"
     info = None

tests/test_task.py

@@ -16,7 +16,7 @@
 import taskcluster.exceptions
 import taskcluster.async
 import time
-from . import fake_session, fake_session_500, successful_queue, unsuccessful_queue, read
+from . import fake_session, fake_session_500, successful_queue, touch, unsuccessful_queue, read
 
 assert fake_session, fake_session_500  # silence flake8
 assert successful_queue, unsuccessful_queue  # silence flake8
@@ -25,11 +25,6 @@
 TIMEOUT_SCRIPT = os.path.join(os.path.dirname(__file__), "data", "long_running.py")
 
 
-def touch(path):
-    with open(path, "w") as fh:
-        print(path, file=fh, end="")
-
-
 @pytest.fixture(scope='function')
 def context(tmpdir_factory):
     temp_dir = tmpdir_factory.mktemp("context", numbered=True)