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’s config attribute and can be modified afterwards.

  • 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='')
    # ''
    # Want to disable SSL?
    # make sure there's NO SLASH at the end!
    s.config['server'] = ''
    # ''
    # or maybe use a completely different API endpoint?
    s.config['server'] = ''
    # ''
    # or just change the path?
    s.config['server'] = ''
    # ''
    s.config['server'] = '!"$%/WebUntis/'
    # 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 to True. 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 than 5.

    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.

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 recieve a session ID for unknown reasons.

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 unless suppress_errors is True.
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

Get all departments.

Return type:webuntis.objects.DepartmentList

Get all holidays.

Return type:webuntis.objects.HolidayList

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:webuntis.objects.KlassenList

Get the timetable for a specific school class and 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 =
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:ValueError, TypeError

Get all rooms of a school.

Return type:webuntis.objects.RoomList

Get all schoolyears.

Return type:webuntis.objects.SchoolyearList

Information about lesson types and period codes, specifically about the colors used to highlight them in the web-interface of WebUntis.

Return type:webuntis.objects.StatusData

Get all subjects.

Return type:webuntis.objects.SubjectList

Get all teachers.

Return type:webuntis.objects.TeacherList