Getting Started

Before we are getting started, there are a few things to know about WebUntis and its API:

Note

  • You need an account for the API. You can’t access the API anonymously. It’s designated that schools give each student a user account for the WebUntis server they’re using. Many schools just make the timetable world-accessible though, preventing any use of the API. If you happen to be at such a school, you’re a pitiful bastard.
  • The API is read-only. And there’s nothing you can do about it.
  • The API documentation does not explain the purpose of some methods. So i can’t do a much better job at it.
  • Different schools, different rules. It is not neccessary that schools enter information about, for example, a teacher, in the correct format. It might happen that a school abuses the name field of a teacher to just write the teacher’s initials in it. Testing is the only sane way out of this.
  • All dates and times are in local time. WebUntis’ JSON API returns time and date in local time, the timezones are configurable by the school. As if that wasn’t ridiculous enough, there is no information on the timezone provided as part of the API. So this library can’t make real efforts to handle date and time in a more professional manner.

Initially i started writing this library with the goal to abstract away all the pain that otherwise would result in direct interaction with the API. This is still an unreached goal. Some things like the problem with time and date is unsolvable. So if you think some part of the library could be easier to use, please let me know! I don’t want python-webuntis to become as inconsistent and weird as the API it is wrapping.

Okay, let’s install the webuntis package:

pip install webuntis

Here’s the example from the Intro again:

import webuntis

s = webuntis.Session(
    server='webuntis.grupet.at:8080',
    username='api',
    password='api',
    school='demo_inf',
    useragent='WebUntis Test'
)

s.login()

for klasse in s.klassen():
    print(klasse.name)

s.logout()

So what does this do?

# a minimal example, these parameters are absolutely neccessary
s = webuntis.Session(
    server='webuntis.grupet.at:8080',
    username='api',
    password='api',
    school='demo_inf',
    useragent='WebUntis Test'
)

webuntis.Session represents a new session on a WebUntis server, which is bound to a school. This means that you will have to create a new session if you want to read data from a different school, even if it’s on the same server.

But passing the credentials in doesn’t mean a session is started immediately. You have to do it manually:

s.login()

This will raise an exception if you haven’t provided the neccessary configuration (i.e. username, password, server, useragent, school).

So now that we’re logged in, we can fetch some data. How about a list of all the classes of the school demo_inf? As the WebUntis software comes from Austria, these are called “klassen”, which is German and means “classes”. This name was probably choosen so there’s no confusion between the classes of object-oriented programming languages and the classes that are actually important now.

Anyway, python-webuntis won’t break that tradition:

for klasse in s.klassen():
    print(klasse.name)

We get a list-like, iterable object when calling webuntis.Session.klassen(), a webuntis.objects.KlassenList to be precise. This KlassenList contains multiple instances of webuntis.objects.KlassenObject. An instance of this object has multiple attributes, one of them being name.

At last, you get logged out with this:

s.logout()

You should always log out after doing your job, just like you should close a file after being done with it. For such reasons, Python has the with-statement, which you also can use to log yourself out automatically:

with webuntis.Session(...).login() as s:
    # work goes here

# now you're logged out, even if your code halted with exceptions before.

Where to go from here?

Session describes the Session class, which is the only class you will ever directly get in touch with.