Full API documentation

Client

class usos_api.client.USOSClient(api_base_address, consumer_key, consumer_secret, trust_env=False)[source]

Bases: object

A client for the USOS API.

Variables:

user_service (UserService) – The user service.
group_service (GroupService) – The group service.
api_server_service (APIServerService) – The API server service.
api_documentation_service (APIDocumentationService) – The API documentation service.
course_service (CourseService) – The course service.
term_service (TermService) – The term service.
grade_service (GradeService) – The grade service.
registration_service (RegistrationService) – The registration service.
connection (USOSAPIConnection) – The connection to the USOS API, used for making requests.

add_scope(scope)[source]

Add a scope to the client.

Parameters:: scope (str) – The scope to add.
Return type:: None

async authorize(verifier, request_token=None, request_token_secret=None)[source]

Authorize the client with verifier and optionally token and token secret.

Parameters token and token_secret can be useful when you create a new client instance and want to authorize it with the token and secret obtained from another client instance.

Parameters:

verifier (str) – The verifier to authorize the client with.
request_token (str) – The OAuth token obtained from the previous step.
request_token_secret (str) – The OAuth token secret obtained from the previous step.

Return type:

tuple[str, str]

Returns:

The access token and secret.

async close()[source]

Close the client.

Return type:: None

async get_authorization_url(callback_url='oob', confirm_user=False)[source]

Get the URL to authorize the client.

Parameters:

callback_url (str) – The URL to redirect to after authorization, leave as “oob” for pin-based authorization.
confirm_user (bool) – Whether to confirm the user before authorizing the client.

Return type:

str

Returns:

The URL to authorize the client.

load_access_token(access_token, access_token_secret)[source]

Load the access token and secret into the client.

Parameters:

access_token (str) – The access token.
access_token_secret (str) – The access token secret.

async load_access_token_from_file(file_path='usos_api_access_token.json')[source]

Load the access token and secret from a JSON file.

Parameters:: file_path (str) – The path to the JSON file.
Return type:: None

load_access_token_from_json(json_data)[source]

Load the access token and secret from a JSON object.

Parameters:: json_data (dict) – The JSON object containing the access token and secret.

async open()[source]

Open the client.

Return type:: None

remove_scope(scope)[source]

Remove a scope from the client.

Parameters:: scope (str) – The scope to remove.
Return type:: None

async save_access_token_to_file(file_path='usos_api_access_token.json')[source]

Save the access token and secret to a JSON file.

Parameters:: file_path (str) – The path to the JSON file.
Return type:: None

set_scopes(scopes)[source]

Set the scopes for the client.

Parameters:: scopes (list[str]) – The scopes to set.
Return type:: None

async test_connection()[source]

Test the connection to the USOS API.

Return type:: bool
Returns:: True if the connection is successful, False otherwise.

Connection

class usos_api.connection.USOSAPIConnection(api_base_address, consumer_key, consumer_secret, trust_env=False)[source]

Bases: object

A connection to the USOS API.

async close()[source]: Close the connection.

async get(service, **kwargs)[source]

Perform a GET request to the USOS API.

From the USOS API documentation: You may call all the services with GET or POST methods (POST preferred).

Parameters:

service (str) – The service to call.
kwargs – The parameters to pass.

Return type:

dict

Returns:

The response data.

async open()[source]: Open the connection.

async post(service, **kwargs)[source]

Perform a POST request to the USOS API.

From the USOS API documentation: You may call all the services with GET or POST methods (POST preferred).

Parameters:

service (str) – The service to call.
kwargs – The parameters to pass.

Return type:

dict

Returns:

The response data.

async test_connection()[source]

Test the connection to the USOS API.

Return type:: bool
Returns:: True if the connection is successful, False otherwise.

Auth

class usos_api.auth.AuthManager(api_base_address, consumer_key, consumer_secret, trust_env=False)[source]

Bases: object

A manager for the USOS API authentication.

async authorize(verifier, request_token, request_token_secret)[source]

Authorize the client with verifier and optionally token and token secret.

Parameters:

verifier (str) – The verifier to authorize the client with.
token – The OAuth token obtained from the previous step.
token_secret – The OAuth token secret obtained from the previous step.

Returns:

The access token and secret.

async close()[source]: Close the manager.

async get_authorization_url(callback_url, confirm_user=False)[source]

Get the authorization URL.

Parameters:

callback_url (str) – The callback URL.
confirm_user (bool) – Whether to confirm the user.

Return type:

str

Returns:

The authorization URL.

