uwquest 0.1.0__tar.gz

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.
Files changed (33) hide show
  1. uwquest-0.1.0/.gitignore +10 -0
  2. uwquest-0.1.0/DISCLAIMER.md +45 -0
  3. uwquest-0.1.0/LICENSE +21 -0
  4. uwquest-0.1.0/PKG-INFO +199 -0
  5. uwquest-0.1.0/README.md +163 -0
  6. uwquest-0.1.0/pyproject.toml +64 -0
  7. uwquest-0.1.0/scripts/demo.py +183 -0
  8. uwquest-0.1.0/src/quest/__init__.py +34 -0
  9. uwquest-0.1.0/src/quest/cli.py +237 -0
  10. uwquest-0.1.0/src/quest/core/__init__.py +2 -0
  11. uwquest-0.1.0/src/quest/core/models.py +113 -0
  12. uwquest-0.1.0/src/quest/core/parsers.py +136 -0
  13. uwquest-0.1.0/src/quest/core/session.py +275 -0
  14. uwquest-0.1.0/src/quest/errors.py +39 -0
  15. uwquest-0.1.0/src/quest/readers/__init__.py +32 -0
  16. uwquest-0.1.0/src/quest/readers/academic_requirements.py +36 -0
  17. uwquest-0.1.0/src/quest/readers/account.py +25 -0
  18. uwquest-0.1.0/src/quest/readers/course_availability.py +160 -0
  19. uwquest-0.1.0/src/quest/readers/dashboard.py +29 -0
  20. uwquest-0.1.0/src/quest/readers/enrollment_dates.py +15 -0
  21. uwquest-0.1.0/src/quest/readers/financial_aid.py +19 -0
  22. uwquest-0.1.0/src/quest/readers/grades.py +43 -0
  23. uwquest-0.1.0/src/quest/readers/holds.py +28 -0
  24. uwquest-0.1.0/src/quest/readers/milestones.py +20 -0
  25. uwquest-0.1.0/src/quest/readers/program.py +19 -0
  26. uwquest-0.1.0/src/quest/readers/schedule.py +79 -0
  27. uwquest-0.1.0/src/quest/readers/transcript.py +43 -0
  28. uwquest-0.1.0/src/quest/tui/__init__.py +7 -0
  29. uwquest-0.1.0/src/quest/tui/app.py +249 -0
  30. uwquest-0.1.0/tests/test_cli.py +86 -0
  31. uwquest-0.1.0/tests/test_parsers.py +44 -0
  32. uwquest-0.1.0/tests/test_session.py +109 -0
  33. uwquest-0.1.0/tests/test_tui.py +45 -0
