smart-study-planner 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,199 @@
1
+ Metadata-Version: 2.4
2
+ Name: smart-study-planner
3
+ Version: 0.5.0
4
+ Summary: Priority-aware study scheduling balanced across dates and daily time windows
5
+ Project-URL: Homepage, https://github.com/Justin-Liu080606/1302A-projecct-spare
6
+ Project-URL: Repository, https://github.com/Justin-Liu080606/1302A-projecct-spare
7
+ Project-URL: Documentation, https://github.com/Justin-Liu080606/1302A-projecct-spare#readme
8
+ Keywords: study,planner,scheduling,calendar,education
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Education
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Topic :: Education
14
+ Classifier: Topic :: Office/Business :: Scheduling
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+
18
+ [README.md](https://github.com/user-attachments/files/35005946/README.md)
19
+ # Smart Study Planner · CS1302 Group 06
20
+
21
+ > **Installable Python package** for automatic, explainable exam-aware study scheduling, with a colored weekly calendar, optional local web UI, and `.ics` calendar export.
22
+
23
+ Smart Study Planner is an open-source Python package for building balanced, priority-aware study schedules. Its scheduling engine works directly in Python and Jupyter notebooks, while an optional local web interface displays a weekly calendar. This repository contains the source code, usage examples, tests, and documentation.
24
+
25
+ ## Motivation & innovation
26
+
27
+ Students often know how many hours they need to study but struggle to fit them into irregular daily availability. Existing calendar tools generally require users to arrange every event manually. Our package converts subject workloads, exam deadlines, available dates and breaks into a feasible schedule. The scheduling engine is reusable from Python/JupyterHub — not tied to the webpage. See [algorithm explanation](docs/ALGORITHM.md) for the heuristic's tradeoffs and limitations.
28
+
29
+ ### Main features
30
+
31
+ - Schedule up to 20 subjects over up to 63 days with user-defined study hours.
32
+ - Multiple available windows per day; custom exceptions (including days off), with overlap merging.
33
+ - **Hard per-subject daily cap**, default **2h per subject per day**, configurable from 1h to 8h. No deadline can override it.
34
+ - **Priority-weighted multi-subject rotation** within and across days; subject order influences scheduling without letting any subject monopolize the timetable.
35
+ - **Date-aware pacing:** study sessions are distributed over the complete selected period instead of always filling the first days. Exam deadlines limit how far each subject can be spread.
36
+ - **Within-day window balance:** study sessions are distributed across available morning, afternoon, and other time windows based on their capacity, rather than always starting in the first window. Light days rotate the preferred window.
37
+ - Configurable study sessions and rest intervals; events never overlap or exceed availability.
38
+ - Report **unmet** study hours and calculate each subject's theoretical capacity before its exam, instead of promising an impossible timetable.
39
+ - Reuse results as JSON-compatible Python data, embedded JupyterHub HTML, or `.ics` calendar.
40
+ - Optional local browser UI with a colorful navigable weekly calendar, requiring no web framework.
41
+
42
+ ## Installation
43
+
44
+ Python **3.9+** is required. No mandatory runtime third-party dependencies.
45
+
46
+ **Before the first PyPI release:** open a terminal in the project's root directory:
47
+
48
+ ```bash
49
+ python -m pip install .
50
+ ```
51
+
52
+ **After the official PyPI release** (not yet available until the team publishes it):
53
+
54
+ ```bash
55
+ python -m pip install smart-study-planner==0.5.0
56
+ ```
57
+
58
+ The distribution name in `pip install` differs from the Python **import name**, which remains `study_plan`.
59
+
60
+ ## Python package usage (also works in JupyterHub)
61
+
62
+ ```python
63
+ from study_plan import generate_plan, summarize_plan, render_week_html, to_ics
64
+
65
+ request = {
66
+ "start_date": "2026-11-16",
67
+ "end_date": "2026-11-22",
68
+ "subjects": [
69
+ {"name": "CS1302 Python", "hours": 5, "exam_date": "2026-11-21"},
70
+ {"name": "Math", "hours": 6},
71
+ ],
72
+ "daily_windows": [
73
+ {"start": "08:00", "end": "11:00"},
74
+ {"start": "14:00", "end": "17:00"},
75
+ ],
76
+ "date_overrides": [{"date": "2026-11-18", "windows": []}],
77
+ "session_minutes": 60,
78
+ "break_minutes": 10,
79
+ "daily_subject_limit_minutes": 120, # 2 hours / subject / day
80
+ }
81
+
82
+ plan = generate_plan(request)
83
+ print(summarize_plan(plan))
84
+ print(plan["sessions"][:2])
85
+ ```
86
+
87
+ For **JupyterHub**, after installing the package in the notebook environment, show the weekly calendar **inline**, without needing to expose a web port:
88
+
89
+ ```python
90
+ from IPython.display import display, HTML
91
+ display(HTML(render_week_html(plan)))
92
+ ```
93
+
94
+ For calendar apps, save an ICS file (times are floating local times, not automatically timezone-adjusted):
95
+
96
+ ```python
97
+ from pathlib import Path
98
+ Path("my_plan.ics").write_bytes(to_ics(plan).encode("utf-8"))
99
+ ```
100
+
101
+ See [`examples/quickstart.py`](examples/quickstart.py) and [`examples/jupyterhub_demo.ipynb`](examples/jupyterhub_demo.ipynb) for full examples.
102
+
103
+ ## Web interface (PyCharm)
104
+
105
+ In PyCharm, open the project folder and run `run.py`, or from a terminal:
106
+
107
+ ```bash
108
+ python -m study_plan
109
+ # Equivalent after installation:
110
+ study-plan
111
+ ```
112
+
113
+ The application opens at **http://127.0.0.1:8765/**. Enter subjects and planned hours, choose the date range and free time windows, then click **Generate Plan**. Review study sessions, subject progress and available/remaining hours in the weekly view. Use **Previous/Next Week** to navigate.
114
+
115
+ Options:
116
+
117
+ ```bash
118
+ study-plan --no-browser # print URL without opening a browser
119
+ study-plan --port 8766 # choose another port
120
+ study-plan --cli # original terminal input mode
121
+ study-plan --demo # original static HTML example
122
+ ```
123
+
124
+ Press **Ctrl+C** in your terminal to shut down the server. It only binds to `127.0.0.1`, so it is designed for local use, not public deployment or remote JupyterHub hosting.
125
+
126
+ ## Inputs, outputs and constraints
127
+
128
+ `generate_plan(request)` accepts a dictionary with these fields:
129
+
130
+ | Field | Description |
131
+ |---|---|
132
+ | `start_date`, `end_date` | Inclusive dates, `YYYY-MM-DD` |
133
+ | `subjects` | List of `{name, hours, exam_date?}` objects; hours in 0.5h increments |
134
+ | `daily_windows` | Default list of `{start, end}` windows in `HH:MM` local time |
135
+ | `date_overrides` | Optional list of `{date, windows}` replacing defaults for that date; `[]` means a day off |
136
+ | `session_minutes` | `30`, `60`, or `90` (default `60`) |
137
+ | `break_minutes` | `0`, `5`, `10`, or `15` (default `10`) |
138
+ | `daily_subject_limit_minutes` | Hard per-subject daily cap, in minutes, from `60` to `480` in 30-minute increments (default `120` = 2h); applies even if a subject has an imminent exam |
139
+
140
+ The result includes `sessions`, `subjects`, `availability`, `start_date`, `end_date`, `settings`, `warnings`, and `summary`. Each `subjects` item has `individual_capacity_upper_bound_minutes`, a theoretical maximum for that subject before its exam, accounting for its daily cap and free days **but not** breaks or competition with other subjects. `warnings` explain incomplete plans. The planner intentionally spaces work across eligible dates, so early free time may remain empty even while future days are scheduled. Sometimes the calendar also leaves empty slots because all remaining subjects hit their daily caps; this is correct behavior, not a missing event. Each session has a subject, day, start/end times, and an integer subject ID. Errors raise `study_plan.InputError` for invalid requests. An examination on a particular date means the study must be scheduled **before** that date.
141
+
142
+ Output can be displayed in a notebook with `render_week_html(plan)`, summarized with `summarize_plan(plan)` or exported with `to_ics(plan)`.
143
+
144
+ ## Development & testing
145
+
146
+ ```bash
147
+ python -m unittest discover -s tests -v
148
+ python -m pip install .
149
+ study-plan --help
150
+ ```
151
+
152
+ The package layout:
153
+
154
+ ```text
155
+ pyproject.toml PyPI metadata, build config, console command
156
+ study_plan/ Importable Python package
157
+ planner.py Validation + hard daily cap + priority-aware scheduling
158
+ exports.py Jupyter HTML, ICS export, progress summary
159
+ web_app.py Local HTTP interface
160
+ static/ Shipped HTML/CSS/JS assets
161
+ __main__.py Command-line entry point
162
+ scheduler.py Original algorithm retained for compatibility
163
+ input_ui.py Original terminal interface retained
164
+ calendar_view.py Original HTML export retained
165
+ tests/ Standard-library unit and API tests (incl. MA1508 regression)
166
+ examples/ Python and JupyterHub examples
167
+ docs/ALGORITHM.md Algorithm, innovation, limitations
168
+ docs/PUBLISHING_AND_DEMO.md Publish + verify on JupyterHub, 1-min presentation
169
+ run.py Simple PyCharm runner
170
+ ```
171
+
172
+ ## Publishing, teamwork and one-minute demo
173
+
174
+ **Please read [`docs/PUBLISHING_AND_DEMO.md`](docs/PUBLISHING_AND_DEMO.md).** The team must still (1) use its public Git repository with regular genuine contributions by members, (2) create a versioned wheel/source distribution, (3) upload those artifacts to PyPI with an authorized account, (4) verify fresh installation in course JupyterHub, and (5) submit/present as instructed by the course.
175
+
176
+ ## Honest limitations
177
+
178
+ This is a deterministic heuristic, **not an AI predictor** or a guarantee of optimal scheduling. It cannot infer learning needs or solve impossible schedules. The included web UI runs locally and is separate from the importable package API. The package is a classroom project that may require further hardening for general production use.
179
+
180
+
181
+ ## Priority-aware planning
182
+
183
+ **Enter subjects from highest to lowest priority.** The first card is priority #1; use the ↑ and ↓ controls to change their order without retyping. The API similarly treats the first `subjects` entry as highest priority.
184
+
185
+ The scheduler uses weighted fair queuing. It favors higher priority subjects when hours are scarce, alternates subjects when possible, and never violates daily study caps or schedules on/after exam days. When enough free time exists to accommodate all subjects up to their caps, some subjects may receive equal hours. Required-hours completion percentages are not guaranteed to be strictly ordered.
186
+
187
+ For a concise setup walkthrough, see [GETTING_STARTED.md](GETTING_STARTED.md).
188
+
189
+ ## Spreading sessions across a long date range
190
+
191
+ The scheduler distributes each subject's study requirement across all dates on which that subject is eligible. More available time on a date can attract a larger share; days off have no allocations. A short workload over several weeks remains visible in later weeks, rather than being packed into the beginning.
192
+
193
+ **Exam dates take precedence over spreading:** a subject's study blocks can only appear before its exam date. Priority order still controls how competing subjects share limited hours, with the strict per-subject daily cap and session breaks unchanged. A small workload cannot fill every date when each session requires at least 30 minutes.
194
+
195
+ ## Morning / afternoon balance
196
+
197
+ The scheduler balances study sessions over multiple available windows **within each day**. For example, with free periods at 08:00–11:00 and 14:00–17:00, it avoids placing all daily sessions in the morning when both windows have room. Long and short windows receive study time in proportion to their capacity; if there is only one short session on a given day, the preferred window rotates across active study days. All existing subject priorities, daily limits, exam cutoffs and date-aware pacing remain in effect.
198
+
199
+ This is a heuristic for practical distribution, not a promise of exactly equal morning and afternoon totals for every possible set of availability windows.
@@ -0,0 +1,16 @@
1
+ study_plan/__init__.py,sha256=zp2tXfcEPoPsNYu2Dzc_2mt73yAUCtKayV0A4o1Mh-Y,454
2
+ study_plan/__main__.py,sha256=vYIyJFvN8nT6jc22yx1leGADDbfHPsHFVa3XL-FZsDM,2043
3
+ study_plan/calendar_view.py,sha256=WH6uPe0u_pw2Yh8CKGBJJ3miKCpJ38PCVqNKlRcz2RM,3573
4
+ study_plan/exports.py,sha256=Dccj-gkoNCtOZ-rqzUbGbg-0L98_SnwXQEEYPk-ItSk,4644
5
+ study_plan/input_ui.py,sha256=czqb1QiT_he5MZoZshVTPR19VLrdVhDA5WCN13pt2Rs,3003
6
+ study_plan/planner.py,sha256=9wdc4Ea34ITWIIu4HLau8knmQeQLH_OmtueDbHtGlnc,16820
7
+ study_plan/scheduler.py,sha256=Uy57JEMJoIOnYv9fy8f9jctjUJEWzkOa4zbJuGbBimc,2064
8
+ study_plan/web_app.py,sha256=Bk131CIWn0fC1UA1aj9dwchTomw-RXMYNw9n95rrOYw,3377
9
+ study_plan/static/app.js,sha256=cctgP4zTfhohRuwDz-BKHrSpCMU-uGVbKmmVxt0LX0M,14881
10
+ study_plan/static/index.html,sha256=Pq0zaw1m_48ujl65HuKXnHMS6JFn2rTWFmWUOOks1sw,11530
11
+ study_plan/static/style.css,sha256=cR1VrqkldviL_YCEJdbWbR0KGY_Jb62KeKHS6WVMAJg,15574
12
+ smart_study_planner-0.5.0.dist-info/METADATA,sha256=S2Jtiv_nULtwibbcYTy0BLrk_OoQKKycyVjH7aoUn34,11939
13
+ smart_study_planner-0.5.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
14
+ smart_study_planner-0.5.0.dist-info/entry_points.txt,sha256=tHH1OUusyZhG8AdwGkUdhn3tsxkkfDlbV-2jds_xNT8,56
15
+ smart_study_planner-0.5.0.dist-info/top_level.txt,sha256=O8F89Y0abLbW1xeFAs9VarrA9AJgIMZunK8WzAerAfw,11
16
+ smart_study_planner-0.5.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ study-plan = study_plan.__main__:main
@@ -0,0 +1 @@
1
+ study_plan
study_plan/__init__.py ADDED
@@ -0,0 +1,15 @@
1
+ """Reusable scheduling tools for the CS1302 Smart Study Planner.
2
+
3
+ Example::
4
+
5
+ from study_plan import generate_plan
6
+ plan = generate_plan({ ... })
7
+
8
+ The package uses only the Python standard library; a browser is optional.
9
+ """
10
+
11
+ from .planner import InputError, generate_plan
12
+ from .exports import to_ics, render_week_html, summarize_plan
13
+
14
+ __version__ = "0.5.0"
15
+ __all__ = ["InputError", "generate_plan", "to_ics", "render_week_html", "summarize_plan"]
study_plan/__main__.py ADDED
@@ -0,0 +1,53 @@
1
+ """Project entry: local web interface, legacy CLI, or legacy HTML demo."""
2
+
3
+ import argparse
4
+ from datetime import date, timedelta
5
+
6
+ from .calendar_view import save_calendar
7
+ from .input_ui import collect_input
8
+ from .scheduler import schedule
9
+ from .web_app import run_web
10
+
11
+
12
+ def demo_input():
13
+ start_date = date(2026, 11, 9)
14
+ tasks = [
15
+ {"subject": "CS1302A Python", "exam_date": date(2026, 11, 11), "minutes": 180},
16
+ {"subject": "Mathematics", "exam_date": date(2026, 11, 14), "minutes": 180},
17
+ ]
18
+ slots = []
19
+ for offset in range(7):
20
+ slots.append({"date": start_date + timedelta(days=offset), "start": 19 * 60,
21
+ "end": 20 * 60})
22
+ return start_date, tasks, slots
23
+
24
+
25
+ def main():
26
+ parser = argparse.ArgumentParser(description="Smart Study Planner local calendar")
27
+ group = parser.add_mutually_exclusive_group()
28
+ group.add_argument("--cli", action="store_true", help="Use legacy terminal input mode")
29
+ group.add_argument("--demo", action="store_true", help="Generate a legacy HTML example")
30
+ parser.add_argument("--port", type=int, default=8765, help="Web server port (default: 8765)")
31
+ parser.add_argument("--no-browser", action="store_true", help="Do not open the browser automatically")
32
+ args = parser.parse_args()
33
+
34
+ if not args.cli and not args.demo:
35
+ if not 0 <= args.port <= 65535:
36
+ parser.error("Port must be between 0 and 65535.")
37
+ run_web(args.port, not args.no_browser)
38
+ return
39
+ try:
40
+ start_date, tasks, slots = demo_input() if args.demo else collect_input()
41
+ sessions, unscheduled = schedule(tasks, slots)
42
+ path = save_calendar(start_date, slots, sessions, unscheduled)
43
+ except (EOFError, KeyboardInterrupt):
44
+ print("\nInput cancelled.")
45
+ return
46
+ print(f"Calendar generated:{path}")
47
+ print(f"Browser URL:{path.as_uri()}")
48
+ for task in unscheduled:
49
+ print(f'{task["subject"]} has {task["remaining_minutes"]} minutes remaining')
50
+
51
+
52
+ if __name__ == "__main__":
53
+ main()
@@ -0,0 +1,70 @@
1
+ """Render a standalone offline HTML weekly calendar."""
2
+
3
+ from datetime import timedelta
4
+ from html import escape
5
+ from pathlib import Path
6
+
7
+
8
+ COLORS = ["#dbeafe", "#fce7f3", "#dcfce7", "#fef3c7", "#ede9fe", "#cffafe"]
9
+
10
+
11
+ def format_time(minutes):
12
+ return f"{minutes // 60:02d}:{minutes % 60:02d}"
13
+
14
+
15
+ def save_calendar(start_date, available_slots, sessions, unscheduled,
16
+ output_path="study_plan.html"):
17
+ """Save HTML and return absolute path; subject names are escaped."""
18
+ days = [start_date + timedelta(days=offset) for offset in range(7)]
19
+ first = min((slot["start"] for slot in available_slots), default=9 * 60)
20
+ last = max((slot["end"] for slot in available_slots), default=17 * 60)
21
+ occupied = {(s["date"], s["start"]): s for s in sessions}
22
+ free = set()
23
+ for slot in available_slots:
24
+ for minute in range(slot["start"], slot["end"], 30):
25
+ free.add((slot["date"], minute))
26
+
27
+ parts = ['<!doctype html><html lang="en"><head><meta charset="utf-8">',
28
+ '<meta name="viewport" content="width=device-width, initial-scale=1">',
29
+ '<title>Study Planner · Weekly Calendar</title><style>',
30
+ 'body{font-family:system-ui,sans-serif;margin:24px;color:#172033}',
31
+ '.calendar{overflow-x:auto}table{border-collapse:collapse;width:100%;min-width:900px}',
32
+ 'th,td{border:1px solid #cbd5e1;padding:10px;text-align:center;min-width:95px}',
33
+ 'th{background:#f1f5f9}td{height:42px}.unavailable{background:#e5e7eb;color:#64748b}',
34
+ 'small{display:block;margin-top:4px}li{margin:8px 0}',
35
+ '</style></head><body><h1>Study Planner · 7-Day Plan</h1>',
36
+ '<p>Each cell represents 30 minutes. Gray cells are unavailable; empty cells are free.</p>',
37
+ '<div class="calendar"><table><thead><tr><th scope="col">Time</th>']
38
+ weekdays = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
39
+ for day in days:
40
+ parts.append(f'<th scope="col">{day.isoformat()}<br>{weekdays[day.weekday()]}</th>')
41
+ parts.append('</tr></thead><tbody>')
42
+ for minute in range(first, last, 30):
43
+ label = f"{format_time(minute)}–{format_time(minute + 30)}"
44
+ parts.append(f'<tr><th scope="row">{label}</th>')
45
+ for day in days:
46
+ session = occupied.get((day, minute))
47
+ if session:
48
+ color = COLORS[session["subject_id"] % len(COLORS)]
49
+ # Beyond the palette, a distinct hue keeps additional subjects distinct.
50
+ if session["subject_id"] >= len(COLORS):
51
+ color = f'hsl({session["subject_id"] * 137.508 % 360:.3f},70%,88%)'
52
+ parts.append(f'<td style="background:{color}">{escape(session["subject"])}'
53
+ f'<small>{label}</small></td>')
54
+ elif (day, minute) in free:
55
+ parts.append('<td></td>')
56
+ else:
57
+ parts.append('<td class="unavailable">Unavailable</td>')
58
+ parts.append('</tr>')
59
+ parts.append('</tbody></table></div><h2>Unscheduled study time</h2>')
60
+ if unscheduled:
61
+ parts.append('<ul>')
62
+ for task in unscheduled:
63
+ parts.append(f'<li>{escape(task["subject"])} — {task["remaining_minutes"]} minutes remaining</li>')
64
+ parts.append('</ul>')
65
+ else:
66
+ parts.append('<p>All requested study time has been scheduled (0 minutes remaining).</p>')
67
+ parts.append('</body></html>')
68
+ path = Path(output_path).resolve()
69
+ path.write_text("\n".join(parts), encoding="utf-8")
70
+ return path
study_plan/exports.py ADDED
@@ -0,0 +1,96 @@
1
+ """Reusable, dependency-free exports for notebooks, other apps and calendars."""
2
+
3
+ from datetime import date, timedelta, datetime, timezone
4
+ from html import escape
5
+ import re
6
+
7
+
8
+ def summarize_plan(plan):
9
+ """Return clear, data-only completion metrics for an existing plan."""
10
+ subjects = []
11
+ for subject in plan["subjects"]:
12
+ required = subject["required_minutes"]
13
+ scheduled = subject["scheduled_minutes"]
14
+ subjects.append({
15
+ "name": subject["name"],
16
+ "required_hours": round(required / 60, 2),
17
+ "scheduled_hours": round(scheduled / 60, 2),
18
+ "remaining_hours": round(subject["remaining_minutes"] / 60, 2),
19
+ "completion_percentage": round(100 * scheduled / required, 1) if required else 100.0,
20
+ "exam_date": subject["exam_date"],
21
+ })
22
+ return {
23
+ "required_hours": round(plan["summary"]["required_minutes"] / 60, 2),
24
+ "scheduled_hours": round(plan["summary"]["scheduled_minutes"] / 60, 2),
25
+ "remaining_hours": round(plan["summary"]["remaining_minutes"] / 60, 2),
26
+ "subjects": subjects,
27
+ }
28
+
29
+
30
+ def _ical_escape(value):
31
+ """Escape property text according to RFC 5545 for simple VEVENT output."""
32
+ return str(value).replace("\\", "\\\\").replace("\n", "\\n").replace(",", "\\,").replace(";", "\\;")
33
+
34
+
35
+ def to_ics(plan, calendar_name="Study Plan"):
36
+ """Export the scheduled sessions as a calendar ICS string (floating local times).
37
+
38
+ Times are intentionally *floating* local times because the input has no
39
+ timezone. Importers will interpret them in their own default timezone.
40
+ """
41
+ lines = ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//CS1302 Group06//SmartStudyPlanner//EN",
42
+ f"X-WR-CALNAME:{_ical_escape(calendar_name)}"]
43
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
44
+ for idx, session in enumerate(plan["sessions"], 1):
45
+ event_date = date.fromisoformat(session["date"])
46
+ day = event_date.strftime("%Y%m%d")
47
+ start = str(session["start_time"]).replace(":", "") + "00"
48
+ end_time = str(session["end_time"])
49
+ # RFC 5545 expects midnight at the start of the *next* calendar day.
50
+ if end_time == "24:00":
51
+ end_day = (event_date + timedelta(days=1)).strftime("%Y%m%d")
52
+ end = "000000"
53
+ else:
54
+ end_day = day
55
+ end = end_time.replace(":", "") + "00"
56
+ if not re.fullmatch(r"\d{6}", start) or not re.fullmatch(r"\d{6}", end):
57
+ raise ValueError("Invalid session time")
58
+ lines.extend([
59
+ "BEGIN:VEVENT", f"UID:study-{day}-{idx}@cs1302-group06",
60
+ f"DTSTAMP:{stamp}", f"DTSTART:{day}T{start}",
61
+ f"DTEND:{end_day}T{end}",
62
+ f"SUMMARY:{_ical_escape('Study: ' + session['subject'])}", "END:VEVENT",
63
+ ])
64
+ lines.append("END:VCALENDAR")
65
+ return "\r\n".join(lines) + "\r\n"
66
+
67
+
68
+ def render_week_html(plan, week_start=None):
69
+ """Return notebook-friendly standalone HTML for a seven-day calendar.
70
+
71
+ Run in JupyterHub with ``display(HTML(render_week_html(plan)))``.
72
+ Subject names are HTML-escaped to prevent interpreted input.
73
+ """
74
+ first = date.fromisoformat(week_start or plan["start_date"])
75
+ days = [first + timedelta(days=i) for i in range(7)]
76
+ colors = ["#dbeafe", "#fce7f3", "#dcfce7", "#fef3c7", "#ede9fe", "#cffafe"]
77
+ headers = "".join(f"<th style='padding:10px;background:#f1f5f9'>{d:%a %d %b}</th>" for d in days)
78
+ columns = []
79
+ for day in days:
80
+ items = []
81
+ for event in plan["sessions"]:
82
+ if event["date"] != day.isoformat():
83
+ continue
84
+ color = colors[int(event["subject_id"]) % len(colors)]
85
+ title = escape(event["subject"])
86
+ start, end = escape(event["start_time"]), escape(event["end_time"])
87
+ items.append(f"<div style='background:{color};border-left:4px solid #64748b;"
88
+ f"border-radius:8px;padding:8px;margin:5px 2px;text-align:left'>"
89
+ f"<strong>{title}</strong><br><small>{start}–{end}</small></div>")
90
+ columns.append("<td style='vertical-align:top;min-width:120px;height:140px;"
91
+ "padding:5px;border:1px solid #d1d5db'>" + "".join(items) + "</td>")
92
+ return ("<div style='font-family:Arial,sans-serif;color:#1e293b;overflow:auto'>"
93
+ "<h3>Smart Study Planner · Weekly View</h3>"
94
+ "<table style='border-collapse:collapse;width:100%;min-width:840px'><thead><tr>"
95
+ + headers + "</tr></thead><tbody><tr>" + "".join(columns) +
96
+ "</tr></tbody></table></div>")
study_plan/input_ui.py ADDED
@@ -0,0 +1,83 @@
1
+ """Terminal input and validation; times are minutes since midnight."""
2
+
3
+ from datetime import date, timedelta
4
+
5
+
6
+ def ask_date(prompt):
7
+ while True:
8
+ value = input(prompt).strip()
9
+ try:
10
+ result = date.fromisoformat(value)
11
+ if result.isoformat() != value:
12
+ raise ValueError
13
+ return result
14
+ except ValueError:
15
+ print("Enter a valid date in YYYY-MM-DD format, e.g. 2026-11-10.")
16
+
17
+
18
+ def ask_positive_integer(prompt, multiple=1):
19
+ while True:
20
+ try:
21
+ value = int(input(prompt).strip())
22
+ if value > 0 and value % multiple == 0:
23
+ return value
24
+ except ValueError:
25
+ pass
26
+ print(f"Enter a positive integer divisible by {multiple}.")
27
+
28
+
29
+ def ask_time(prompt):
30
+ while True:
31
+ value = input(prompt).strip()
32
+ try:
33
+ hour, minute = value.split(":")
34
+ hour, minute = int(hour), int(minute)
35
+ if 0 <= hour <= 23 and minute in (0, 30):
36
+ return hour * 60 + minute
37
+ if hour == 24 and minute == 0:
38
+ return 1440
39
+ except ValueError:
40
+ pass
41
+ print("Enter a half-hour time, such as 09:00 or 09:30; 24:00 is only valid as an end time.")
42
+
43
+
44
+ def collect_input():
45
+ start_date = ask_date("Plan start date (YYYY-MM-DD): ")
46
+ while start_date > date.max - timedelta(days=6):
47
+ print("Start date must permit a full 7-day plan.")
48
+ start_date = ask_date("Plan start date (YYYY-MM-DD): ")
49
+
50
+ count = ask_positive_integer("How many free-time windows per day? ")
51
+ windows = []
52
+ for index in range(count):
53
+ while True:
54
+ print(f"Default time window {index + 1} (repeated daily):")
55
+ start = ask_time("Start time (HH:MM): ")
56
+ end = ask_time("End time (HH:MM): ")
57
+ if start >= end:
58
+ print("End time must be later than start time on the same day. Try again.")
59
+ elif any(start < old_end and old_start < end
60
+ for old_start, old_end in windows):
61
+ print("Time windows must not overlap. Try again.")
62
+ else:
63
+ windows.append((start, end))
64
+ break
65
+
66
+ tasks = []
67
+ count = ask_positive_integer("How many subjects? ")
68
+ for index in range(count):
69
+ name = ""
70
+ while not name:
71
+ name = input(f"Name of subject #{index + 1}: ").strip()
72
+ if not name:
73
+ print("Subject name cannot be empty.")
74
+ exam_date = ask_date("Exam date (YYYY-MM-DD): ")
75
+ minutes = ask_positive_integer("Remaining study time (minutes, divisible by 30): ", 30)
76
+ tasks.append({"subject": name, "exam_date": exam_date, "minutes": minutes})
77
+
78
+ slots = []
79
+ for day_offset in range(7):
80
+ day = start_date + timedelta(days=day_offset)
81
+ for start, end in windows:
82
+ slots.append({"date": day, "start": start, "end": end})
83
+ return start_date, tasks, slots