ade_api module

class ade_api.Client(credentials: Dict[str, Union[str, List[int]]])

Bases: ade_api.DummyClient

A client subclasses the DummyClient abstract class and implements access to ADE API using correct credentials. If you do not own such credentials, please use FakeClient().

expire_in() → float

Returns the time remaining before the token expires.

Returns: the time remaining in seconds, 0 if expired
Return type: float

is_expired() → bool

Returns whether the current token is expired.

Returns: True if the token is expired
Return type: bool

renew_token(): Renews the current token requesting a new one.

request(**kwargs: Union[str, int]) → requests.models.Response

Performs a request to the API with given parameters. The client should automatically renew its token if it has expired.

Parameters: kwargs (Request) – set of key / value parameters that will be merged
Returns: the response
Return type: request.Response
Raises: HTTPError – if the request is unsuccessful (oustide the 2XX-3XX range)

class ade_api.DummyClient(credentials: Dict[str, Union[str, List[int]]])

Bases: object

A dummy client is an abstrat class providing just the specific requests, but not the access to the API. Access to the API is to be implemented.

Parameters

credentials – all information needed to make requests to API
credentials – ClientCredentials

Example

>>> import backend.credentials as credentials
>>> credentials = credentials.get_credentials(credentials.ADE_API_CREDENTIALS)
>>> client = Client(credentials)

expire_in() → float

Returns the time remaining before the token expires.

Returns: the time remaining in seconds, 0 if expired
Return type: float

get_activities(resource_ids: List[str], project_id: str) → requests.models.Response

Requests all activities (set of events) for a specific project.

Parameters

resource_ids (List[str]) – the ids of all the resources the activities are requested
project_id (str) – the id of the project

Returns

the response

Return type

request.Response

get_classrooms(project_id: str) → requests.models.Response

Requests all the classrooms for a specific project.

Parameters: project_id (str) – the id of the project
Returns: the response
Return type: request.Response

get_course_resources(project_id: str) → Tuple[requests.models.Response, requests.models.Response]

Requests all the course resource for a specific project.

Parameters: project_id (str) – the id of the project
Returns: a tuple the response
Return type: Tuple[request.Response, requests.Response]

get_project_ids() → requests.models.Response

Requests the project ids currently available; each year (project) corresponds to an id.

Returns: the response
Return type: request.Response

get_resource_ids(project_id: str) → requests.models.Response

Requests the ids of all the resource for a specific project.

Parameters: project_id (str) – the id of the project
Returns: the response
Return type: request.Response

get_resources(project_id: str) → requests.models.Response

Requests all the resource for a specific project.

Parameters: project_id (str) – the id of the project
Returns: the response
Return type: request.Response

is_expired() → bool

Returns whether the current token is expired.

Returns: True if the token is expired
Return type: bool

renew_token() → None: Renews the current token requesting a new one.

request(**kwargs: Union[str, int]) → requests.models.Response

Performs a request to the API with given parameters. The client should automatically renew its token if it has expired.

Parameters: kwargs (Request) – set of key / value parameters that will be merged
Returns: the response
Return type: request.Response
Raises: HTTPError – if the request is unsuccessful (oustide the 2XX-3XX range)

exception ade_api.ExpiredTokenError

Bases: Exception

Exception that will occur if a token is expired.

class ade_api.FakeClient(credentials: Dict[str, Union[str, List[int]]])

Bases: ade_api.DummyClient

A fake client subclasses the DummyClient abstract class and implements a fake access to ADE API. All the API responses you can cannot are stored in json file, which you can change if you want to.

FOLDER = 'fake_api'

expire_in() → float

Returns the time remaining before the token expires.

Returns: the time remaining in seconds, 0 if expired
Return type: float

is_expired() → bool

Returns whether the current token is expired.

Returns: True if the token is expired
Return type: bool

renew_token() → None: Renews the current token requesting a new one.

request(**kwargs: Union[str, int]) → requests.models.Response

Performs a request to the API with given parameters. The client should automatically renew its token if it has expired.

Parameters: kwargs (Request) – set of key / value parameters that will be merged
Returns: the response
Return type: request.Response
Raises: HTTPError – if the request is unsuccessful (oustide the 2XX-3XX range)

ade_api.get_response_path(request_name: str) → str

Returns the path where the response should be located if using the fake ade api.

Parameters: request_name (str) – the parameters used in the request, concatenated as in FakeClient.request()
Returns: the path
Return type: str

ade_api.get_token(credentials: Dict[str, Union[str, List[int]]]) → Tuple[str, int]

Requests a new token to the API.

Parameters

credentials – all information needed to make requests to API
credentials – ClientCredentials

Returns

the token and its time to expiration in seconds

Return type

Tuple[str, int]

ade_api.load_response(request_name: str) → requests.models.Response

Loads the response of a given request.

