Add function docs

Author: nikdoof

hackspaceapi/events.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 from enum import Enum
-from typing import List, Literal
+from typing import Iterable, Literal
 
 import arrow
 from fastapi import APIRouter, Response
@@ -19,7 +19,10 @@ class CalendarType(str, Enum):
     members = settings.hackspace_member_calendar
 
 
-def get_calendar_events(start: datetime, end: datetime, calendar: str) -> List:
+def get_calendar_events(start: datetime, end: datetime, calendar: str) -> Iterable:
+    """
+    Get a list of calendar events from Home Assistant via the API.
+    """
     data = call_homeassistant(
         "/api/calendars/{0}".format(calendar.value), start=start, end=end
     )

hackspaceapi/services/homeassistant.py

@@ -26,7 +26,7 @@
 @call_homeassistant_metrics.time()
 def call_homeassistant(endpoint: str, **params) -> Optional[Iterable]:
     """
-    Call a Homeassistant API endpoint and return the JSON if successful
+    Call a Home Assistant API endpoint and return the JSON if successful
     """
     url = urljoin(settings.homeassistant_instance, endpoint)
     try:
@@ -40,4 +40,7 @@ def call_homeassistant(endpoint: str, **params) -> Optional[Iterable]:
 
 
 def get_entity_state(entity_id: str) -> Optional[Iterable]:
+    """
+    Call the configured Home Assistant API and retrieve the current state of a entity
+    """
     return call_homeassistant("/api/states/{0}".format(entity_id))

hackspaceapi/services/prometheus.py

@@ -11,11 +11,18 @@
 
 session = get_requests_session()
 
-prometheus_metric_summary = Summary('hackspaceapi_prometheus_api_time', 'Summary of calls to the Prometheus API')
+prometheus_metric_summary = Summary(
+    "hackspaceapi_prometheus_api_time", "Summary of calls to the Prometheus API"
+)
+
 
 @ttl_cache(ttl=60)
 @prometheus_metric_summary.time()
 def get_prometheus_metric(query: str) -> Optional[Dict]:
+    """
+    Call the configured Prometheus endpoint with a query, and return the
+    resulting data if successful.
+    """
     url = urljoin(settings.prometheus_instance, "/api/v1/query")
     try:
         resp = session.get(url, params={"query": query})

hackspaceapi/services/website.py

@@ -17,6 +17,10 @@
 @ttl_cache(ttl=1800)
 @website_metric_summary.time()
 def get_membership_data() -> Optional[Iterable]:
+    """
+    Pull the JSON formatted membership plan data from the Leigh Hackspace
+    website.
+    """
     url = "https://web-test.leighhack.org/membership/index.json"
     try:
         resp = session.get(url)

hackspaceapi/spaceapi.py

@@ -12,7 +12,7 @@
 
 spaceapi = APIRouter()
 
-# Homeassistant Sensors to export to the Space API
+# Home Assistant Sensors to export to the Space API
 # entity_id, override_name
 HOMEASSISTANT_SENSORS = (
     ("sensor.gw_dhcp_leases_online", "WiFi Clients"),
@@ -32,21 +32,28 @@
 
 
 def get_state() -> dict:
+    """
+    Return the current open state of the Hackspace.
+    """
     data = get_entity_state(settings.hackspace_open_entity)
     if data:
         return {
             "open": data["state"] == "on",
             "lastchange": int(arrow.get(data["last_changed"]).timestamp()),
         }
 
-    # We didn't get a valid response from Homeassistant, assume we're closed
+    # We didn't get a valid response from Home Assistant, assume we're closed
     return {
         "open": False,
     }
 
 
 @ttl_cache(ttl=60)
 def get_sensors() -> dict:
+    """
+    Query Home Assistant and Prometheus to build the 'sensors' section of the
+    SpaceAPI response.
+    """
     results = {}
     for sensor, override_name in HOMEASSISTANT_SENSORS:
         data = get_entity_state(sensor)
@@ -202,6 +209,9 @@ def get_sensors() -> dict:
 
 
 def get_links() -> list:
+    """
+    Return a list of links to add to the 'links' value of the SpaceAPI response.
+    """
     return [
         {"name": "Github", "url": "https://github.com/leigh-hackspace"},
         {
@@ -214,6 +224,9 @@ def get_links() -> list:
 
 
 def get_membership_plans() -> list:
+    """
+    Format the website membership plan data into a SpaceAPI compatible format.
+    """
     data = get_membership_data()
     if not data:
         return []