Merge pull request #2 from Programming-The-Next-Step-2026/week-2

Week 2

Author: magdalena-grubesa

.coverage

@@ -1,4 +1,6 @@
 *.egg-info/
 __pycache__/
 *.pyc
-.DS_Store
+.DS_Store
+credentials.json
+token.json

.gitignore

@@ -1,4 +1,4 @@
-Copyright (c) 2025 Magdalena Grubesa
+Copyright (c) 2026 Magdalena Grubesa
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -3,8 +3,61 @@
 A smart study planner that builds your revision schedule automatically based on your exam dates and availability.
 
 ## Features
-- Input your exams with dates, difficulty and estimated study hours
-- Set daily available study hours
-- Get an automatically generated revision schedule
-- Receive warnings when schedule is overloaded
-- Receive study tips based on the schedule
+- Input your exams with dates and estimated study hours
+- Set daily available study hours and commitments
+- Import commitments automatically from Google Calendar
+- Edit/ commitments inside the planner 
+- Get an automatically generated color coded revision schedule
+- Receive warnings when there is not enough time for an exam
+- Get personalised study tips based on psychology research
+- Optional spaced repetition schedule based on the Ebbinghaus forgetting curve
+
+## Installation
+```bash
+pip install -e .
+```
+
+## Usage
+```bash
+python src/study_smart/app.py
+```
+
+## Documentation
+
+To view the documentation for schedule.py, run:
+
+```bash
+pdoc --docformat google src/study_smart/schedule.py
+```
+
+To view the documentation for google_calendar.py, run:
+
+```bash
+pdoc --docformat google src/study_smart/google_calendar.py
+```
+
+## Testing
+
+To run the unit tests:
+
+```bash
+pytest tests/
+```
+
+To run tests with coverage report:
+
+```bash
+pytest --cov=study_smart tests/
+```
+
+## Google Calendar Integration
+To use the Google Calendar import feature you need:
+1. A Google account
+2. A `credentials.json` file — get this from [Google Cloud Console](https://console.cloud.google.com) by creating a project, enabling the Google Calendar API, and creating OAuth 2.0 credentials (Desktop app)
+3. Place `credentials.json` in the root of the project folder
+4. On first run a browser window will open asking you to grant calendar access — after that a `token.json` file is saved automatically
+
+Note: `credentials.json` and `token.json` are excluded from version control for security reasons.
+
+## Study Tips
+Hard-coded tips, based on psychological research.

README.md

@@ -18,12 +18,16 @@ classifiers = [
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
 dependencies = [
-    "shiny",
     "pandas",
-    "plotnine",
-    "openpyxl",
+    "google-auth",
+    "google-auth-oauthlib",
+    "google-api-python-client",
+]
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
 ]
-
 [project.urls]
 Homepage = "https://github.com/Programming-The-Next-Step-2026/StudySmart"
 Issues = "https://github.com/Programming-The-Next-Step-2026/StudySmart/issues"

pyproject.toml

@@ -1,3 +1,6 @@
 from .schedule import (
-    available_hours_per_day
-)
+    build_schedule,
+    update_schedule,
+    generate_tips
+)
+from .google_calendar import import_commitments_from_google_calendar

src/study_smart/__init__.py

@@ -0,0 +1,100 @@
+import os
+from datetime import datetime
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+
+SCOPES = ["https://www.googleapis.com/auth/calendar.readonly"]
+
+
+def _get_calendar_service():
+    """Internal — authenticates and returns Google Calendar service."""
+    creds = None
+
+    if os.path.exists("token.json"):
+        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
+
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file(
+                "credentials.json", SCOPES
+            )
+            creds = flow.run_local_server(port=0)
+
+        with open("token.json", "w") as token:
+            token.write(creds.to_json())
+
+    return build("calendar", "v3", credentials=creds)
+
+def import_commitments_from_google_calendar(start_date, end_date):
+    """
+    Imports calendar events as commitments from Google Calendar.
+
+    Fetches all events between start_date and end_date and converts
+    them into a commitments dictionary mapping dates to blocked hours.
+
+    Note: Requires a live Google Calendar connection and valid credentials.
+    Authentication is handled via OAuth 2.0. On first run, a browser window
+    will open asking the user to grant calendar access.
+
+    Args:
+        start_date (date): First day to fetch events from.
+        end_date (date): Last day to fetch events until.
+
+    Returns:
+        tuple: A tuple containing two dictionaries:
+            - commitments (dict): Mapping dates to total blocked hours that day.
+            - event_name (dict): Mapping dates to lists of event titles.
+
+    Example:
+        >>> from datetime import date, datetime
+        >>> commitments, event_name = import_commitments_from_google_calendar(
+        ...     start_date=date(2026, 5, 13),
+        ...     end_date=date(2026, 6, 5)
+        ... )
+    """
+    service = _get_calendar_service()
+
+    start = datetime.combine(start_date, datetime.min.time()).isoformat() + "Z"
+    end = datetime.combine(end_date, datetime.min.time()).isoformat() + "Z"
+
+    events_result = service.events().list(
+        calendarId="primary",
+        timeMin=start,
+        timeMax=end,
+        singleEvents=True,
+        orderBy="startTime"
+    ).execute()
+
+    events = events_result.get("items", [])
+
+    commitments = {}
+    event_name = {}
+    for event in events:
+        if "dateTime" not in event["start"]:
+            continue
+
+        start_time = datetime.fromisoformat(
+            event["start"]["dateTime"].replace("Z", "+00:00")
+        )
+        end_time = datetime.fromisoformat(
+            event["end"]["dateTime"].replace("Z", "+00:00")
+        )
+        duration_hours = (end_time - start_time).seconds / 3600
+        event_date = start_time.date()
+        event_title = event.get("summary", "Unnamed event")
+
+        #to prevent overwriting existing commitments, sum durations for events on the same day
+        if event_date in commitments:
+            commitments[event_date] += duration_hours
+            event_name[event_date].append(event_title)
+        else:
+            commitments[event_date] = duration_hours
+            event_name[event_date] = [event_title]
+
+    return (commitments, event_name)
+
+