load_access_token(access_token, access_token_secret)[source]

Load the access token and secret into the manager.

Parameters:

access_token (str) – The access token.
access_token_secret (str) – The access token secret.

async logout()[source]: Log out the user.

async open()[source]: Open the manager.

sign_request(url, http_method='GET', **kwargs)[source]

Sign a request with the OAuth client.

Parameters:

url (str) – The URL to sign.
http_method (str) – The HTTP method to use.
kwargs – Additional parameters to pass.

Return type:

tuple[str, dict, dict]

Returns:

The signed URL, headers, and body.

logger

usos_api.logger.get_logger(name)[source]

Get a logger with the specified name.

Parameters:: name (str) – The name of the logger.
Return type:: Logger
Returns:: The logger.

Services

class usos_api.services.APIDocumentationService(connection)[source]

A service for API documentation fetching.

async get_method_index()[source]

Get a list of API methods with brief descriptions.

Return type:: list[APIMethodIndexItem]
Returns:: List of objects representing the methods.

async get_method_info(method, fields=None)[source]

Get information about a specific method.

Parameters:

method (str) – The method to get information about.
fields (list[str] | None) – The fields to include in the response.

Return type:

APIMethodInfo

Returns:

Object representing the method.

async get_module_info(module_name)[source]

Get information about a specific module.

Parameters:: module_name (str) – The name of the module.
Return type:: APIModuleInfo
Returns:: Object representing the module.

async get_scopes()[source]

Get a list of all scopes available in the USOS API installation.

Return type:: list[ScopeInfo]
Returns:: List of scope information objects.

class usos_api.services.APIServerService(connection)[source]

A service for APIServer-related operations.

async get_consumer_info(fields=None)[source]

Get information on the Consumer.

Parameters:: fields (list[str] | None) – The fields to include in the response.
Return type:: Consumer
Returns:: A dictionary of fields you have asked for.

class usos_api.services.CourseService(connection)[source]

A service for course-related operations.

async get_courses(course_ids, fields=None)[source]

Get courses by their IDs.

Parameters:

course_ids (list[str]) – The IDs of the courses to get.
fields (Optional[list[str]]) – The fields to include in the response.

Return type:

list[Course]

Returns:

A list of courses.

async get_user_course_editions(active_terms_only=False, ongoing_terms_only=False)[source]

Get information on user’s courses.

This is a BETA method. We’re looking for beta-testers. Until we find them, there’s a substantial probability it won’t stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Parameters:

active_terms_only (bool) – Return only these course editions which are related to the currently active academic terms. Apparently, this parameter does not always work as expected, so you can use ongoing_terms_only instead.
ongoing_terms_only (bool) – Return only these course editions which are related to the currently ongoing academic terms (filtered locally based on start and finish dates).

Return type:

list[CourseEdition]

Returns:

A dictionary of selected fields and their values.

async get_user_courses_ects()[source]

Get user courses ECTS.

Return type:: dict[str, dict[str, Optional[float]]]
Returns:: The user courses ECTS.

class usos_api.services.GradeService(connection)[source]

A service for grade-related operations.

async get_grades_by_terms(term_ids, fields=None)[source]

Get grades by terms.

Parameters:

term_ids (list[str] | str) – The IDs of the terms to get grades for, or a single term ID.
fields (list[str]) – The fields to include in the response.

Return type:

dict[str, dict[str, dict[str, dict[str, Grade] | list[Grade]]]]

Returns:

The grades.

class usos_api.services.GroupService(connection)[source]

A service for group-related operations.

async get_group_by_id(group_id, course_unit_id, fields=None)[source]

Get group by their ID.

Parameters:

group_id (str) – The ID of the groups to get.
course_unit_id (str) – The ID of the course unit.
fields (list[str]) – The fields to include in the response.

Return type:

list[Group]

Returns:

A dictionary of group IDs to groups.

async get_groups_by_ids(group_ids, fields=None)[source]

Get groups by their IDs.

Parameters:

group_ids (list[tuple[str, str]]) – The IDs of the groups to get. Each ID should be a tuple of course unit ID and group number.
fields (list[str]) – The fields to include in the response.

Return type:

list[Group]

Returns:

A dictionary of group IDs to groups.

async get_groups_for_lecturer(user_id=None, active_terms_only=False, ongoing_terms_only=False, fields=None, lang='en')[source]

Get groups for a lecturer.

Parameters:

