Extending

Extending virtual-classroom

Sometimes you may find that virtual-classroom can't do what you want. This page aims to give insight into how one should go about implementing your desired functionality. To this end the following sections will go through how virtual-classroom works, and how to work with it in your own scripts.

The main components

Classroom

The classroom.Classroom class defines access to the main functionality of virtual-classroom. If you run

from virtual_classroom.classroom import Classroom
classroom = Classroom("students_base.txt")

the classroom will automatically be built from the students_base.txt file in your working directory. This means that every student marked with an "X" under "Attendance" will be given a private repository in the organization (if they don't have one already), and information about them will be setup and stored in student.Student class instances. The students are stored in the Classroom.students instance attribute as a dictionary with their Github usernames as keys.

Now if you need to do manipulations to a single or multiple Student instances, you can access them through:

for student in classroom.students.values():
    print("Student {} is present.".format(student.name))

For more information about what you can do with each Student instance, have a look at the Student section below, or take a peek into the student.py file.

If you have started a peer review during your current session the Classroom.review_groups attribute will be a list of group.ReviewGroup instances. If you currently have ongoing peer review groups, it is also possible to fetch them using Classroom.fetch_peer_review, but have a look at classroom.py for limitations and documentation of the different methods.

API

Sometimes you may want to do more advanced things than manipulating data that virtual-classroom already fetches. Say you want to do some Github API call, maybe download a file or check if it exists, then you need to resort to api.py. Here you will find the two classes Endpoint and APIManager which together define the layer that communicates with the Github API.

To start off you might want to figure out what endpoint you need to use by checking the Github API Developer Guide.

The Endpoint class defines all the Github API URLs used by virtual-classroom. It is easy to extend by adding a new EndpointItem. The recommended way to define a new EndpointItem is to use two arguments, the first being the base url preferably using one of the previous EndpointItem instances, and a second argument as a string to append to the base url. If the url takes parameters you can define them with {} which will then be replaced by positional arguments when calling EndpointItem.url. As a simple example

API_URL = EndpointItem("https://api.github.com")
USERS_API = EndpointItem(API_URL, "/users/{}")
NEW_API = EndpointItem(USERS_API, "/foo/{}/{}/bar")

Then calling Endpoint.NEW_API.url("me", "param2", 123).url() will return

https://api.github.com/users/me/foo/param2/123/bar

Now that you have added an endpoint you have to find a way to use it. This is where APIManager comes in. The simplest way to add the endpoint to APIManager is to define a new method that calls either get, post, put or delete from the requests package and returns the result. If the Github endpoint uses pagination then you can use APIManager._get to get all pages in one method call. Note that APIManager._get returns a json object (dict) while get returns a requests.Response object.

An example for implementing the above new endpoint:

def get_new_api(self, user, foo, foo2):
    return get(Endpoint.REPOSITORY.url(user, foo, foo2), auth=self.auth)

Student

The student.Student class holds information about an individual student. The constructor is responsible for setting up the private repository and possibly fetch some data from Github to populate certain attributes. There is much room for gathering more information and implementing more functionality in this class.

Students file

In students_file.py you will find the code responsible for parsing and writing to the students file. If you want to extend the students file to contain more information, you can have a look at the list students_file_columns. The entries in the list is the key names in the resulting array, and the ordering of the list decides the placement in the students file.