Session¶
The Session Class¶
- class webuntis.Session(**config)¶
The origin of everything you want to do with the WebUntis API. Can be used as a context-manager to provide automatic log-out.
Configuration can be set with keyword arguments when initializing
Session
. Unless noted otherwise, they get saved in a dictionary located in the instance’sconfig
attribute and can be modified afterwards.- Parameters:
username (str) – The username used for the API.
password (str) – The password used for the API.
server (str) –
A host name, a URL, or a URL without path.
s = webuntis.Session(..., server='thalia.webuntis.com') # 'https://thalia.webuntis.com/WebUntis/jsonrpc.do' # Want to disable SSL? # make sure there's NO SLASH at the end! s.config['server'] = 'http://thalia.webuntis.com' # 'http://thalia.webuntis.com/WebUntis/jsonrpc.do' # or maybe use a completely different API endpoint? s.config['server'] = 'http://thalia.webuntis.com/WebUntis/jsonrpc2.do' # 'http://thalia.webuntis.com/WebUntis/jsonrpc2.do' # or just change the path? s.config['server'] = 'thalia.webuntis.com/WebUntis/jsonrpc2.do' # 'https://thalia.webuntis.com/WebUntis/jsonrpc2.do' s.config['server'] = '!"$%/WebUntis/jsonrpc.do' # ValueError: Not a valid hostname
school (str) – A valid school name.
useragent (str) – A string containing a useragent. Please include useful information, such as an email address, for the server maintainer. Just like you would do with the HTTP useragents of bots.
cachelen (int) –
The maximum size of the internal cache. All results are saved in it, but they only get used if you set the
from_cache
parameter on a session method toTrue
. This parameter is not saved in the configuration dictionary.s.timetable(klasse=123) # saves in cache s.timetable(klasse=123) # fetch data again, override old value s.timetable(klasse=123, from_cache=True) # get directly from cache
The reason this cache was added is that the API only allows you to fetch a whole list of objects (teachers/schoolclasses/…), not single ones. It would seriously harm performance to fetch the whole list each time we want information about a single object. Without the cache, i sometimes experienced a performance decrease about twenty seconds, so i wouldn’t set the
cachelen
to anything smaller than5
.Default value is
20
.You can clear the cache using:
s.cache.clear('timetable') # clears all cached timetables s.cache.clear() # clears everything from the cache
jsessionid (str) – The session key to use. You usually shouldn’t touch this.
login_repeat (int) – The amount of times python-webuntis should try to login when finding no or an expired session. Default to
0
, meaning it won’t do that.use_cache (bool) – always use the cache
- login()¶
Initializes an authentication, provided we have the credentials for it.
- Returns:
The session. This is useful for jQuery-like command chaining:
s = webuntis.Session(...).login()
- Raises:
webuntis.errors.BadCredentialsError
– Username/Password missing or invalid.- Raises:
webuntis.errors.AuthError
– Didn’t receive a session ID for unknown reasons.
- logout(suppress_errors=False)¶
Log out of session
- Parameters:
suppress_errors (bool) – Whether to suppress errors.
- Raises:
webuntis.errors.NotLoggedInError
– Can’t log out because not logged in. Raised unlesssuppress_errors
isTrue
.
- config = None¶
The config dictionary, filled with most keyword arguments from initialization.
- cache = None¶
Contains the caching dictionary for requests.
Things you can do with the API¶
- class webuntis.Session
- departments()¶
Get all departments.
- Return type:
- holidays()¶
Get all holidays.
- Return type:
- klassen(schoolyear=None)¶
Get all school classes.
- Parameters:
schoolyear (
webuntis.objects.SchoolyearObject
or an integer ID of it) – The schoolyear where the classes should be fetched from.- Return type:
- timetable(start, end, **type_and_id)¶
Get the timetable for a specific school class and time period.
- Parameters:
start (
datetime.datetime
ordatetime.date
or int) – The beginning of the time period.end (
datetime.datetime
ordatetime.date
or int) – The end of the time period.
- Return type:
Furthermore you have to explicitly define a klasse, teacher, subject, room or student parameter containing the id or the object of the thing you want to get a timetable about:
import datetime today = datetime.date.today() monday = today - datetime.timedelta(days=today.weekday()) friday = monday + datetime.timedelta(days=4) klasse = s.klassen().filter(id=1)[0] # schoolclass #1 tt = s.timetable(klasse=klasse, start=monday, end=friday)
- Raises:
- timetable_extended(start, end, **type_and_id)¶
Get the timetable for a specific school class and time period.
Like timetable, but includes more info.
- my_timetable(end, start)¶
Get the timetable for the logged-in user.
see timetable_extended.
- rooms()¶
Get all rooms of a school.
- Return type:
- schoolyears()¶
Get all schoolyears.
- Return type:
- subjects()¶
Get all subjects.
- Return type:
- teachers()¶
Get all teachers.
- Return type:
- statusdata()¶
Information about lesson types and period codes, specifically about the colors used to highlight them in the web-interface of WebUntis.
- Return type:
- last_import_time()¶
Information about the last change made.
- Return type:
py:class:webuntis.objects.TimeStampObject
- substitutions(start, end, department_id=0)¶
Get all substitutions.
- Parameters:
start (
datetime.datetime
ordatetime.date
or int) – The beginning of the time period.end (
datetime.datetime
ordatetime.date
or int) – The end of the time period.department_id – int, set to 0 for all departments or if not applicable
- Return type:
- timegrid_units()¶
Information about the Timegrid.
- Returns:
- Return type:
- students()¶
Get all students
- Return type:
- exam_types()¶
Information about the Exam types. needs additional rights Master/Exam Types – Stammdaten /Pruefungsart
- Return type:
- exams(start, end, exam_type_id=0)¶
Information about the Exams.
- Parameters:
start (
datetime.datetime
ordatetime.date
or int) – The beginning of the time period.end (
datetime.datetime
ordatetime.date
or int) – The end of the time period.exam_type_id – int - id of Exam, @TODO: allow examtype id/name
- Return type:
- timetable_with_absences(start, end)¶
Information about the Exams.
- Parameters:
start (
datetime.datetime
ordatetime.date
or int) – The beginning of the time period.end (
datetime.datetime
ordatetime.date
or int) – The end of the time period.
- Return type:
- class_reg_events(start, end)¶
Information about the ClassRegEvents :type start:
datetime.datetime
ordatetime.date
or int :param start: The beginning of the time period.- Parameters:
end (
datetime.datetime
ordatetime.date
or int) – The end of the time period.- Return type: