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.
- uwquest-0.1.0/.gitignore +10 -0
- uwquest-0.1.0/DISCLAIMER.md +45 -0
- uwquest-0.1.0/LICENSE +21 -0
- uwquest-0.1.0/PKG-INFO +199 -0
- uwquest-0.1.0/README.md +163 -0
- uwquest-0.1.0/pyproject.toml +64 -0
- uwquest-0.1.0/scripts/demo.py +183 -0
- uwquest-0.1.0/src/quest/__init__.py +34 -0
- uwquest-0.1.0/src/quest/cli.py +237 -0
- uwquest-0.1.0/src/quest/core/__init__.py +2 -0
- uwquest-0.1.0/src/quest/core/models.py +113 -0
- uwquest-0.1.0/src/quest/core/parsers.py +136 -0
- uwquest-0.1.0/src/quest/core/session.py +275 -0
- uwquest-0.1.0/src/quest/errors.py +39 -0
- uwquest-0.1.0/src/quest/readers/__init__.py +32 -0
- uwquest-0.1.0/src/quest/readers/academic_requirements.py +36 -0
- uwquest-0.1.0/src/quest/readers/account.py +25 -0
- uwquest-0.1.0/src/quest/readers/course_availability.py +160 -0
- uwquest-0.1.0/src/quest/readers/dashboard.py +29 -0
- uwquest-0.1.0/src/quest/readers/enrollment_dates.py +15 -0
- uwquest-0.1.0/src/quest/readers/financial_aid.py +19 -0
- uwquest-0.1.0/src/quest/readers/grades.py +43 -0
- uwquest-0.1.0/src/quest/readers/holds.py +28 -0
- uwquest-0.1.0/src/quest/readers/milestones.py +20 -0
- uwquest-0.1.0/src/quest/readers/program.py +19 -0
- uwquest-0.1.0/src/quest/readers/schedule.py +79 -0
- uwquest-0.1.0/src/quest/readers/transcript.py +43 -0
- uwquest-0.1.0/src/quest/tui/__init__.py +7 -0
- uwquest-0.1.0/src/quest/tui/app.py +249 -0
- uwquest-0.1.0/tests/test_cli.py +86 -0
- uwquest-0.1.0/tests/test_parsers.py +44 -0
- uwquest-0.1.0/tests/test_session.py +109 -0
- uwquest-0.1.0/tests/test_tui.py +45 -0
uwquest-0.1.0/.gitignore
ADDED
|
@@ -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
|
+

|
|
43
|
+
[](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
|
+

|
|
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.
|
uwquest-0.1.0/README.md
ADDED
|
@@ -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
|
+

|
|
7
|
+
[](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
|
+

|
|
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"
|