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’s config 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 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.

  • 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 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
departments()

Get all departments.

Return type:

webuntis.objects.DepartmentList

holidays()

Get all holidays.

Return type:

webuntis.objects.HolidayList

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:

webuntis.objects.KlassenList

timetable(start, end, **type_and_id)

Get the timetable for a specific school class and time period.

Parameters:
Return type:

webuntis.objects.PeriodList

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:

ValueError, TypeError

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:

webuntis.objects.RoomList

schoolyears()

Get all schoolyears.

Return type:

webuntis.objects.SchoolyearList

subjects()

Get all subjects.

Return type:

webuntis.objects.SubjectList

teachers()

Get all teachers.

Return type:

webuntis.objects.TeacherList

statusdata()

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

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:
Return type:

webuntis.objects.SubstitutionList

timegrid_units()

Information about the Timegrid.

Returns:

Return type:

webuntis.objects.TimegridObject

students()

Get all students

Return type:

webuntis.objects.StudentsList

exam_types()

Information about the Exam types. needs additional rights Master/Exam Types – Stammdaten /Pruefungsart

Return type:

webuntis.objects.ExamTypeList

exams(start, end, exam_type_id=0)

Information about the Exams.

Parameters:
Return type:

webuntis.objects.ExamsList

timetable_with_absences(start, end)

Information about the Exams.

Parameters:
Return type:

webuntis.objects.AbsencesList

class_reg_events(start, end)

Information about the ClassRegEvents :type start: datetime.datetime or datetime.date or int :param start: The beginning of the time period.

Parameters:

end (datetime.datetime or datetime.date or int) – The end of the time period.

Return type:

webuntis.objects.ClassRegEventList