unitoolkit 0.7.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,86 @@
1
+ """SharePoint share links -> real file bytes, through the logged-in agent browser.
2
+
3
+ SHH publishes kursplaner, litteraturlistor and the utbildningsplan as tenant-restricted
4
+ share links (`https://<tenant>.sharepoint.com/:b:/s/<site>/<docid>?e=...`). A plain GET
5
+ returns the viewer or a login page. `download.aspx?share=<docid>`, fetched from inside
6
+ the site's own origin with the user's cookies, returns the file itself.
7
+
8
+ Walking document libraries over REST is not offered: SHH answers AccessDenied for
9
+ students on folder endpoints, so share links are the supported route.
10
+ """
11
+ import pathlib
12
+ import re
13
+
14
+ from . import browser
15
+
16
+ SHARE_RE = re.compile(r"https://([^/]+)/:([a-z]):/[sr]/([^/]+)/([^?]+)")
17
+
18
+
19
+ def share_to_download(share):
20
+ """Return (download_url, origin) for a share link, or (None, None)."""
21
+ m = SHARE_RE.match(share)
22
+ if not m:
23
+ return None, None
24
+ host, _kind, site, docid = m.groups()
25
+ origin = f"https://{host}/sites/{site}/"
26
+ return f"{origin}_layouts/15/download.aspx?share={docid}", origin
27
+
28
+
29
+ def sniff(b):
30
+ """Classify bytes. A UTF-8 BOM precedes the '<' of an HTML page, so check past it."""
31
+ if b[:4] == b"%PDF":
32
+ return "pdf"
33
+ if b[:2] == b"PK":
34
+ return "docx" # docx/pptx/xlsx; real extension comes from Content-Disposition
35
+ head = b.lstrip(b"\xef\xbb\xbf").lstrip()
36
+ if head[:1] == b"<":
37
+ return "html"
38
+ return "bin"
39
+
40
+
41
+ def name_from_cd(cd):
42
+ """Filename out of Content-Disposition, preferring filename* (RFC 5987)."""
43
+ if not cd:
44
+ return None
45
+ m = re.search(r"filename\*=utf-8''([^;]+)", cd, re.I)
46
+ if m:
47
+ import urllib.parse
48
+ return urllib.parse.unquote(m.group(1))
49
+ m = re.search(r'filename="?([^";]+)"?', cd, re.I)
50
+ return m.group(1) if m else None
51
+
52
+
53
+ def fetch_share(share):
54
+ """Return (bytes, kind, suggested_name) or (None, None, None).
55
+
56
+ The real extension comes from Content-Disposition: a share can point at a PDF, a docx,
57
+ or something like a saved .aspx page, and magic bytes alone cannot tell docx from pptx.
58
+ """
59
+ url, origin = share_to_download(share)
60
+ if not url:
61
+ return None, None, None
62
+ r = browser.fetch_binary(url, origin) or {}
63
+ b = r.get("bytes") or b""
64
+ if r.get("status") != 200 or not b:
65
+ return None, None, None
66
+ kind = sniff(b)
67
+ name = name_from_cd(r.get("cd"))
68
+ if name and "." in name:
69
+ ext = name.rsplit(".", 1)[-1].lower()
70
+ if ext in ("pdf", "docx", "pptx", "xlsx", "txt", "html", "htm", "aspx", "csv"):
71
+ kind = ext
72
+ return b, kind, name
73
+
74
+
75
+ def save_share(share, out):
76
+ """Download a share link to `out` (a file path, or a dir to auto-name in)."""
77
+ b, ext, name = fetch_share(share)
78
+ if not b:
79
+ return {"ok": False, "share": share, "error": "download failed (logged in? link valid?)"}
80
+ out = pathlib.Path(out).expanduser()
81
+ if out.is_dir() or not out.suffix:
82
+ out.mkdir(parents=True, exist_ok=True)
83
+ out = out / (name or f"{SHARE_RE.match(share).group(4)[:24]}.{ext}")
84
+ out.parent.mkdir(parents=True, exist_ok=True)
85
+ out.write_bytes(b)
86
+ return {"ok": True, "path": str(out), "bytes": len(b), "type": ext}
unitoolkit/surface.py ADDED
@@ -0,0 +1,86 @@
1
+ """What a student session can actually extract from Canvas, endpoint by endpoint.
2
+
3
+ This exists because assumptions about Canvas are wrong often enough to be expensive: pages
4
+ may be disabled per course, rubrics are empty unless asked for with include[]=rubric, the
5
+ quizzes endpoint can be off, and students cannot read the rubric collection. Probing first,
6
+ then building, keeps the search index honest about what it can cover.
7
+
8
+ from unitoolkit import surface
9
+ surface.probe_course(2416) # -> list of rows with status, count, bytes
10
+ """
11
+ import json
12
+ import urllib.error
13
+ import urllib.request
14
+
15
+ from . import canvas
16
+
17
+ # (label, path template, note) -- {c} is the course id
18
+ PROBES = [
19
+ ("courses", "courses", "enrolments, term, codes"),
20
+ ("course meta", "courses/{c}", "name, settings"),
21
+ ("course tabs", "courses/{c}/tabs", "which tools the course shows"),
22
+ ("course settings", "courses/{c}/settings", "feature switches"),
23
+ ("features", "courses/{c}/features", "account flags, e.g. smart_search"),
24
+ ("modules", "courses/{c}/modules?include[]=items&include[]=content_details", "the only route to pages"),
25
+ ("pages index", "courses/{c}/pages", "often disabled: 'Sidan har avaktiverats'"),
26
+ ("pages search", "courses/{c}/pages?search_term=kurs", "disabled together with the index"),
27
+ ("assignments", "courses/{c}/assignments?per_page=100", "task text"),
28
+ ("assignments + rubric", "courses/{c}/assignments?include[]=rubric&per_page=100", "rubric rows, needed for criteria"),
29
+ ("rubrics", "courses/{c}/rubrics", "students are refused (403)"),
30
+ ("assignment groups", "courses/{c}/assignment_groups", "weights"),
31
+ ("quizzes", "courses/{c}/quizzes", "may be disabled"),
32
+ ("discussions", "courses/{c}/discussion_topics?per_page=100", "threads"),
33
+ ("announcements", "courses/{c}/discussion_topics?only_announcements=true&per_page=100", "the 'anvisningar' feed"),
34
+ ("files", "courses/{c}/files?per_page=100", "names, sizes, download urls"),
35
+ ("folders", "courses/{c}/folders?per_page=100", "file tree"),
36
+ ("enrollments self", "courses/{c}/enrollments?user_id=self", "own role, section"),
37
+ ("submissions self", "courses/{c}/students/submissions?student_ids[]=self&per_page=100",
38
+ "own grades, submission state, bodies"),
39
+ ("external tools", "courses/{c}/external_tools", "LTI tools in the course"),
40
+ ("course nav LTI", "courses/{c}/external_tools/visible_course_nav_tools", "Kaltura etc."),
41
+ ("planner items", "planner/items?per_page=100", "unified feed: assignments, files, announcements"),
42
+ ("todo", "users/self/todo", "what Canvas thinks is pending"),
43
+ ("upcoming events", "users/self/upcoming_events", "calendar feed"),
44
+ ("profile", "users/self/profile", "self"),
45
+ ("groups", "users/self/groups", "group work and group submissions"),
46
+ ("calendar events", "calendar_events?context_codes[]=course_{c}&type=event", "course events"),
47
+ ]
48
+
49
+
50
+ def _probe(path):
51
+ url = f"{canvas.BASE}/api/v1/{path}"
52
+ req = urllib.request.Request(url, headers={"Authorization": f"Bearer {canvas.token()}"})
53
+ try:
54
+ with urllib.request.urlopen(req, timeout=40) as r:
55
+ raw = r.read()
56
+ status = r.status
57
+ except urllib.error.HTTPError as e:
58
+ return {"status": e.code, "count": None, "bytes": 0,
59
+ "note": e.read()[:80].decode("utf-8", "replace").replace("\n", " ")}
60
+ except Exception as e: # noqa: BLE001 - a probe reports, it does not raise
61
+ return {"status": "ERR", "count": None, "bytes": 0, "note": str(e)[:80]}
62
+ try:
63
+ data = json.loads(raw)
64
+ except Exception: # noqa: BLE001
65
+ return {"status": status, "count": None, "bytes": len(raw), "note": "non-JSON"}
66
+ count = len(data) if isinstance(data, list) else None
67
+ return {"status": status, "count": count, "bytes": len(raw), "note": ""}
68
+
69
+
70
+ def probe_course(course_id):
71
+ """Probe every endpoint a student session might use. Returns one row per endpoint."""
72
+ rows = []
73
+ for label, tpl, note in PROBES:
74
+ path = tpl.format(c=course_id)
75
+ res = _probe(path)
76
+ rows.append({"label": label, "path": path, **res, "why": note})
77
+ return rows
78
+
79
+
80
+ def summary(rows):
81
+ ok = [r for r in rows if r["status"] == 200]
82
+ return {
83
+ "reachable": len(ok),
84
+ "blocked": [f"{r['label']}: {r['status']}" for r in rows if r["status"] != 200],
85
+ "documents": {r["label"]: r["count"] for r in ok if r["count"] is not None},
86
+ }
unitoolkit/timeedit.py ADDED
@@ -0,0 +1,209 @@
1
+ """TimeEdit, the whole timetable rather than one saved link.
2
+
3
+ Two guides matter at SHH (cloud.timeedit.net/shh/web/student/):
4
+ - ri1Q9 "Schema" is public (sid=5). Its object search answers course codes, groups and rooms,
5
+ and `ri.json` with `objects=<id>` returns the bookings of any of them for any period. That is
6
+ every course's schedule without a login.
7
+ - ri1Q3 "Boka salar" (sid=8) sits behind the school SSO. It only tells us WHICH rooms students
8
+ may book; their occupancy is in the public guide like any other room. So the login is needed
9
+ once, to learn the room list, which is then cached.
10
+
11
+ Read-only: nothing here books a room. The booking rules the guide shows (Mon-Fri 08-20, three
12
+ days ahead, one room per student per day, max 4 hours) are applied to `free_rooms`, so the
13
+ answer is "what you could book", not just "what is empty".
14
+
15
+ Gotchas found while building this:
16
+ - The type codes are not the ones the filter boxes on the page carry (11, 19, 20, ...): those are
17
+ room attributes. Objects are 5=Kurs, 21=Kurskod, 6=Grupp, 4=Sal, 8=Ämne, 9=Undervisningsform.
18
+ - A course name search ("Sjuksköterskan...") finds nothing; search the course code (type 21),
19
+ and the student group (type 6, e.g. "H26SK") to see the whole cohort's timetable.
20
+ - The period parameter is `p=<from>,<to>` with dates as YYYYMMDD.x, or relative 0.d / 4.w.
21
+ """
22
+
23
+ import datetime as dt
24
+ import json
25
+ import re
26
+ import urllib.parse
27
+ import urllib.request
28
+ from pathlib import Path
29
+
30
+ BASE = 'https://cloud.timeedit.net/shh/web/student/'
31
+ PUBLIC_SID = 5
32
+ BOOKING_SID = 8
33
+ TYPES = {'course': 5, 'code': 21, 'group': 6, 'room': 4, 'subject': 8, 'form': 9}
34
+ CACHE = Path.home() / '.cache/unitoolkit/timeedit_bookable_rooms.json'
35
+
36
+ # Bookable rooms as read from the logged-in "Boka salar" guide on 2026-11-17. Used when the
37
+ # login is unavailable; refresh with bookable_rooms(refresh=True).
38
+ BOOKABLE_FALLBACK = [
39
+ {'id': '1777', 'name': '100 Lill Jan', 'kind': 'Seminarierum'},
40
+ {'id': '1779', 'name': '101A Lill Jan', 'kind': 'Seminarierum'},
41
+ {'id': '1780', 'name': '101B Lill Jan', 'kind': 'Seminarierum'},
42
+ {'id': '1781', 'name': '102A Lill Jan', 'kind': 'Seminarierum'},
43
+ {'id': '1782', 'name': '102B Lill Jan', 'kind': 'Seminarierum'},
44
+ {'id': '1783', 'name': '103 Lill Jan', 'kind': 'Seminarierum'},
45
+ {'id': '427', 'name': '201 Lill Jan', 'kind': 'Föreläsningssal'},
46
+ {'id': '440', 'name': 'Henderson', 'kind': 'Seminarierum'},
47
+ {'id': '439', 'name': 'Nightingale', 'kind': 'Seminarierum'},
48
+ ]
49
+ BOOKING_RULES = {'weekdays': (0, 1, 2, 3, 4), 'open': '08:00', 'close': '20:00',
50
+ 'days_ahead': 3, 'max_hours': 4}
51
+
52
+ UA = {'User-Agent': 'unitoolkit (https://github.com/vhsgreed/shh-study-kit)'}
53
+
54
+
55
+ def _get(url, timeout=30):
56
+ req = urllib.request.Request(url, headers=UA)
57
+ with urllib.request.urlopen(req, timeout=timeout) as r:
58
+ return r.read().decode('utf-8', 'replace')
59
+
60
+
61
+ def _period(start, end):
62
+ def one(d):
63
+ if isinstance(d, (dt.date, dt.datetime)):
64
+ return d.strftime('%Y%m%d') + '.x'
65
+ s = str(d).strip()
66
+ if re.fullmatch(r'\d{4}-\d{2}-\d{2}', s):
67
+ return s.replace('-', '') + '.x'
68
+ return s # already TimeEdit form (0.d, 4.w, YYYYMMDD.x)
69
+ return '%s,%s' % (one(start), one(end))
70
+
71
+
72
+ def find(query, kind='code', limit=20):
73
+ """Object ids for a course code, group, room, subject or teaching form."""
74
+ t = TYPES.get(kind, kind)
75
+ q = urllib.parse.urlencode({'max': 100, 'fr': 't', 'partajax': 't', 'im': 'f',
76
+ 'sid': PUBLIC_SID, 'l': 'sv_SE', 'search_text': query,
77
+ 'objects': '', 'types': t})
78
+ h = _get(BASE + 'objects.html?' + q)
79
+ import html as _html
80
+ rows = re.findall(r'data-idonly="([^"]+)"[^>]*data-name="([^"]*)"', h) or \
81
+ re.findall(r'data-id="([^"]+)"[^>]*data-name="([^"]*)"', h)
82
+ out, seen = [], set()
83
+ for oid, name in rows:
84
+ if oid.startswith('-') or oid in seen:
85
+ continue
86
+ seen.add(oid)
87
+ out.append({'id': oid.split('.')[0], 'name': _html.unescape(name).strip(), 'kind': kind})
88
+ return out[:limit]
89
+
90
+
91
+ def bookings(object_ids, start: object = '0.d', end: object = '14.d'):
92
+ """Every booking of the given objects between start and end, as plain rows."""
93
+ ids = ','.join(str(i).split('.')[0] for i in (object_ids if isinstance(object_ids, (list, tuple)) else [object_ids]))
94
+ if not ids:
95
+ return []
96
+ q = 'h=t&sid=%d&p=%s&objects=%s&ox=0&types=0&fe=0' % (
97
+ PUBLIC_SID, urllib.parse.quote(_period(start, end), safe=',.'), ids)
98
+ d = json.loads(_get(BASE + 'ri.json?' + q))
99
+ head = [h or 'col%d' % i for i, h in enumerate(d.get('columnheaders') or [])]
100
+ names = {'Kurs/Grupp': 'group', 'Undervisningsform': 'form', 'Ämne': 'subject',
101
+ 'Sal': 'room', 'Lärare, Personal, Person': 'teacher', 'Information': 'info'}
102
+ out = []
103
+ for r in d.get('reservations') or []:
104
+ row = {'date': r['startdate'], 'start': r['starttime'], 'end': r['endtime']}
105
+ for i, v in enumerate(r.get('columns') or []):
106
+ key = names.get(head[i], head[i]) if i < len(head) else 'col%d' % i
107
+ row[key] = v
108
+ out.append(row)
109
+ return sorted(out, key=lambda x: (x['date'], x['start']))
110
+
111
+
112
+ def schedule(query, kind='code', start='0.d', end='14.d'):
113
+ """'When is PRY?' in one call: resolve the code (or group, room) and list its bookings."""
114
+ hits = find(query, kind)
115
+ if not hits:
116
+ hint = (' Search the course code (e.g. 1SPRY2) or the group (e.g. H26SK); course names '
117
+ 'are not indexed.' if kind in ('code', 'course') else '')
118
+ raise LookupError('TimeEdit has no %s matching %r.%s' % (kind, query, hint))
119
+ exact = [h for h in hits if h['name'].lower() == query.lower()]
120
+ picked = exact or hits[:1] if kind != 'group' else (exact or hits)
121
+ rows = bookings([h['id'] for h in picked], start, end)
122
+ return {'query': query, 'kind': kind, 'objects': picked, 'period': _period(start, end),
123
+ 'bookings': rows, 'count': len(rows)}
124
+
125
+
126
+ def bookable_rooms(refresh=False):
127
+ """Rooms students may book. Needs the school SSO once (agent browser), then cached."""
128
+ if not refresh and CACHE.exists():
129
+ try:
130
+ return json.loads(CACHE.read_text())
131
+ except Exception:
132
+ pass
133
+ if not refresh:
134
+ return BOOKABLE_FALLBACK
135
+ import asyncio
136
+ from .databases import _Tab
137
+ with _Tab(BASE + 'ri1Q3.html') as page:
138
+ for _ in range(8):
139
+ page._run(asyncio.sleep(3))
140
+ url = page.eval('location.href') or ''
141
+ if 'ri1Q3' in url:
142
+ break
143
+ page.eval("""(() => { const b = [...document.querySelectorAll('a,button')]
144
+ .find(e => /SHH-konto/i.test(e.innerText)); if (b) b.click(); })()""")
145
+ if 'ri1Q3' not in (page.eval('location.href') or ''):
146
+ raise RuntimeError('TimeEdit room booking needs the school sign-in: open %sri1Q3.html '
147
+ 'in the agent browser and choose "Sign in with SHH-konto"' % BASE)
148
+ raw = page.eval("""(async () => JSON.stringify(await (await fetch('objects.json?max=50&fr=f'
149
+ + '&part=t&partajax=t&im=f&step=1&sid=%d&l=sv_SE&ohg=0&types=4&subtypes=4',
150
+ {credentials: 'include'})).json()))()""" % BOOKING_SID)
151
+ rooms = []
152
+ for o in json.loads(raw or '{}').get('objects') or []:
153
+ f = o.get('fields') or {}
154
+ rooms.append({'id': str(o['id']), 'name': (f.get('Namn') or '').strip(),
155
+ 'kind': (f.get('Salstyp') or '').strip()})
156
+ if rooms:
157
+ CACHE.parent.mkdir(parents=True, exist_ok=True)
158
+ CACHE.write_text(json.dumps(rooms, ensure_ascii=False, indent=1))
159
+ return rooms
160
+
161
+
162
+ def _mins(hhmm):
163
+ h, m = hhmm.split(':')
164
+ return int(h) * 60 + int(m)
165
+
166
+
167
+ def _hhmm(mins):
168
+ return '%02d:%02d' % (mins // 60, mins % 60)
169
+
170
+
171
+ def free_rooms(date=None, min_minutes=60, rooms=None, today=None):
172
+ """Free slots in the bookable rooms on one day, within the booking rules.
173
+
174
+ Returns, per room, the gaps between bookings inside opening hours that are at least
175
+ `min_minutes` long, each capped to the 4-hour booking limit. A date outside the bookable
176
+ window still gets an answer, flagged `bookable: false`, because "is it free?" and "can I
177
+ book it yet?" are different questions.
178
+ """
179
+ today = today or dt.date.today()
180
+ day = dt.date.fromisoformat(date) if date else today
181
+ rooms = rooms or bookable_rooms()
182
+ rules = BOOKING_RULES
183
+ lo, hi = _mins(rules['open']), _mins(rules['close'])
184
+ bookable = day.weekday() in rules['weekdays'] and 0 <= (day - today).days <= rules['days_ahead']
185
+ out = []
186
+ for room in rooms:
187
+ # One request per room: a combined query returns some bookings with an empty room
188
+ # column, and those cannot be attributed to a room (they matched every room before).
189
+ busy = sorted((_mins(r['start']), _mins(r['end']))
190
+ for r in bookings([room['id']], day.isoformat(), day.isoformat())
191
+ if r['date'] == day.isoformat())
192
+ gaps, cursor = [], lo
193
+ for st, en in busy:
194
+ if st > cursor:
195
+ gaps.append((cursor, min(st, hi)))
196
+ cursor = max(cursor, en)
197
+ if cursor < hi:
198
+ gaps.append((cursor, hi))
199
+ slots = [{'from': _hhmm(a), 'to': _hhmm(b), 'minutes': b - a,
200
+ 'bookable_until': _hhmm(min(b, a + rules['max_hours'] * 60))}
201
+ for a, b in gaps if b - a >= min_minutes]
202
+ out.append({'room': room['name'], 'kind': room.get('kind', ''), 'free': slots,
203
+ 'busy': [{'from': _hhmm(a), 'to': _hhmm(b)} for a, b in busy]})
204
+ out.sort(key=lambda r: -sum(s['minutes'] for s in r['free']))
205
+ return {'date': day.isoformat(), 'bookable': bookable,
206
+ 'rules': 'Mon-Fri 08-20, up to %d days ahead, one room per student per day, max %d h; '
207
+ 'book in TimeEdit (Boka salar), this tool only reads.' % (
208
+ rules['days_ahead'], rules['max_hours']),
209
+ 'rooms': out}