CodeGrade API#

This library makes it easier to use the CodeGrade API. Its API allows you to automate your usage of CodeGrade. We are currently still busy documenting the entire API, but everything that is possible in the UI of CodeGrade is also possible through the API.

The packages is made of three main elements: an AuthenticatedClient, i.e. the authenticated entry-point used to query the server for information, the Services, which expose the API to query the server and get, patch, remove, etc.. the data, and Models, which are the representations of the data received and sent to the server.

Alongside these elements, we provide documentation for some utils which make working with these elements easier, and Maybe, a class used to represent data that is not guaranteed to be present in the models as it is optional data.

Installation#

You can install the library through pypi, simply run python3 -m pip install codegrade. If you want to get a dev version with support for the latest features, simply email support@codegrade.com and we’ll provide you with a dev version.

Where to start#

The CodeGrade API relies entirely on accessing information through an authenticated client, which can be easily obtained with one of the following methods:

login(username, password, tenant=None, host='https://app.codegra.de')#

Get an AuthenticatedClient by logging in with your username and password.

with codegrade.login(
    username='my-username',
    password=os.getenv('CG_PASS'),
    tenant='My University',
) as client:
    print('Hi I am {}'.format(client.user.get().name)
Parameters:

  • username (str) – Your CodeGrade username.

  • password (str) – Your CodeGrade password, if you do not know your password you can set it by following these steps.

  • tenant (Optional[str]) – The id or name of your tenant in CodeGrade. This is the name you click on the login screen.

  • host (str) – The CodeGrade instance you want to use.

Returns:

A client that you can use to do authenticated requests to CodeGrade. We advise you to use it in combination with a with block (i.e. as a contextmanager) for the highest efficiency.

Return type:

AuthenticatedClient

login_from_cli()#

Get an AuthenticatedClient by logging in through command line interface.

>>> import codegrade
>>> codegrade.login_from_cli()
Your instance [default: https://app.codegra.de]: https://app.codegra.de
[ 1] CodeGrade Sandbox
[ 2] Academy of Interactive Entertainment
...
Select your tenant: 1
Selecting CodeGrade Sandbox
Your username: my-username
Your password:
<codegrade.client.AuthenticatedClient object at 0x106f139a0>
Returns:

A client that you can use to do authenticated requests to CodeGrade. We advise you to use it in combination with a with block (i.e. as a contextmanager) for the highest efficiency.

Return type:

AuthenticatedClient

These are just aliases for AuthenticatedClient’s methods. We suggest to take a look at its documentation for further usage of the API.

Examples#

Following are some basic examples of the API. For more specific and advanced examples refer to these:

Note

The following examples assume you know the ID of the objects you want to query. Please, refer to the aforementioned examples for how you could get the same information without knowing the IDs beforehand.

Get a course#

with codegrade.login_from_cli() as client:
   course = client.course.get(course_id)

Get all assignments in a course#

with codegrade.login_from_cli() as client:
   assignemnts = client.course.get(course_id).assignments

Get all users in a course#

with codegrade.login_from_cli() as client:
   users = client.course.get_all_users(course_id)

Get all submissions in an assignment#

with codegrade.login_from_cli() as client:
   submissions = client.assignment.get_all_submissions(assignment_id)

Backwards compatibility#

CodeGrade is constantly upgrading its API, but we try to minimize backwards incompatible changes. We’ll announce every backwards incompatible change in the changelog. A new version of the API client is released with every release of CodeGrade, which is approximately every month. To upgrade simply run pip install --upgrade codegrade.

Supported python versions#

We support python 3.6 and above, pypy is currently not tested but should work just fine.

License#

The library is licensed under AGPL-3.0-only or BSD-3-Clause-Clear.