Add docstring comments to functions

engelke · engelke · commit 057f0e80f190 · 2019-08-01T15:49:16.000-07:00
diff --git a/authenticating-users/main.py b/authenticating-users/main.py
@@ -22,6 +22,10 @@
 
 
 def certs():
+    """Returns a dictionary of current Google public key certificates for
+    validating Google-signed JWTs. Since these change rarely, the result
+    is cached on first request for faster subsequent responses.
+    """
     import requests
 
     global CERTS
@@ -34,6 +38,10 @@ def certs():
 
 
 def get_metadata(item_name):
+    """Returns a string with the project metadata value for the item_name.
+    See https://cloud.google.com/compute/docs/storing-retrieving-metadata for
+    possible item_name values.
+    """
     import requests
 
     endpoint = 'http://metadata.google.internal'
@@ -48,6 +56,10 @@ def get_metadata(item_name):
 
 
 def audience():
+    """Returns the audience value (the JWT 'aud' property) for the current
+    running instance. Since this involves a metadata lookup, the result is
+    cached when first requested for faster future responses.
+    """
     global AUDIENCE
     if AUDIENCE is None:
         project_number = get_metadata('numeric-project-id')
@@ -59,6 +71,10 @@ def audience():
 
 
 def validate_assertion(assertion):
+    """Checks that the JWT assertion is valid (properly signed, for the
+    correct audience) and if so, returns strings for the requesting user's
+    email and a persistent user ID. If not valid, returns None for each field.
+    """
     from jose import jwt
 
     try:
