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.
- smart_study_planner-0.5.0.dist-info/METADATA +199 -0
- smart_study_planner-0.5.0.dist-info/RECORD +16 -0
- smart_study_planner-0.5.0.dist-info/WHEEL +5 -0
- smart_study_planner-0.5.0.dist-info/entry_points.txt +2 -0
- smart_study_planner-0.5.0.dist-info/top_level.txt +1 -0
- study_plan/__init__.py +15 -0
- study_plan/__main__.py +53 -0
- study_plan/calendar_view.py +70 -0
- study_plan/exports.py +96 -0
- study_plan/input_ui.py +83 -0
- study_plan/planner.py +356 -0
- study_plan/scheduler.py +43 -0
- study_plan/static/app.js +328 -0
- study_plan/static/index.html +132 -0
- study_plan/static/style.css +24 -0
- study_plan/web_app.py +86 -0
|
@@ -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 @@
|
|
|
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
|