user_id (int | None) – The ID of the lecturer to get groups for, or None to get groups for the current user.
active_terms_only (bool) – Whether to only get groups from active terms. Apparently, this parameter does not always work as expected, so you can use ongoing_terms_only instead.
ongoing_terms_only (bool) – Whether to only get groups from ongoing terms (filtered locally based on start and finish dates).
fields (list[str]) – The fields to include in the response.
lang (str) – Either pl or en - resulting list of groups will be sorted by the course name in the specified language.

Return type:

list[Group]

Returns:

A dictionary with the following fields: ‘groups’ (list of groups) and ‘terms’ (list of terms).

async get_groups_for_participant(user_id=None, active_terms_only=False, ongoing_terms_only=False, fields=None, lang='en')[source]

Get groups for a participant.

Parameters:

user_id (int | None) – The ID of the participant to get groups for, or None to get groups for the current user.
active_terms_only (bool) – Whether to only get groups from active terms. Apparently, this parameter does not always work as expected, so you can use ongoing_terms_only instead.
ongoing_terms_only (bool) – Whether to only get groups from ongoing terms (filtered locally based on start and finish dates).
fields (list[str]) – The fields to include in the response.
lang (str) – Either pl or en - resulting list of groups will be sorted by the course name in the specified language.

Return type:

list[Group]

Returns:

A dictionary with the following fields: ‘groups’ (list of groups) and ‘terms’ (list of terms).

async get_groups_for_user(user_id=None, active_terms_only=False, ongoing_terms_only=False, fields=None, lang='en')[source]

Get groups for a user.

Parameters:

user_id (int | None) – The ID of the user to get groups for, or None to get groups for the current user.
active_terms_only (bool) – Whether to only get groups from active terms. Apparently, this parameter does not always work as expected, so you can use ongoing_terms_only instead.
ongoing_terms_only (bool) – Whether to only get groups from ongoing terms (filtered locally based on start and finish dates).
fields (list[str]) – The fields to include in the response.
lang (str) – Either pl or en - resulting list of groups will be sorted by the course name in the specified language.

Return type:

list[Group]

Returns:

A dictionary with the following fields: ‘groups’ (list of groups) and ‘terms’ (list of terms).

class usos_api.services.RegistrationService(connection)[source]

A service for registration-related operations.

async get_courses_cart(fields=None)[source]

Get user courses cart with registrations information.

Parameters:: fields (list[str]) – Selector of result fields you are interested in (optional, default is specified fields).
Return type:: list[CoursesCart]
Returns:: A CoursesCartResponse object.

async get_registration(registration_id, fields=None)[source]

Get a registration.

Parameters:

registration_id (str) – The ID of the registration.
fields (list[str]) – Selector of result fields you are interested in (optional, default is specified fields).

Return type:

Registration

Returns:

The registration.

async get_user_registrations(active_only=True, fields=None)[source]

Get user registrations.

Parameters:

active_only (bool) – Whether to return only active registrations.
fields (list[str]) – Selector of result fields you are interested in (optional, default is specified fields).

Return type:

list[Registration]

Returns:

The user registrations.

async register_to_course(round_id, course_id, term_id, user_programme_id=None, user_stage_id=None)[source]

Register to a course.

Parameters:

round_id (str) – Registration round ID.
course_id (str) – Course code.
term_id (str) – Cycle code.
user_programme_id (str) – User program ID (optional).
user_stage_id (str) – User stage ID (optional).

Return type:

dict

Returns:

Empty dict on success.

class usos_api.services.TermService(connection)[source]

A service for term-related operations.

async get_term(term_id)[source]

Get a term by its ID.

Parameters:: term_id (str) – The ID of the term to get.
Return type:: Term
Returns:: The term.

async get_terms(term_ids)[source]

Get terms by their IDs.

Parameters:: term_ids (list[str]) – The IDs of the terms to get, or a single term ID.
Return type:: list[Term]
Returns:: The terms.

class usos_api.services.UserService(connection)[source]

A service for user-related operations.

async get_user(user_id=None, fields=None)[source]

Get a user by their ID or the currently authorized user.

Parameters:

user_id (int | None) – The ID of the user to get. If None, the currently authorized user will be returned.
fields (list[str] | None) – The fields to include in the response. Whole list of fields can be found here.

Return type:

User

Returns:

The user.

Helper

class usos_api.helper.APIHelper(client)[source]

Bases: object

async get_user_end_grades_with_weights(current_term_only=False)[source]

Get user end grades with weights.

Parameters:: current_term_only (bool) – If True, only consider the current term.
Return type:: List[Grade]
Returns:: A list of user end grades with weights.