@@ -0,0 +1,10 @@
1
+ .venv*/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ cookies.json
8
+ *.cookies.json
9
+ *.pdf
10
+ snapshot*.json
@@ -0,0 +1,45 @@
1
+ # Disclaimer
2
+
3
+ **Read this before installing or running uwquest. By using, copying, modifying or
4
+ distributing this software you acknowledge and accept everything below.**
5
+
6
+ ## AI-generated code
7
+
8
+ Most of this project's code, tests and documentation were written with the help
9
+ of an AI coding assistant (Anthropic's Claude). AI-generated code can contain
10
+ mistakes or behaviour that doesn't match its documentation, even when it appears
11
+ to work. **Inspect, review and test the code yourself before running it.**
12
+
13
+ ## No warranty
14
+
15
+ This software is provided **"AS IS"**, without warranty of any kind, express or
16
+ implied, including merchantability, fitness for a particular purpose, accuracy,
17
+ and non-infringement. The entire risk as to its quality and results is with you.
18
+ The warranty disclaimer in the MIT [LICENSE](LICENSE) also applies.
19
+
20
+ ## Limitation of liability
21
+
22
+ To the maximum extent permitted by law, in no event will the author(s) be liable
23
+ for any damages of any kind arising from the use of this software, however caused
24
+ and under any theory of liability.
25
+
26
+ ## Your responsibilities
27
+
28
+ - **Your own account.** Use this only on a Quest account you own. Accessing
29
+ someone else's records is prohibited and likely illegal.
30
+ - **Acceptable use.** Automated access to Quest may be restricted by the
31
+ University of Waterloo's acceptable-use and IT policies. It is your
32
+ responsibility to check and comply. Keep request rates modest.
33
+ - **Credentials.** Your browser cookie session is as sensitive as your password
34
+ while valid. The tool never stores your Quest token persistently; protect your
35
+ cookies file.
36
+ - **Read-only, but verify.** This tool is designed to read, not change, your
37
+ records, and it blocks Personal-Information pages. Review the code to confirm
38
+ this before relying on it.
39
+
40
+ ## Not affiliated
41
+
42
+ This is an independent, unofficial project, not affiliated with, endorsed by, or
43
+ supported by the University of Waterloo or Oracle Corporation. "Quest",
44
+ "PeopleSoft" and related names are trademarks of their respective owners, used
45
+ here only to describe compatibility.
uwquest-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Amol Venkataraman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
uwquest-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,199 @@
1
+ Metadata-Version: 2.5
2
+ Name: uwquest
3
+ Version: 0.1.0
4
+ Summary: Read-first CLI and Python client for UWaterloo Quest (PeopleSoft) student self-service
5
+ Project-URL: Homepage, https://github.com/amolvenkataraman/uwquest
6
+ Project-URL: Repository, https://github.com/amolvenkataraman/uwquest
7
+ Project-URL: Issues, https://github.com/amolvenkataraman/uwquest/issues
8
+ Author: Amol Venkataraman
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: cli,peoplesoft,quest,student,unofficial,uwaterloo
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: End Users/Desktop
15
+ Classifier: Natural Language :: English
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Education
23
+ Classifier: Topic :: Utilities
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: requests>=2.31
26
+ Requires-Dist: selectolax>=0.3.21
27
+ Provides-Extra: browser
28
+ Requires-Dist: browser-cookie3>=0.19; extra == 'browser'
29
+ Provides-Extra: dev
30
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
31
+ Requires-Dist: pytest>=8; extra == 'dev'
32
+ Provides-Extra: tui
33
+ Requires-Dist: rich>=13; extra == 'tui'
34
+ Requires-Dist: textual>=0.60; extra == 'tui'
35
+ Description-Content-Type: text/markdown
36
+
37
+ <!-- header:start -->
38
+ <div align="center">
39
+
40
+ <img alt="uwquest: UWaterloo Quest from your terminal: classes, grades and enrollment. Read-only." src="https://raw.githubusercontent.com/amolvenkataraman/uwquest/main/.github/assets/banner.svg" width="100%">
41
+
42
+ ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-0f6f68?labelColor=15181c&color=0f6f68)
43
+ [![licence: MIT](https://img.shields.io/badge/licence-MIT-0f6f68?labelColor=15181c&color=0f6f68)](https://github.com/amolvenkataraman/uwquest/blob/main/LICENSE)
44
+
45
+ [Install](#install) · [Usage](#usage) · [Terminal UI](#terminal-ui) · [How it works](#how-it-works) · [Status](#status)
46
+
47
+ </div>
48
+
49
+ <a href="https://haiscale.amolven.com/A1/"><img alt="HAI Scale A1, Mostly automated. Most of the code was written by AI coding agents. I directed the design, reviewed the changes and tested it on my own account. Unofficial and not affiliated with the University of Waterloo. Provided as is, with no warranty. Read DISCLAIMER.md before use." src="https://raw.githubusercontent.com/amolvenkataraman/uwquest/main/.github/assets/hai.svg" width="100%"></a>
50
+
51
+ <sub>Use it only on your own account, at a modest request rate, and check UW's acceptable-use policy for automated access. Full terms: [DISCLAIMER.md](https://github.com/amolvenkataraman/uwquest/blob/main/DISCLAIMER.md)</sub>
52
+ <!-- header:end -->
53
+
54
+ ![Terminal recording: quest status, quest schedule and quest classes CS 341 --seats, then the TUI's Dashboard, Schedule, Grades, Account and Classes tabs](https://raw.githubusercontent.com/amolvenkataraman/uwquest/main/docs/media/demo.gif)
55
+
56
+ <sub>The recording uses synthetic data from [`scripts/demo.py`](https://github.com/amolvenkataraman/uwquest/blob/main/scripts/demo.py); no real student record is shown.</sub>
57
+
58
+ A read-first command-line tool and Python client for **UWaterloo Quest**
59
+ (the university's PeopleSoft student self-service system).
60
+
61
+ It logs in with a browser cookie session (Quest uses SSO + Duo, which you do once
62
+ in your browser) and reads your own records into plain data — no enrolling, no
63
+ payments, and Personal-Information pages are blocked in code.
64
+
65
+ ## Install
66
+
67
+ From PyPI (the package is `uwquest`; the command it installs is `quest`):
68
+
69
+ ```bash
70
+ pipx install uwquest # or: uv tool install uwquest
71
+ pipx install 'uwquest[browser]' # also read cookies live from the browser
72
+ pipx install 'uwquest[browser,tui]' # plus the terminal UI
73
+ pip install uwquest # as a library in an existing environment
74
+ ```
75
+
76
+ From source:
77
+
78
+ ```bash
79
+ git clone https://github.com/amolvenkataraman/uwquest && cd uwquest
80
+ uv tool install . # base (file-based cookies)
81
+ uv tool install '.[browser]' # also read cookies live from the browser
82
+ ```
83
+
84
+ ## Cookies
85
+
86
+ Log into Quest in your browser, then either:
87
+
88
+ - **Export** the `pecs.uwaterloo.ca` cookies to JSON and point the tool at it
89
+ (`--cookies-file path.json`, or put it at `~/.config/quest/cookies.json`), or
90
+ - **Read them live** from the browser: `quest --browser brave holds`.
91
+
92
+ The session slides while you use it, so repeated commands keep it alive until
93
+ UW's SSO cap; when it expires the tool tells you to log in again.
94
+
95
+ ## Usage
96
+
97
+ ```bash
98
+ quest status # one-screen summary: program, balance, holds, next enrollment
99
+ quest schedule # enrolled classes this term
100
+ quest grades --term "Winter 2026" # grades (defaults to the latest term)
101
+ quest terms # term labels available for grades
102
+ quest account # per-term registration status and balance
103
+ quest holds # service indicators
104
+ quest milestones # requirements, scholarships
105
+ quest program # plan, academic load, campus
106
+ quest enrollment-dates # when enrollment opens
107
+ quest financial-aid # aid years on record
108
+ quest classes MATH 135 # course availability (status per section, no enrolling)
109
+ quest classes CS 486 --seats # also fetch seat counts (slower)
110
+ quest classes PMATH --open-only # whole subject, open sections only
111
+ quest transcript -o transcript.pdf # download the unofficial transcript PDF
112
+ quest schedule --json # raw JSON on any command (--json also works before it)
113
+ quest tui # interactive terminal UI (needs the 'tui' extra)
114
+ ```
115
+
116
+ The transcript PDF is only *fetched* here; parsing it (GPA, averages, standing)
117
+ is a separate service. `academic-requirements` is experimental (UW renders that
118
+ report dynamically).
119
+
120
+ ## Terminal UI
121
+
122
+ `quest tui` opens a tabbed interface — Dashboard, Schedule, Grades (type a term),
123
+ Account, Holds, and a Classes browser with coloured Open/Closed/Waitlist status.
124
+ Install it with the `tui` extra.
125
+
126
+ ## How it works
127
+
128
+ **Session.** Quest sits behind UW's SSO and Duo, so the tool never handles a
129
+ password. `QuestSession` copies an existing browser session into a
130
+ `requests.Session`, either from an exported JSON array of cookies
131
+ (`name`/`value`/`domain`/`path`) or straight from the browser's cookie store via
132
+ `browser_cookie3`. Every request goes to the PeopleSoft content URL for one
133
+ component, `https://quest.pecs.uwaterloo.ca/psc/SS/ACADEMIC/SA/c/<COMPONENT>`,
134
+ not the portal frame around it. Each response is checked for the sign-in page
135
+ (a `cmd=login` or `/signon` URL, a sign-in title, or `userid`/`pwd` fields); if it
136
+ shows up, the call raises `SessionExpired` instead of parsing a login form.
137
+ Requests are serialised by a lock and spaced at least 0.5 s apart.
138
+ `heartbeat()` loads the landing page to keep the session sliding.
139
+
140
+ **Pages and state.** Each reader handles one component. A GET returns the page,
141
+ and the session stores that page's hidden form fields (`ICSID`, `ICStateNum` and
142
+ the rest) per component. `action()` POSTs those stored fields back with an
143
+ `ICAction` and the reader's own fields, then replaces the stored state with the
144
+ new response's, so `ICStateNum` stays in step with the server. If a component
145
+ has no state yet, it is fetched first. Where they can, parsers read PeopleSoft's
146
+ element ids (for example `STDNT_ENRL_SSV1_CRSE_GRADE_OFF$0`) rather than layout.
147
+ Some examples:
148
+
149
+ - Grades: GET the term picker, then POST its GO action with the chosen term's
150
+ index.
151
+ - Class search: one POST of `CLASS_SRCH_WRK2_SSR_PB_CLASS_SRCH` with subject,
152
+ number, term and career. `--seats` opens each section (`MTG_CLASS_NBR$<n>`)
153
+ and goes back, so it costs two requests per section and stops at 40 sections.
154
+ - Transcript: `report()` selects the report type, presses View, follows the
155
+ `/view/` link in the response and checks that the result starts with `%PDF`.
156
+
157
+ **Read-only allowlist.** `action()` POSTs only the `ICAction`s listed in
158
+ `READ_ONLY_ACTIONS` (in `core/session.py`), and each one is tied to its component:
159
+
160
+ | Component | Allowed actions |
161
+ | --- | --- |
162
+ | `UW_SS_MENU.UW_SSR_SSENRL_GRDE.GBL` (grades) | the term picker's `…PB_GO` button |
163
+ | `UW_CEM.UW_CLASS_SRCH.GBL` (class search) | `CLASS_SRCH_WRK2_SSR_PB_CLASS_SRCH`, `CLASS_SRCH_WRK2_SSR_PB_BACK`, `MTG_CLASS_NBR$<n>` |
164
+ | `SA_LEARNER_SERVICES.SSS_TSRQST_UNOFF.GBL` (transcript) | `DERIVED_SSTSRPT_TSCRPT_TYPE3`, `GO1` |
165
+
166
+ Any other action, or any action on another component, raises `BlockedAction`
167
+ before a request is sent. `report()` checks its whole sequence before it starts,
168
+ and `get()` refuses a query string that carries an `ICAction`. Nothing in the
169
+ package touches the shopping cart, enrollment, payments or any form that saves
170
+ data.
171
+
172
+ **Personal-Information blocklist.** Before any request, `get` and `action` check
173
+ the component name against
174
+ `PERSONAL|ADDR|PHONE|EMAIL|EMERG|DISABILITY|ETHNIC|GENDER|DEMOGRAPH`
175
+ (case-insensitive). A match raises `BlockedComponent` and no request is sent.
176
+ `report()` runs the same check before it starts.
177
+
178
+ ## Status
179
+
180
+ Working: the session layer (file + browser cookies, the PeopleSoft request state
181
+ machine, keep-alive, a Personal-Information blocklist) and readers for status,
182
+ schedule, grades, account, holds, milestones, program, enrollment dates, financial
183
+ aid, course availability (with seat counts), and the transcript PDF, plus a
184
+ Textual TUI. All read-only; writes (enrollment) are intentionally not implemented.
185
+
186
+ ## Development
187
+
188
+ ```bash
189
+ uv venv .venv && uv pip install --python .venv/bin/python -e '.[dev]'
190
+ .venv/bin/pytest
191
+ .venv/bin/python scripts/demo.py account # any command on synthetic data; no network or cookies
192
+ ```
193
+
194
+ ## License
195
+
196
+ MIT © 2026 Amol Venkataraman. Provided WITHOUT ANY WARRANTY — see [LICENSE](https://github.com/amolvenkataraman/uwquest/blob/main/LICENSE)
197
+ and [DISCLAIMER.md](https://github.com/amolvenkataraman/uwquest/blob/main/DISCLAIMER.md). Not affiliated with or endorsed by the
198
+ University of Waterloo or Oracle. "Quest" and "PeopleSoft" are used only to
199
+ describe compatibility.
@@ -0,0 +1,163 @@
1
+ <!-- header:start -->
2
+ <div align="center">
3
+
4
+ <img alt="uwquest: UWaterloo Quest from your terminal: classes, grades and enrollment. Read-only." src="https://raw.githubusercontent.com/amolvenkataraman/uwquest/main/.github/assets/banner.svg" width="100%">
5
+
6
+ ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-0f6f68?labelColor=15181c&color=0f6f68)
7
+ [![licence: MIT](https://img.shields.io/badge/licence-MIT-0f6f68?labelColor=15181c&color=0f6f68)](https://github.com/amolvenkataraman/uwquest/blob/main/LICENSE)
8
+
9
+ [Install](#install) · [Usage](#usage) · [Terminal UI](#terminal-ui) · [How it works](#how-it-works) · [Status](#status)
10
+
11
+ </div>
12
+
13
+ <a href="https://haiscale.amolven.com/A1/"><img alt="HAI Scale A1, Mostly automated. Most of the code was written by AI coding agents. I directed the design, reviewed the changes and tested it on my own account. Unofficial and not affiliated with the University of Waterloo. Provided as is, with no warranty. Read DISCLAIMER.md before use." src="https://raw.githubusercontent.com/amolvenkataraman/uwquest/main/.github/assets/hai.svg" width="100%"></a>
14
+
15
+ <sub>Use it only on your own account, at a modest request rate, and check UW's acceptable-use policy for automated access. Full terms: [DISCLAIMER.md](https://github.com/amolvenkataraman/uwquest/blob/main/DISCLAIMER.md)</sub>
16
+ <!-- header:end -->
17
+
18
+ ![Terminal recording: quest status, quest schedule and quest classes CS 341 --seats, then the TUI's Dashboard, Schedule, Grades, Account and Classes tabs](https://raw.githubusercontent.com/amolvenkataraman/uwquest/main/docs/media/demo.gif)
19
+
20
+ <sub>The recording uses synthetic data from [`scripts/demo.py`](https://github.com/amolvenkataraman/uwquest/blob/main/scripts/demo.py); no real student record is shown.</sub>
21
+
22
+ A read-first command-line tool and Python client for **UWaterloo Quest**
23
+ (the university's PeopleSoft student self-service system).
24
+
25
+ It logs in with a browser cookie session (Quest uses SSO + Duo, which you do once
26
+ in your browser) and reads your own records into plain data — no enrolling, no
27
+ payments, and Personal-Information pages are blocked in code.
28
+
29
+ ## Install
30
+
31
+ From PyPI (the package is `uwquest`; the command it installs is `quest`):
32
+
33
+ ```bash
34
+ pipx install uwquest # or: uv tool install uwquest
35
+ pipx install 'uwquest[browser]' # also read cookies live from the browser
36
+ pipx install 'uwquest[browser,tui]' # plus the terminal UI
37
+ pip install uwquest # as a library in an existing environment
38
+ ```
39
+
40
+ From source:
41
+
42
+ ```bash
43
+ git clone https://github.com/amolvenkataraman/uwquest && cd uwquest
44
+ uv tool install . # base (file-based cookies)
45
+ uv tool install '.[browser]' # also read cookies live from the browser
46
+ ```
47
+
48
+ ## Cookies
49
+
50
+ Log into Quest in your browser, then either:
51
+
52
+ - **Export** the `pecs.uwaterloo.ca` cookies to JSON and point the tool at it
53
+ (`--cookies-file path.json`, or put it at `~/.config/quest/cookies.json`), or
54
+ - **Read them live** from the browser: `quest --browser brave holds`.
55
+
56
+ The session slides while you use it, so repeated commands keep it alive until
57
+ UW's SSO cap; when it expires the tool tells you to log in again.
58
+
59
+ ## Usage
60
+
61
+ ```bash
62
+ quest status # one-screen summary: program, balance, holds, next enrollment
63
+ quest schedule # enrolled classes this term
64
+ quest grades --term "Winter 2026" # grades (defaults to the latest term)
65
+ quest terms # term labels available for grades
66
+ quest account # per-term registration status and balance
67
+ quest holds # service indicators
68
+ quest milestones # requirements, scholarships
69
+ quest program # plan, academic load, campus
70
+ quest enrollment-dates # when enrollment opens
71
+ quest financial-aid # aid years on record
72
+ quest classes MATH 135 # course availability (status per section, no enrolling)
73
+ quest classes CS 486 --seats # also fetch seat counts (slower)
74
+ quest classes PMATH --open-only # whole subject, open sections only
75
+ quest transcript -o transcript.pdf # download the unofficial transcript PDF
76
+ quest schedule --json # raw JSON on any command (--json also works before it)
77
+ quest tui # interactive terminal UI (needs the 'tui' extra)
78
+ ```
79
+
80
+ The transcript PDF is only *fetched* here; parsing it (GPA, averages, standing)
81
+ is a separate service. `academic-requirements` is experimental (UW renders that
82
+ report dynamically).
83
+
84
+ ## Terminal UI
85
+
86
+ `quest tui` opens a tabbed interface — Dashboard, Schedule, Grades (type a term),
87
+ Account, Holds, and a Classes browser with coloured Open/Closed/Waitlist status.
88
+ Install it with the `tui` extra.
89
+
90
+ ## How it works
91
+
92
+ **Session.** Quest sits behind UW's SSO and Duo, so the tool never handles a
93
+ password. `QuestSession` copies an existing browser session into a
94
+ `requests.Session`, either from an exported JSON array of cookies
95
+ (`name`/`value`/`domain`/`path`) or straight from the browser's cookie store via
96
+ `browser_cookie3`. Every request goes to the PeopleSoft content URL for one
97
+ component, `https://quest.pecs.uwaterloo.ca/psc/SS/ACADEMIC/SA/c/<COMPONENT>`,
98
+ not the portal frame around it. Each response is checked for the sign-in page
99
+ (a `cmd=login` or `/signon` URL, a sign-in title, or `userid`/`pwd` fields); if it
100
+ shows up, the call raises `SessionExpired` instead of parsing a login form.
101
+ Requests are serialised by a lock and spaced at least 0.5 s apart.
102
+ `heartbeat()` loads the landing page to keep the session sliding.
103
+
104
+ **Pages and state.** Each reader handles one component. A GET returns the page,
105
+ and the session stores that page's hidden form fields (`ICSID`, `ICStateNum` and
106
+ the rest) per component. `action()` POSTs those stored fields back with an
107
+ `ICAction` and the reader's own fields, then replaces the stored state with the
108
+ new response's, so `ICStateNum` stays in step with the server. If a component
109
+ has no state yet, it is fetched first. Where they can, parsers read PeopleSoft's
110
+ element ids (for example `STDNT_ENRL_SSV1_CRSE_GRADE_OFF$0`) rather than layout.
111
+ Some examples:
112
+
113
+ - Grades: GET the term picker, then POST its GO action with the chosen term's
114
+ index.
115
+ - Class search: one POST of `CLASS_SRCH_WRK2_SSR_PB_CLASS_SRCH` with subject,
116
+ number, term and career. `--seats` opens each section (`MTG_CLASS_NBR$<n>`)
117
+ and goes back, so it costs two requests per section and stops at 40 sections.
118
+ - Transcript: `report()` selects the report type, presses View, follows the
119
+ `/view/` link in the response and checks that the result starts with `%PDF`.
120
+
121
+ **Read-only allowlist.** `action()` POSTs only the `ICAction`s listed in
122
+ `READ_ONLY_ACTIONS` (in `core/session.py`), and each one is tied to its component:
123
+
124
+ | Component | Allowed actions |
125
+ | --- | --- |
126
+ | `UW_SS_MENU.UW_SSR_SSENRL_GRDE.GBL` (grades) | the term picker's `…PB_GO` button |
127
+ | `UW_CEM.UW_CLASS_SRCH.GBL` (class search) | `CLASS_SRCH_WRK2_SSR_PB_CLASS_SRCH`, `CLASS_SRCH_WRK2_SSR_PB_BACK`, `MTG_CLASS_NBR$<n>` |
128
+ | `SA_LEARNER_SERVICES.SSS_TSRQST_UNOFF.GBL` (transcript) | `DERIVED_SSTSRPT_TSCRPT_TYPE3`, `GO1` |
129
+
130
+ Any other action, or any action on another component, raises `BlockedAction`
131
+ before a request is sent. `report()` checks its whole sequence before it starts,
132
+ and `get()` refuses a query string that carries an `ICAction`. Nothing in the
133
+ package touches the shopping cart, enrollment, payments or any form that saves
134
+ data.
135
+
136
+ **Personal-Information blocklist.** Before any request, `get` and `action` check
137
+ the component name against
138
+ `PERSONAL|ADDR|PHONE|EMAIL|EMERG|DISABILITY|ETHNIC|GENDER|DEMOGRAPH`
139
+ (case-insensitive). A match raises `BlockedComponent` and no request is sent.
140
+ `report()` runs the same check before it starts.
141
+
142
+ ## Status
143
+
144
+ Working: the session layer (file + browser cookies, the PeopleSoft request state
145
+ machine, keep-alive, a Personal-Information blocklist) and readers for status,
146
+ schedule, grades, account, holds, milestones, program, enrollment dates, financial
147
+ aid, course availability (with seat counts), and the transcript PDF, plus a
148
+ Textual TUI. All read-only; writes (enrollment) are intentionally not implemented.
149
+
150
+ ## Development
151
+
152
+ ```bash
153
+ uv venv .venv && uv pip install --python .venv/bin/python -e '.[dev]'
154
+ .venv/bin/pytest
155
+ .venv/bin/python scripts/demo.py account # any command on synthetic data; no network or cookies
156
+ ```
157
+
158
+ ## License
159
+
160
+ MIT © 2026 Amol Venkataraman. Provided WITHOUT ANY WARRANTY — see [LICENSE](https://github.com/amolvenkataraman/uwquest/blob/main/LICENSE)
161
+ and [DISCLAIMER.md](https://github.com/amolvenkataraman/uwquest/blob/main/DISCLAIMER.md). Not affiliated with or endorsed by the
162
+ University of Waterloo or Oracle. "Quest" and "PeopleSoft" are used only to
163
+ describe compatibility.
@@ -0,0 +1,64 @@
1
+ [project]
2
+ name = "uwquest"
3
+ dynamic = ["version"]
4
+ description = "Read-first CLI and Python client for UWaterloo Quest (PeopleSoft) student self-service"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Amol Venkataraman" }]
9
+ requires-python = ">=3.11"
10
+ dependencies = [
11
+ "requests>=2.31",
12
+ "selectolax>=0.3.21",
13
+ ]
14
+ keywords = ["uwaterloo", "quest", "peoplesoft", "student", "cli", "unofficial"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Environment :: Console",
18
+ "Intended Audience :: End Users/Desktop",
19
+ "Natural Language :: English",
20
+ "Operating System :: OS Independent",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Topic :: Education",
27
+ "Topic :: Utilities",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ browser = ["browser-cookie3>=0.19"] # read the live session straight from the browser
32
+ tui = ["textual>=0.60", "rich>=13"] # the terminal UI
33
+ dev = ["pytest>=8", "pytest-asyncio>=0.23"]
34
+
35
+ [project.scripts]
36
+ quest = "quest.cli:main"
37
+
38
+ [project.urls]
39
+ Homepage = "https://github.com/amolvenkataraman/uwquest"
40
+ Repository = "https://github.com/amolvenkataraman/uwquest"
41
+ Issues = "https://github.com/amolvenkataraman/uwquest/issues"
42
+
43
+ [build-system]
44
+ requires = ["hatchling>=1.27"]
45
+ build-backend = "hatchling.build"
46
+
47
+ [tool.hatch.version]
48
+ path = "src/quest/__init__.py"
49
+
50
+ [tool.hatch.build.targets.sdist]
51
+ exclude = ["docs/media", ".github"]
52
+
53
+ [tool.hatch.build.targets.wheel]
54
+ packages = ["src/quest"]
55
+
56
+ [tool.ruff]
57
+ line-length = 100
58
+
59
+ [tool.ruff.lint]
60
+ select = ["E", "F", "B", "BLE", "I", "UP", "RUF"]
61
+
62
+ [tool.pytest.ini_options]
63
+ testpaths = ["tests"]
64
+ asyncio_mode = "auto"