API documentation

Classification: The main part

class classification.classification.Classification(client_id: str, client_secret: str, callback_host: str = 'localhost', callback_port: int = 8080, force_new_token: bool = False, session: requests_oauthlib.oauth2_session.OAuth2Session = None)

The main class for working with Classification API.

This class has a method for every URL listed in API documentation of Classification portal. It also manages acquiring and refreshing of the access token.

See also

ClassificationParamsProxy is a proxy for this class that takes care of saving some frequently used parameters.

Note

In order to use this class, you will need to get a client ID and Secret codes. You will receive them once you register a new application in the AppsManager. Create a new web application there. As the callback URL, please put the URL of your local server to catch the authorization callback (it is localhost:8080 by default).

AUTHORIZE_URL

str – Used to build a login URL to be opened in browser.

TOKEN_URL

str – This endpoint is used to ask the server to give and refresh the access token.

API_URL

str – The base part of the API URL (used in every method/API call).

session

requests_oauthlib.OAuth2Session – This session is used to acquire/refresh token and to make API calls. Can be passed through the constructor, but it was made possible for the purpose of testing; do not pass it in for the regular usage.

client_id

str – A special ID you get when you register your application in the AppsManager.

client_secret

str – A special secret code you get when you register your application in the AppsManager.

__init__(client_id: str, client_secret: str, callback_host: str = 'localhost', callback_port: int = 8080, force_new_token: bool = False, session: requests_oauthlib.oauth2_session.OAuth2Session = None)

Creates a new instance of the library with a new session.

Initially needed to create a new session, client ID and Secret values are stored inside to refresh expired access token later.

Parameters:
  • client_id – A special ID you get when you register your application in the AppsManager.
  • client_secret – A special secret code you get when you register your application in the AppsManager.
  • callback_host – The host which should receive the authorization callback. Used to temporarily create a web server in this app to get callback with authorization code. Defaults to ‘localhost’.
  • callback_port – The port used together with the host described above. Defaults to 8080.
  • force_new_token – If True, the login process will be initiated again, even if we have token saved. Defaults to False.
  • session – This session is used to acquire/refresh token and to make API calls. Can be passed through the constructor, but it was made possible for the purpose of testing; do not pass it in for the regular usage.
