Bulk convert comments above classes/functions/methods into proper docstrings

server/handlers/api/alerts.py

@@ -14,8 +14,9 @@ SSE_HANDLER_MAX_QUEUE_SIZE = 100
 SSE_HANDLER_QUEUE_CHECK_INTERVAL = 5000
 
 
-# API request handler for /api/v1/alerts
 class APIAlertsHandler(tornado.web.RequestHandler):
+    """API request handler for /api/v1/alerts"""
+
     def initialize(self, alerts, web_server_metrics):
         self.alerts = alerts
         self.web_server_metrics = web_server_metrics
@@ -47,14 +48,17 @@ class APIAlertsHandler(tornado.web.RequestHandler):
         self.set_header("Cache-Control", "no-store")
         self.set_header("Content-Type", "application/json")
 
-# API request handler for /api/v1/alerts/stream
+
 class APIAlertsStreamHandler(tornado_eventsource.handler.EventSourceHandler):
+    """API request handler for /api/v1/alerts/stream"""
+
     def initialize(self, sse_alert_queues, web_server_metrics):
         self.sse_alert_queues = sse_alert_queues
         self.web_server_metrics = web_server_metrics
 
-    # Custom headers to avoid e.g. nginx reverse proxy from buffering SSE data
     def custom_headers(self):
+        """Custom headers to avoid e.g. nginx reverse proxy from buffering SSE data"""
+
         return {"Cache-Control": "no-store",
                 "X-Accel-Buffering": "no"}
 
@@ -81,8 +85,9 @@ class APIAlertsStreamHandler(tornado_eventsource.handler.EventSourceHandler):
         except Exception as e:
             logging.warn("Exception when serving SSE socket", e)
 
-    # When the user closes the socket, empty our queue and remove it from the list so the server no longer fills it
     def close(self):
+        """When the user closes the socket, empty our queue and remove it from the list so the server no longer fills it"""
+
         try:
             if self.alert_queue in self.sse_alert_queues:
                 self.sse_alert_queues.remove(self.alert_queue)
@@ -96,8 +101,9 @@ class APIAlertsStreamHandler(tornado_eventsource.handler.EventSourceHandler):
         self.alert_queue = None
         super().close()
 
-    # Callback to check if anything has arrived in the queue, and if so send it to the client
     def _callback(self):
+        """Callback to check if anything has arrived in the queue, and if so send it to the client"""
+
         try:
             if self.alert_queue:
                 while not self.alert_queue.empty():
@@ -114,11 +120,10 @@ class APIAlertsStreamHandler(tornado_eventsource.handler.EventSourceHandler):
             self.close()
 
 
-
-
-# Utility method to apply filters to the overall alert list and return only a subset. Enables query parameters in
-# the main "alerts" GET call.
 def get_alert_list_with_filters(all_alerts, query):
+    """Utility method to apply filters to the overall alert list and return only a subset. Enables query parameters in
+    the main "alerts" GET call."""
+
     # Create a shallow copy of the alert list ordered by start time, then filter the list to reduce it only to alerts
     # that match the filter parameters in the query string. Finally, apply a limit to the number of alerts returned.
     # The list of query string filters is defined in the API docs.
@@ -134,9 +139,11 @@ def get_alert_list_with_filters(all_alerts, query):
         alerts = alerts[:int(query.get("limit"))]
     return alerts
 
-# Given URL query params and an alert, figure out if the alert "passes" the requested filters or is rejected. The list
-# of query parameters and their function is defined in the API docs.
+
 def alert_allowed_by_query(alert, query):
+    """Given URL query params and an alert, figure out if the alert "passes" the requested filters or is rejected. The list
+    of query parameters and their function is defined in the API docs."""
+
     for k in query.keys():
         match k:
             case "received_since":