Technical info

The Vulcan API is asynchronous (using asyncio) and works using coroutines. All the code presented in this documentation needs to be placed inside a coroutine block (except imports, obviously).

A sample coroutine block looks as follows:

import asyncio

async def main():
    # asynchronous code goes here

if __name__ == "__main__":
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

Data fetching

All data getting methods are asynchronous.

There are three return types of those methods:

• object - applies to methods returning a single object (e.g. the currently selected student, the today’s lucky number, the server date-time)

• list - applies to get_students(). The list is either read from the server or the in-memory cache.

• AsyncIterator - applies to all other data fetching methods. The returned iterator may be used like this:

  grades = await client.data.get_grades()
  
  # with a for loop
  async for grade in grades:
      print(grade)
  
  # convert to a list
  grades = [grade async for grade in grades]
  print(grades[0])
  for grade in grades:
      print(grade)
  

Note

You cannot re-use the AsyncIterator (once iterated through). As it is asynchronous, you also cannot use the next() method on it.

Sessions

As all HTTP requests are also async, the API uses aiohttp’s sessions, which need to be opened and closed when needed.

Upon creation, the Vulcan object creates a session, which needs to be closed before the program terminates.

client = Vulcan(keystore, account)
# use the client here
await client.close()

It is also possible to use a context manager to handle session opening and closing automatically.

client = Vulcan(keystore, account)
async with client:
    # use the client here

Warning

Be aware that every with block creates and closes a new session. As per the aiohttp docs, it is recommended to group multiple requests to use with a single session, so it’s best not to use a separate with block for every single request.