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