docs: add detailed docstrings to functions for improved clarity and usage instructions

Author: xXxNIKIxXx

clean_up_events.py

@@ -3,31 +3,56 @@
 
 # Convert string to datetime
 def parse_datetime(dt_str):
+    """
+    Convert a string representation of a date and time to a datetime object.
+
+    This function uses the `fromisoformat` method to parse the input string,
+    which should be in ISO format (YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]][+HH:MM[:SS[.ffffff]]]])
+
+    Args:
+        dt_str (str): A string representing a date and time in ISO format.
+
+    Returns:
+        datetime: A datetime object representing the parsed date and time.
+
+    Raises:
+        ValueError: If the input string is not in a valid ISO format.
+    """
     return datetime.fromisoformat(dt_str)
 
-# Calculate free times
 def calculate_free_times(lessons):
-    free_times = []
-    lessons = sorted(lessons, key=lambda x: parse_datetime(x['start']))
-    
-    # Define the start and end of the day
-    day_start = parse_datetime(lessons[0]['start']).replace(hour=0, minute=0, second=0, microsecond=0)
-    day_end = day_start + timedelta(days=1)
-    
-    # Check for free time before the first lesson
-    if parse_datetime(lessons[0]['start']) > day_start:
-        free_times.append({'start': day_start.isoformat(), 'end': lessons[0]['start']})
-    
-    # Check for free times between lessons
-    for i in range(len(lessons) - 1):
-        end_current = parse_datetime(lessons[i]['end'])
-        start_next = parse_datetime(lessons[i + 1]['start'])
-        if end_current < start_next:
-            free_times.append({'start': end_current.isoformat(), 'end': start_next.isoformat()})
-    
-    # Check for free time after the last lesson
-    if parse_datetime(lessons[-1]['end']) < day_end:
-        free_times.append({'start': lessons[-1]['end'], 'end': day_end.isoformat()})
-    
-    return free_times[1:]
+    """
+    Calculate the free time slots from a list of scheduled lessons.
+
+    This function takes a list of lessons, where each lesson is represented as a dictionary with 'start' and 'end' keys.
+    It then calculates the free time slots by compressing the scheduled lessons and merging overlapping time slots.
+
+    Args:
+        lessons (list): A list of dictionaries, where each dictionary represents a lesson with 'start' and 'end' keys.
+
+    Returns:
+        list: A list of dictionaries representing the free time slots. Each dictionary contains 'start' and 'end' keys.
+
+    Example:
+        lessons = [
+            {'start': '2022-01-01 09:00', 'end': '2022-01-01 11:00'},
+            {'start': '2022-01-01 10:00', 'end': '2022-01-01 12:00'},
+            {'start': '2022-01-01 13:00', 'end': '2022-01-01 14:00'}
+        ]
+        free_times = calculate_free_times(lessons)
+        print(free_times)
+        
+    ## Output:
+        [{'start': '2022-01-01 09:00', 'end': '2022-01-01 10:00'}, {'start': '2022-01-01 12:00', 'end': '2022-01-01 13:00'}]
+    """
+    cleaned_data = [{'start': entry['start'], 'end': entry['end']} for entry in lessons]
+    sorted_data = sorted(cleaned_data, key=lambda x: x['start'])
+    compressed_data = []
+    for entry in sorted_data:
+        if compressed_data and compressed_data[-1]['end'] == entry['start']:
+            compressed_data[-1]['end'] = entry['end']
+        else:
+            compressed_data.append(entry)
+            
+    return compressed_data
 

get_data.py

@@ -5,10 +5,29 @@
 load_dotenv(override=True)
 
 def get_data(from_date, to_date, session_id, auth_token, user_id, school_id):