add_editor(course_code: str, username: str, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Add a new editor.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • username – Username of the editor.
  • **kwargs – Anything that put() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

change_order_of_classifications(course_code: str, indexes: dict, semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Changes the order of classifications.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • indexes – The body for the request. Should be a plain Python dictionary.
  • semester – Semester identifier.
  • **kwargs – Anything that put() function from Requests library can take except for params and json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

clone_classification_definitions(target_semester: str, target_course_code: str, source_semester: str, source_course_code: str, remove_existing: bool, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Clones the definitions of the classification.

See Classification portal API documentation.

Parameters:
  • target_semester – Target semester code.
  • target_course_code – Target course code.
  • source_semester – Source semester code.
  • source_course_code – Source course code.
  • remove_existing – Remove existing definitions.
  • **kwargs – Anything that put() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

delete_classification(course_code: str, classification_id: str, semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Deletes classification.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • classification_id – Classification identifier.
  • semester – Semester identifier.
  • **kwargs – Anything that delete() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

delete_editor(course_code: str, username: str, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Delete given editor.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • username – Username of the editor.
  • **kwargs – Anything that delete() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

drop_session() → None

Closes and deletes internal OAuth2 session.

evaluate_all(expressions_dto: typing.Union[classification.entities.ExpressionParseAllRequestDto, typing.Dict[str, typing.Any]] = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Evaluate all expressions.

See Classification portal API documentation.

Parameters:
  • expressions_dto – The body for the request. Can be a plain Python dictionary or a ExpressionParseAllRequestDto.
  • **kwargs – Anything that post() function from Requests library can take except for json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_classification(course_code: str, identifier: str, semester: str = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Finds classification by identifier.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • identifier – Classification identifier.
  • semester – Semester identifier.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_classifications_for_course(course_code: str, semester: str = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Finds classification for the given course.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • semester – Semester identifier.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_student_classification(course_code: str, student_username: str, semester: str = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Find student classifications.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • student_username – The username of the student.
  • semester – Semester identifier.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_student_classifications_for_definitions(course_code: str, identifier: str, group_code: str = 'ALL', semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Find student classification for definitions.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • identifier – Classification identifier.
  • group_code – The code og the group.
  • semester – Semester identifier.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_student_group_classifications(course_code: str, group_code: str = 'ALL', semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Find student group classifications.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • group_code – The code of the group.
  • semester – Semester identifier.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_student_group_classifications_simple_s2t(course_code: str, group_code: str = 'ALL', semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Find student group classifications with a simplified response.

See Simplified operations section as well as find_student_group_classifications() method.

Parameters:
  • course_code – The code of the course.
  • group_code – The code of the group.
  • semester – Semester identifier.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the simplified response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

find_student_group_classifications_simple_t2s(course_code: str, group_code: str = 'ALL', semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Find student group classifications with a simplified response.

See Simplified operations section as well as find_student_group_classifications() method.

Parameters:
  • course_code – The code of the course.
  • group_code – The code of the group.
  • semester – Semester identifier.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the simplified response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

get_all_notifications(username: str, count: int = None, page: int = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Get all notifications.

See Classification portal API documentation.

Parameters:
  • username – The name of the user.
  • count – Count.
  • page – Page.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

get_course_groups(course_code: str, semester: str = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Get course groups.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • semester – Semester identifier.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

get_editors(course_code: str, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Get editors.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • **kwargs – Anything that get() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

get_functions(**kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Get all functions.

See Classification portal API documentation.

Parameters:**kwargs – Anything that get() function from Requests library can take.
Returns:On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

get_settings(semester: str = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Get settings.

See Classification portal API documentation.

Parameters:
  • semester – Semester identifier.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

get_unread_notifications(username: str, count: int = None, page: int = None, lang: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Get all unread notifications.

See Classification portal API documentation.

Parameters:
  • username – The name of the user.
  • count – Count.
  • page – Page.
  • lang – Language tag.
  • **kwargs – Anything that get() function from Requests library can take except for params.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

read_all_notifications(username: str, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Mark all notifications read.

See Classification portal API documentation.

Parameters:
  • username – The name of the user.
  • **kwargs – Anything that put() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

read_notification(username: str, id: int, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Mark a single notification as read.

See Classification portal API documentation.

Parameters:
  • username – The name of the user.
  • id – The identifier of the notification.
  • **kwargs – Anything that put() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

refresh_token(fun)

A decorator used internally to refresh token.

It is used with functions that make API calls. If it captures an error showing that token has expired, it tries to refresh it and then calls the function that caused it again.

reinit_session(callback_host: str = 'localhost', callback_port: int = 8080, force_new_token: bool = False) → None

Establishes a new session.

Called by the constructor internally. Use it, for example, when you need to log in with different credentials (name and password).

Parameters:
save_classification(course_code: str, classification_dto: typing.Union[classification.entities.ClassificationDto, typing.Dict[str, typing.Any]] = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Saves classification for the given course.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • classification_dto – The body for the request. Can be a plain Python dictionary or a ClassificationDto.
  • **kwargs – Anything that post() function from Requests library can take except for json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

save_my_settings(user_settings_dto: typing.Union[classification.entities.UserSettingsDto, typing.Dict[str, bool]] = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Save my settings.

See Classification portal API documentation.

Parameters:
  • user_settings_dto – The body of the request. Can be a plain Python dictionary or a UserSettingsDto.
  • **kwargs – Anything that put() function from Requests library can take except for json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

save_student_classifications(course_code: str, student_classifications: typing.Union[typing.List[classification.entities.StudentClassificationPreviewDto], typing.List[typing.Dict[str, typing.Any]]] = None, semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Save student classifications.

See Classification portal API documentation.

Parameters:
  • course_code – The code of the course.
  • student_classifications – The body of the request. Can be a list of plain Python dictionaries or of StudentClassificationPreviewDto.
  • semester – Semester identifier.
  • **kwargs – Anything that put() function from Requests library can take except for params and json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

save_student_classifications_simple_s2t(course_code: str, student_to_tasks: typing.Dict[str, typing.Dict[str, typing.Any]] = None, semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

A simplified solution to save students’ classifications.

See Simplified operations section as well as save_student_classifications() method.

Parameters:
  • course_code – The code of the course.
  • student_to_tasks – The body of the request. See Simplified operations section for the format.
  • semester – Semester identifier.
  • **kwargs – Anything that put() function from Requests library can take except for params and json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

save_student_classifications_simple_t2s(course_code: str, task_to_students: typing.Dict[str, typing.Dict[str, typing.Any]] = None, semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

A simplified solution to save students’ classifications.

See Simplified operations section as well as save_student_classifications() method.

Parameters:
  • course_code – The code of the course.
  • task_to_students – The body of the request. See Simplified operations section for the format.
  • semester – Semester identifier.
  • **kwargs – Anything that put() function from Requests library can take except for params and json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

save_student_course_settings(user_course_settings_dto: typing.Union[classification.entities.UserCourseSettingsDto, typing.Dict[str, typing.Any]] = None, semester: str = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Save student course settings.

See Classification portal API documentation.

Parameters:
  • user_course_settings_dto – The body of the request. Can be a plain Python dictionary or a UserCourseSettingsDto.
  • semester – Semester identifier.
  • **kwargs – Anything that put() function from Requests library can take except for params and json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

save_teacher_course_settings(user_course_settings_dto: typing.Union[classification.entities.UserCourseSettingsDto, typing.Dict[str, typing.Any]] = None, semester: str = None, **kwargs)

Save teacher course settings.

See Classification portal API documentation.

Parameters:
  • user_course_settings_dto – The body of the request. Can be a plain Python dictionary or a UserCourseSettingsDto.
  • semester – Semester identifier.
  • **kwargs – Anything that put() function from Requests library can take except for params and json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

try_validity(expression_dto: typing.Union[classification.entities.ExpressionParseRequestDto, typing.Dict[str, typing.Any]] = None, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Try validity of an expression.

See Classification portal API documentation.

Parameters:
  • expression_dto – The body for the request. Can be a plain Python dictionary or a ExpressionParseRequestDto.
  • **kwargs – Anything that post() function from Requests library can take except for json.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

unread_all_notifications(username: str, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Mark all notifications unread.

See Classification portal API documentation.

Parameters:
  • username – The name of the user.
  • **kwargs – Anything that delete() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

unread_notification(username: str, id: int, **kwargs) → typing.Union[typing.Dict[str, typing.Any], NoneType]

Mark a single notification as unread.

See Classification portal API documentation.

Parameters:
  • username – The name of the user.
  • id – The identifier of the notification.
  • **kwargs – Anything that delete() function from Requests library can take.
Returns:

On success, it returns the response body or None, if the body is empty.

Note

On failure, this method raises standard Requests errors.

Classification Proxy

class classification.classificationproxy.ClassificationParamsProxy(client_id, client_secret, callback_host='localhost', callback_port=8080, force_new_token=False, session=None, course_code=None, semester=None, group_code=None, lang=None)

This proxy class can store some parameters for API calls.

You can pass parameters listed below either during the creation of this object or later via directly setting its attributes. Later you can omit them in methods calls. Or supply them anyway to override saved defaults.

Note

This proxy can do everything that Classification class can. See its documentation for all the parameters. Here we describe only attributes not present in the default implementation.

Warning

Please note, that due to the fact that some parameters can be stored internally, they default to None now. However, they can still be needed to make API calls. are not compulsory in method calls. Keep in mind that:

  • If a required parameter is neither saved in proxy nor passed to a method explicitly, a MissingParameterError will be raised.
  • The order of arguments in methods of the plain client and its proxy version can be different. If you prefer to do without named arguments in Python, be sure to double check what you are passing to a method.
classification

str – The implementation of the real library, created automatically.

course_code

str – Stores the code of the course.

semester

str – Stores the semester identifier.

group_code

str – Stores the code of the group.

lang

str – Stores the language tag.

Helper classes (request body generation)

class classification.entities.ClassificationDto(calculated: bool = None, classification_text_dtos: typing.List[ClassificationTextDtoType] = None, classification_type: str = None, course_code: str = None, expression: str = None, hidden: bool = None, id: int = None, identifier: str = None, index: int = None, lowercase_identifier: str = None, mandatory: bool = None, maximum_value: float = None, minimum_required_value: float = None, semester_code: str = None, value_type: str = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

class classification.entities.ClassificationTextDto(identifier: str = None, name: str = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

class classification.entities.ExpressionParseAllRequestDto(expressions: typing.Any = None, variable_value_types: typing.Any = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

class classification.entities.ExpressionParseRequestDto(expected_result_type: str = None, expression: str = None, variable_value_types: str = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

class classification.entities.StudentClassificationPreviewDto(classification_identifier: str = None, id: int = None, note: str = None, student_username: str = None, value: typing.Any = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

class classification.entities.UserCourseSettingsDto(course_code: str = None, hidden: bool = None, silenced_notifications: bool = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

class classification.entities.UserSettingsDto(unsubscribe_emails: bool = None) → None

A helper class for making a request body.

to_dict()

Called internally to generate a dict body for request.

Exceptions

exception classification.exceptions.SavedTokenError

Error related to manipulations with the saved token.

Raised when the file with token cannot be read or when it lacks some essential parts (like “access_token” and/or “refresh_token” fields).

exception classification.exceptions.AuthError

Error related to authorization process.

Raised when, for example, the “code” field is missing from the GET callback during login.

exception classification.exceptions.MissingParameterError

Error related to proxy.

Raised when some compulsory parameter is missing from both its attribute and argument set of the method invocation.