Parameters: request_name (str) – the parameters used in the request, concatenated as in FakeClient.request()
Returns: the response
Return type: requests.Response
Raises: HTTPError – if the response to the request could not be found in the file

ade_api.parse_activity(activity: lxml.etree._Element) → Tuple[List[backend.events.AcademicalEvent], str, str, str]

Parses an element from a request into a list of events and some activity information.

Parameters: activity (etree._Element) – the activity element
Returns: the events, the name, the id and the code of this activity
Return type: Tuple[List[backend.events.AcademicalEvent], str, str, str]

ade_api.parse_event(event: lxml.etree._Element, event_type: backend.events.AcademicalEvent, activity_name: str, activity_id: str, activity_code: str) → backend.events.AcademicalEvent

Parses an element from a request into an academical event. An event is from an activity so information about this activity must be provided.

Parameters

event (etree._Element) – the event element
event_type (Type[backend.events.AcademicalEvent]) – the constructor used to initiate to event object
activity_name (str) – the name of the activity
activity_id (str) – the id of the activity
activity_code (str) – the code of the activity

Returns

the academical event

Return type

backend.events.AcademicalEvent

ade_api.response_to_classrooms(classrooms_response: requests.models.Response) → List[backend.classrooms.Classroom]

Extracts an API response into list of classrooms.

Parameters: classrooms_response (requests.Response) – a response from the API to the classrooms request
Returns: all classrooms
Return type: List[Classroom]
Example

>>> response = client.get_classrooms(9)  # project id for 2019-2020
>>> classrooms = response_to_classrooms(response)

ade_api.response_to_course_resources(course_resources_response: Tuple[requests.models.Response, requests.models.Response]) → pandas.core.frame.DataFrame

Extracts an API response into an dataframe containing all course resources.

Parameters: course_resources_response (Tuple[requests.Response, requests.Response]) – a response from the API to the course resources request
Returns: all the course resources
Return type: pd.Dataframe

ade_api.response_to_courses(activities_response: requests.models.Response) → List[backend.courses.Course]

Extracts an API response into list of courses.

Parameters: activities_response (requests.Response) – a response from the API to the activities request
Returns: all courses present in the response
Return type: List[Courses]
Example

>>> response = client.get_activities(['1234'], 9)  # project id for 2019-2020
>>> courses = response_to_courses(response)

ade_api.response_to_events(activities_response: requests.models.Response, filter_func: Callable[[backend.events.AcademicalEvent], bool]) → List[backend.events.AcademicalEvent]

Extracts an API response into list of events.

Parameters

activities_response (requests.Response) – a response from the API to the activities request
filter_func (Callable[[backend.events.AcademicalEvent], bool]) – a function to filter out events

Returns

all events present in the response, optionnally filtered

Return type

List[backend.events.AcademicalEvents]

Example

>>> response = client.get_activities(['1234'], 9)  # project id for 2019-2020
>>> events = response_to_events(response)

ade_api.response_to_project_ids(project_ids_response: requests.models.Response) → Dict[str, str]

Extracts an API response into an iterator of project ids and years.

Parameters: project_ids_response (requests.Response) – a response from the API to the project_ids request
Returns: all the project ids and years (year as key, id as value)
Return type: Dict[str, int]
Example

>>> response = client.get_project_ids()
>>> ids_years = response_to_project_ids(response)

ade_api.response_to_resource_ids(resource_ids_response) → Dict[str, str]

Extracts an API response into an dictionary mapping a resource name to its ids.

Parameters: resource_ids_response (requests.Response) – a response from the API to the resources or resource_ids request
Returns: all the resources names and their ids
Return type: Dict[str, str]
Example

>>> response = client.get_resource_ids(9)  # project id for 2019-2020
>>> resources_ids = response_to_resource_ids(response)

ade_api.response_to_resources(resources_response: requests.models.Response) → pandas.core.frame.DataFrame

Extracts an API response into an dataframe containing all resources.

Parameters: resources_response (requests.Response) – a response from the API to the resources request
Returns: all the resources
Return type: pd.Dataframe
Example

>>> response = client.get_resources(9)  # project id for 2019-2020
>>> resources = response_to_resources(response)

ade_api.response_to_root(response: requests.models.Response) → lxml.etree._Element

Parses an API response into a tree structure.

Parameters: response (requests.Response) – a response from the API
Returns: the tree structure
Return type: etree._ElementTree

ade_api.room_to_classroom(room: lxml.etree._Element) → backend.classrooms.Classroom

Parses the (class)room retrieved from API to a more convenient Classroom object.

Parameters: room (etree._Element) – (class)room as a tree structure
Returns: the classroom
Return type: Classroom

ade_api.save_response(response: requests.models.Response, request_name: str)

Saves the response to a request into the file specified by the FakeClient class.

Parameters

response (requests.Response) – the response to the request
request_name (str) – the parameters used in the request, concatenated as in FakeClient.request()