+    """
+    Retrieves schedule data from the ALL4SCHOOLS API.
+
+    This function sends a POST request to the ALL4SCHOOLS API to fetch schedule data
+    for a specific student within a given date range.
+
+    Parameters:
+    from_date (str): The start date of the schedule period (format: 'YYYY-MM-DD').
+    to_date (str): The end date of the schedule period (format: 'YYYY-MM-DD').
+    session_id (str): The ASP.NET session ID for authentication.
+    auth_token (str): The ASPXAUTH token for authentication.
+    user_id (str): The ID of the student whose schedule is being requested.
+    school_id (str): The ID of the school.
+
+    Returns:
+    dict or None: A dictionary containing the schedule data if the request is successful
+                  and the response is in JSON format. Returns None if the request fails
+                  or the response is not in JSON format.
+    """
     base_url = os.getenv('ALL4SCHOOLS_URL')
     api_endpoint = 'api/api/Schedule/GetSchedule'
     full_url = f"{base_url}/{api_endpoint}"
-    
+
     data = {
         "schoolId": school_id,
         "studentId": user_id,
@@ -34,4 +53,4 @@ def get_data(from_date, to_date, session_id, auth_token, user_id, school_id):
             return None
     else:
         print(f"Request failed with status code {response.status_code}")
-        return None
+        return None

get_school_id.py

@@ -5,6 +5,22 @@
 load_dotenv(override=True)
 
 def get_school_id(session_id, auth_token):
+    """
+    Retrieves the school ID for the current user from the ALL4SCHOOLS API.
+
+    This function makes a GET request to the ALL4SCHOOLS API to fetch the schools and settings
+    for the current user. It then extracts and returns the ID of the first school in the response.
+
+    Args:
+        session_id (str): The ASP.NET session ID for authentication.
+        auth_token (str): The ASPXAUTH token for authentication.
+
+    Returns:
+        str: The ID of the first school associated with the current user.
+
+    Raises:
+        requests.exceptions.HTTPError: If the API request fails or returns a non-200 status code.
+    """
     base_url = os.getenv('ALL4SCHOOLS_URL')
     api_endpoint = 'api/Api/AppUser/GetSchoolsAndSettingsForCurrentUser'
     full_url = f"{base_url}/{api_endpoint}"
@@ -16,8 +32,8 @@ def get_school_id(session_id, auth_token):
 
     # Assuming you will use requests to make the API call
     response = requests.get(full_url, cookies=cookies)
-    
+
     if response.status_code == 200:
         return response.json()[0]["id"]
     else:
-        response.raise_for_status()
+        response.raise_for_status()

main.py

@@ -124,6 +124,19 @@ def print_progress_bar(processed, total):
 
 
 def process_event_with_progress(event, lock, processed_events, total_events, last_print_time):
+    """
+    Processes an event and updates the progress bar.
+
+    Args:
+        event: The event to be processed.
+        lock: A threading lock to ensure thread-safe updates to the processed_events counter.
+        processed_events (list): A list containing a single integer representing the number of processed events.
+        total_events (int): The total number of events to be processed.
+        last_print_time (list): A list containing a single float representing the last time the progress bar was printed.
+
+    Returns:
+        None
+    """
     process_event(event)
     with lock:
         processed_events[0] += 1
@@ -132,7 +145,21 @@ def process_event_with_progress(event, lock, processed_events, total_events, las
             print_progress_bar(processed_events[0], total_events)
             last_print_time[0] = current_time
 
+
 def process_free_time_range(time_range, lock, processed_free_times, total_free_times, last_print_time_free):
+    """
+    Processes a given time range by removing events within that range and updating the progress.
+
+    Args:
+        time_range (tuple): The time range to process.
+        lock (threading.Lock): A lock to ensure thread-safe operations.
+        processed_free_times (list): A list containing the count of processed free times.
+        total_free_times (int): The total number of free times to process.
+        last_print_time_free (list): A list containing the last time the progress was printed.
+
+    Returns:
+        None
+    """
     remove_events_in_time_range(time_range)
     with lock:
         processed_free_times[0] += 1
@@ -169,8 +196,12 @@ def main():
 
     print_with_timestamp("\033[94mCompressing events...\033[0m")
     compressed_data = compress_events(parsed_data)
+    import json
+    with open("compressed.json", 'w') as json_file:
+        json.dump(compressed_data, json_file, indent=4)
     print_with_timestamp("\033[92mCompressed events\033[0m")
 
+
     print_with_timestamp("\033[94mAdding events to calendar...\033[0m")
     total_events = len(compressed_data)
     processed_events = [0]
@@ -187,15 +218,9 @@ def main():
     free_times = calculate_free_times(compressed_data)
     print_with_timestamp("\033[92mCalculated free times\033[0m")
 
-    print_with_timestamp("\033[94mRemoving free times from calendar...\033[0m")
-    total_free_times = len(free_times)
-    processed_free_times = [0]
-    last_print_time_free = [time.time()]
-
-    with ThreadPoolExecutor() as executor:
-        executor.map(lambda time_range: process_free_time_range(time_range, lock, processed_free_times, total_free_times, last_print_time_free), free_times)
-    print_progress_bar(total_free_times, total_free_times)
-    print_with_timestamp("\033[92mAll free times removed.\033[0m")
+    print_with_timestamp("\033[94mRemoving events from calendar...\033[0m")
+    remove_events_in_time_range(free_times)
+    print_with_timestamp("\033[92mRemoved events from calendar\033[0m")
 
 if __name__ == "__main__":
     interval_minutes = int(os.getenv('INTERVAL_MINUTES', 10))

set_free_time_in_calander.py

@@ -11,24 +11,21 @@
 
 def remove_events_in_time_range(time_range):
     """
-    Remove events from a SOGo calendar that fall within a specified time range.
+    Remove events from a calendar that do not overlap with specified free time slots.
 
-    This function connects to a SOGo calendar, retrieves events within a certain date range,
-    and deletes any events that overlap with the specified time range.
+    This function connects to a calendar service, retrieves events within a specified date range,
+    and deletes events that do not overlap with the provided free time slots.
 
     Parameters:
-    time_range (dict): A dictionary containing the start and end times for the range
-                       in which events should be removed. It should have two keys:
-                       'start' and 'end', with string values that can be parsed into
-                       datetime objects.
+    time_range (list of dict): A list of dictionaries, where each dictionary represents a free time slot
+                               with 'start' and 'end' keys containing datetime strings.
 
     Returns:
     None
 
     Note:
-    - This function relies on environment variables for calendar connection details.
-    - It uses the caldav library to interact with the calendar.
-    - Events are deleted if they start, end, or span within the specified time range.
+    - The function uses environment variables for calendar service credentials and configuration.
+    - Events are deleted if they fall completely outside the specified free time slots.
     """
     url = os.getenv('SOGO_CALENDAR_URL')
     username = os.getenv('SOGO_USERNAME')
@@ -39,17 +36,17 @@ def remove_events_in_time_range(time_range):
 
     start = datetime.now()
     end = datetime.now() + timedelta(days=int(os.getenv('DAYS_TO_UPDATE')))
-    existing_events = calendar__.date_search(start, end)
+    events_to_delete = calendar__.date_search(start, end)
 
-    range_start = parse(time_range['start'])
-    range_end = parse(time_range['end'])
 
-    for event in existing_events:
-        event_start = event.vobject_instance.vevent.dtstart.value
-        event_end = event.vobject_instance.vevent.dtend.value
-
-        if (event_start > range_start and event_start < range_end) or \
-           (event_end > range_start and event_end < range_end) or \
-           (event_start < range_start and event_end > range_end):
-            event.delete()
+    for free_slot in time_range:
+        free_start = parse(free_slot['start'])
+        free_end = parse(free_slot['end'])
+        for event in events_to_delete:
+            event_start = event.vobject_instance.vevent.dtstart.value
+            event_end = event.vobject_instance.vevent.dtend.value
+            if (free_start <= event_start < free_end) or (free_start < event_end <= free_end) or (event_start <= free_start and event_end >= free_end):
+                events_to_delete.remove(event)
 
+    for event in events_to_delete:
+        event.delete()