📝 Functions and docstrings

main.py

@@ -14,8 +14,13 @@ def log(text: str):
 
 def read_config() -> dict:
     """
-    Returns the contents of config.ini as a a dict, assuming it exists and has
-    no empty fields.
+    Reads the file config.ini. If the there is no file, it will create one. If
+    the file has empty fields, it will notify the user and end the program.
+
+    RETURNS
+    -------
+    - dict
+        The contents of the config.ini file.
     """
     config = ConfigParser()
 
@@ -45,7 +50,18 @@ def read_config() -> dict:
 
 def get_trello_cards(config: dict) -> list[dict]:
     """
-    Returns a list of every card in the Trello board, each a dict.
+    Uses the Trello API to get every card from the board, and extracts the important information.
+
+    PARAMETERS
+    ----------
+    - config: dict
+        The config file data. Uses this for the board ID, and the API key and
+        token.
+
+    RETURNS
+    -------
+    - list[dict]
+        A list of each card, with the following information: card id, name of the card, when the last activity on the card was performed, the IDs of whatever members are assigned, and the labels the card has.
     """
     url = TRELLO_API_CARDS_URL.format(id=config["Trello"]["boardid"])
     query = {
@@ -74,24 +90,98 @@ def get_trello_cards(config: dict) -> list[dict]:
 
     return cards
 
+def flag_out_of_date_cards(cards: list[dict]) -> list[dict]:
+    """
+    Flags cards as out of date, if they exceed the deadline.
+
+    PARAMETERS
+    ----------
+    - cards: list[dict]
+        The list of cards.
+
+    RETURNS
+    -------
+    - list[dict]
+        The same list of cards, but with an out_of_date boolean field.
+    """
+    pass
+
+def generate_reports(cards: list[dict]) -> tuple[str,list]:
+    """
+    Generates the PDF reports for each user. Each report will be found at
+    ./reports/TIMESTAMP/USERID.pdf
+
+    PARAMETERS
+    ----------
+    - cards: list[dict]
+        The list of cards.
+
+    RETURNS
+    -------
+    - str
+        The timestamp used for the folder in which the reports are generated.
+
+    - list
+        The list of users reports were generated for.
+    """
+    pass
+
+def get_emails(config: dict, user_ids: list[str]) -> dict:
+    """
+    Uses the Trello API to find the email addresses of the given users.
+
+    PARAMETERS
+    ----------
+    - config: dict
+        The config file data. Uses this for the board ID, and the API key and
+        token.
+
+    - user_ids: list[str]
+        A list of user IDs.
+
+    RETURNS
+    -------
+    - dict
+        A dict where each user ID is the key and the value is their email.
+    """
+    pass
+
+def send_emails(config: dict, users: dict, timestamp: str) -> None:
+    """
+    Sending out emails.
+
+    PARAMETERS
+    ----------
+    - config: dict
+        The config file data. Uses this for the SMTP server, username and
+        password.
+
+    - users: dict
+        Each user ID and the email connected to it.
+
+    - timestamp: str
+        The timestamp used to create the folder that the reports are in.
+    """
+    pass
+
 def main():
     # Reading the config file
     config = read_config()
 
     # Getting the cards from Trello
-    submissions = get_trello_cards(config)
+    cards = get_trello_cards(config)
 
-    # Step 3:
-    #   For each card, compare to escalation rules to see if it's at the step
-    #   and escalation level it should be at. If not, flag it.
+    # Flagging the cards if they've exceeded their deadline
+    cards = flag_out_of_date_cards(cards)
 
-    # Step 4:
-    #   Generate reports for each person, showing their own cards.
-    #   Perhaps a "master report" with every card.
+    # Generate the PDF reports
+    timestamp, user_ids = generate_reports(cards)
 
-    # Step 5:
-    #   Send out the reports via email.
+    # Get the email address of each user
+    users = get_emails(config, user_ids)
 
+    # Send out the emails
+    send_emails(config, users, timestamp)
 
 if __name__ == "__main__":
     main()