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 forparams
andjson
.
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 forparams
.
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 forparams
.
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 forjson
.
Returns: On success, it returns the response body or
None
, if the body is empty.Note
On failure, this method raises standard Requests errors.
- expressions_dto – The body for the request. Can be
a plain Python dictionary or a
-
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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 forparams
.
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: - callback_host – See
__init__()
. - callback_port – See
__init__()
. - force_new_token – See
__init__()
.
- callback_host – See
-
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 forjson
.
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 forjson
.
Returns: On success, it returns the response body or
None
, if the body is empty.Note
On failure, this method raises standard Requests errors.
- user_settings_dto – The body of the request. Can be
a plain Python dictionary or a
-
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 forparams
andjson
.
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 forparams
andjson
.
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 forparams
andjson
.
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 forparams
andjson
.
Returns: On success, it returns the response body or
None
, if the body is empty.Note
On failure, this method raises standard Requests errors.
- user_course_settings_dto – The body of the request. Can be
a plain Python dictionary or a
-
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 forparams
andjson
.
Returns: On success, it returns the response body or
None
, if the body is empty.Note
On failure, this method raises standard Requests errors.
- user_course_settings_dto – The body of the request. Can be
a plain Python dictionary or a
-
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 forjson
.
Returns: On success, it returns the response body or
None
, if the body is empty.Note
On failure, this method raises standard Requests errors.
- expression_dto – The body for the request. Can be
a plain Python dictionary or a
-
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.
- If a required parameter is neither saved in proxy
nor passed to a method explicitly,
a
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.
-
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.