Modules

The modules are used to make manual HTTP requests to the Classeviva APIs. These come from the official API documentation and are implemented in the wrapper exactly as they were written on there.

Modules are useful when:

  • You use the me attribute in ClassevivaClient to get the information you need more easily, which automatically uses the right module;

  • You want to make a request to an endpoint that hasn’t been/is partially implemented in this wrapper;

  • You want to have more control over the request or response;

  • You don’t want to manually write every URL, like you would do with the request() method.

Note

Of course, if you decide to use modules, you will have to parse the response yourself, as they only return the raw response.

Warning

The modules are not made to be manually constructed, but to be used through the ClassevivaClient instance.

Common features

class aiocvv.modules.core.Module(client)

This is the base module for the students, parents and teachers modules. It implements the basic methods that are shared between the three modules.

async request(method, endpoint, *, params=None, data=None, json=None, cookies=None, headers=None, skip_auto_headers=None, compress=None, chunked=None, raise_for_status=True, read_until_eof=True, proxy=None, timeout=_SENTINEL.sentinel, verify_ssl=None, fingerprint=None, ssl_context=None, ssl=None, proxy_headers=None, trace_request_ctx=None, read_bufsize=None)

Make a raw HTTP request to the Classeviva REST APIs using aiohttp.

This function calls ClassevivaClient.request() to make the request itself, the only difference is that the request will be forced to be inside the module.

Note

For example, if you want to make a request to the /students/<sid>/homeworks endpoint from the students module, the endpoint parameter should be /<sid>/homeworks, otherwise the request will fail as it’ll make a request to /students/students/<sid>/homeworks, which is not valid.

For information about the valid endpoints, refer to the Classeviva REST API documentation:

Parameters:

  • method (str) – The HTTP method to use.

  • endpoint (str) – The path for the request. Must be a relative URL since the base URL is https://web.spaggiari.eu/rest/v1/<module>/.

  • params (Optional[Mapping[str, str]]) – Optional. The query parameters for the request.

  • data (Any) – Optional. The request body data.

  • json (dict) – Optional. The request body JSON data.

  • cookies (Optional[LooseCookies]) – Optional. The cookies to include in the request.

  • headers (Optional[LooseHeaders]) – Optional. The headers to include in the request.

  • skip_auto_headers (Optional[Iterable[str]]) – Optional. The headers to skip from automatic inclusion.

  • compress (Optional[str]) – Optional. The compression method to use.

  • chunked (Optional[bool]) – Optional. Whether to use chunked transfer encoding.

  • raise_for_status (bool) – Optional. Whether to raise an exception for non-successful responses.

  • read_until_eof (bool) – Optional. Whether to read the response until EOF.

  • proxy (Optional[StrOrURL]) – Optional. The proxy URL or path.

  • timeout (ClientTimeout) – Optional. The request timeout.

  • verify_ssl (Optional[bool]) – Optional. Whether to verify SSL certificates.

  • fingerprint (Optional[bytes]) – Optional. The SSL fingerprint.

  • ssl_context (Optional[SSLContext]) – Optional. The SSL context.

  • ssl (Optional[Union[SSLContext, bool, Fingerprint]]) – Optional. The SSL configuration.

  • proxy_headers (Optional[LooseHeaders]) – Optional. The headers to include in the proxy request.

  • trace_request_ctx (Optional[SimpleNamespace]) – Optional. The request context for tracing.

  • read_bufsize (Optional[int]) – Optional. The read buffer size.

Returns:

The HTTP response dictionary.

Return type:

dict

class aiocvv.modules.core.BaseModule(client)

Base class for student and peacher modules. It’s not the base class for the parent module because it has totally different endpoints, which is why parents can access all of the student’s endpoints.

async get_card(id)

Get the card of the user.

Return type:

Union[OKResponse, ErrorResponse]

Parameters:

id (int)

property noticeboard: Noticeboard

Get the noticeboard-related endpoints, which have been separated to avoid making too many functions in one class for the same endpoints.

class aiocvv.modules.core.Noticeboard(module)

Represents the noticeboard functionality in the ClasseViva API.

Parameters:

module (Module)

async all(id)

Get all the noticeboard items.

Parameters:

id (int) – The ID of the student/teacher.

Return type:

Union[OKResponse, ErrorResponse]

Returns:

The response from the API.

async get_attachment(id, event_code, publication_id, attach_num=1)

Get an attachment from a noticeboard item.

Parameters:

  • id (int) – The ID of the student/teacher.

  • event_code (int) – The code of the notice.

  • publication_id (int) – The ID itself of the notice.

  • attach_num (int) – Optional. The attachment number.

Return type:

Union[OKResponse, ErrorResponse]

Returns:

The response from the API.

async join(id, event_code, publication_id, *, text=None, file=None, filename=None, sign=None, attrs=True, include_attachment=False, reply_info=False, multi=False)

Join a noticeboard item.

Note

This will automatically mark the item as read from the Classeviva backend.

Parameters:

  • id (int) – The ID of the student/teacher.

  • event_code (int) – The code of the notice.

  • publication_id (int) – The ID itself of the notice.

  • text (Optional[str]) – Optional. The text to join with.

  • file (Optional[IO[Any]]) – Optional. The file object to join with.

  • filename (Optional[str]) – Optional. The name of the file to join with.

  • sign (Optional[bool]) – Optional. Whether to sign the join.

  • attrs (bool) – Optional. Whether to include attributes.

  • include_attachment (bool) – Optional. Whether to include attachments.

  • reply_info (bool) – Optional. Whether to include reply information.

  • multi (bool) – Optional. Whether to get all of the attachments of the item. This is useful when include_attachment is True.

Return type:

Union[OKResponse, ErrorResponse]

Returns:

The response from the API.

async read(id, event_code, publication_id, *, attrs=True, include_attachment=False, reply_info=False, multi=False)

Read a noticeboard item.

Note

This will automatically mark the item as read from the Classeviva backend.

Parameters:

  • id (int) – The ID of the student/teacher.

  • event_code (int) – The code of the notice.

  • publication_id (int) – The ID itself of the notice.

  • attrs (bool) – Optional. Whether to include attributes.

  • include_attachment (bool) – Optional. Whether to include attachments.

  • reply_info (bool) – Optional. Whether to include reply information.

  • multi (bool) – Optional. Whether to get all of the attachments of the item. This is useful when include_attachment is True.

Return type:

Union[OKResponse, ErrorResponse]

Returns:

The response from the API.

Students

This module is used to make HTTP requests to the students endpoint. It can be used by students and parents, and not by teachers.

class aiocvv.modules.students.StudentsModule(client)

This module is used to make HTTP requests to Classeviva’s students module.

async absences(student_id, start=None, end=None)

Get the student’s absences.

Parameters:

  • student_id (int) – The ID of the student.

  • start (Union[date, datetime, None]) – Optional. The start date of the absences, or the single absence day.

  • end (Union[date, datetime, None]) – Optional. The end date of the absences.

Returns:

The response from the Classeviva API.

Return type:

dict

async agenda(student_id, start, end, event_code=None)

Get the student’s agenda (as in events, homeworks, etc.).

Parameters:

  • student_id (int) – The ID of the student.

  • start (Union[date, datetime]) – The start date of the agenda.

  • end (Union[date, datetime]) – The end date of the agenda.

  • event_code (Optional[EventCode]) – Optional. The event code to filter the agenda by.

Returns:

The response from the Classeviva API.

Return type:

dict

Raises:

ValueError – If the end date is before the start date.

async calendar(student_id, start=None, end=None)

Get information about the school’s working, non-working and holiday days.

Note

Without the dates, it returns the whole calendar from the beginning to the end of the school year.

Parameters:

  • student_id (int) – The ID of the student.

  • start (Union[date, datetime, None]) – The start date of the calendar (optional).

  • end (Union[date, datetime, None]) – The end date of the calendar (optional).

Returns:

The response from the Classeviva API.

Return type:

dict

Raises:

ValueError – If the end date is before the start date.

async didactics(student_id, content_id=None)

Get the didactics for a student.

Parameters:

  • student_id (int) – The ID of the student.

  • content_id (Optional[int]) – Optional. The content ID.

Returns:

The response from the Classeviva API.

Return type:

dict

async documents(student_id, hash=None, *, check=False)

Get the documents for a student.

Parameters:

  • student_id (int) – The ID of the student.

  • hash (Optional[str]) – Optional. The hash of the document.

  • check (Optional[bool]) – Optional. Whether to check the document.

Returns:

The response from the Classeviva API.

Return type:

dict

async grades(student_id, subject=None)

Get the student’s current grades.

Parameters:

  • student_id (int) – The ID of the student.

  • subject (Optional[int]) – Optional. The ID of the subject to get the grades of.

Returns:

The response from the Classeviva API.

Return type:

dict

property homeworks: StudentHomeworks

Get homeworks-related endpoints, which have been separated from here to avoid making too many functions in one class for the same endpoint.

Note that this is for media that may be attached to homeworks. If you are looking for the homeworks from the agenda, use the agenda() or the overview() method instead.

async lessons(student_id, start, end=None, *, subject=None)

Get the student’s lessons.

Parameters:

  • student_id – The ID of the student.

  • start (Union[date, datetime]) – The date from which to start retrieving lessons, or the day to get lessons of.

  • end (Union[date, datetime, None]) – Optional. The date until which to retrieve lessons.

  • subject (Optional[int]) – Optional. The ID of the subject to get the lessons of.

Returns:

The response from the Classeviva API.

Return type:

dict

async notes(student_id, type=None, event=None)

Get the student’s disciplinary notes.

Parameters:

  • student_id (int) – The ID of the student.

  • type (Optional[NoteType]) – Optional. The type of note to get.

  • event (Optional[int]) – Optional. The ID of the note to get.

Returns:

The response from the Classeviva API.

Return type:

dict

Raises:

ValueError – If the note ID is provided without the note type.

async overview(student_id, start, end=None)

Get the student’s agenda, lessons, events, grades and notes of a period, all in one request.

Parameters:

  • student_id (int) – The ID of the student.

  • start (Union[date, datetime]) – The start date of the overview or the single day to get the overview of.

  • end (Union[date, datetime, None]) – Optional. The end date of the overview.

Returns:

The response from the Classeviva API.

Return type:

dict

Raises:

ValueError – If the end date is before the start date.

async periods(student_id)

Get the student’s school year periods.

Parameters:

student_id (int) – The ID of the student.

Returns:

The response from the Classeviva API.

Return type:

dict

async register_config(student_id)

Get the register configuration.

Parameters:

student_id (int) – The ID of the student.

Returns:

The response from the Classeviva API.

Return type:

dict

async schoolbooks(student_id)

Get the student’s schoolbooks.

Parameters:

student_id (int) – The ID of the student.

Returns:

The response from the Classeviva API.

Return type:

dict

async subjects(student_id)

Get the student’s subjects.

Parameters:

student_id (int) – The ID of the student.

Returns:

The response from the Classeviva API.

Return type:

dict

async virtual_classes(student_id)

Get the student’s virtual classes.

Parameters:

student_id (int) – The ID of the student.

Returns:

The response from the Classeviva API.

Return type:

dict

class aiocvv.modules.students.StudentHomeworks(module)

Represents a collection of methods for managing student homeworks.

Parameters:

module (StudentsModule)

async all(student_id)

Retrieves all of the student’s homeworks.

Parameters:

student_id (int) – The ID of the student.

Returns:

The response from the Classeviva API.

Return type:

dict

async download_teacher_file(student_id, event_code, file_id)

Downloads a teacher file associated with a specific homework.

Parameters:

  • student_id (int) – The ID of the student.

  • event_code (str) – The event code of the homework.

  • file_id (int) – The ID of the file.

Returns:

The response from the Classeviva API.

Return type:

dict

async insert_student_msg(student_id, event_code, homework_id, message)

Inserts a message from the student for a specific homework.

Parameters:

  • student_id (int) – The ID of the student.

  • event_code (str) – The event code of the homework.

  • homework_id (int) – The ID of the homework.

  • message (str) – The message to insert.

Returns:

The response from the Classeviva API.

Return type:

dict

async remove_student_file(student_id, event_code, homework_id, file_id)

Removes a file uploaded by the student for a specific homework.

Parameters:

  • student_id (int) – The ID of the student.

  • event_code (str) – The event code of the homework.

  • homework_id (int) – The ID of the homework.

  • file_id (int) – The ID of the file.

Returns:

The response from the Classeviva API.

Return type:

dict

async set_teacher_msg_status(student_id, event_code, homework_id, read=True)

Sets the status of a teacher message for a specific homework.

Parameters:

  • student_id (int) – The ID of the student.

  • event_code (str) – The event code of the homework.

  • homework_id (int) – The ID of the homework.

  • read (bool) – The status of the message (default: True).

Returns:

The response from the Classeviva API.

Return type:

dict

async upload_student_file(student_id, event_code, homework_id, file, filename=None)

Uploads a file from the student for a specific homework.

Parameters:

  • student_id (int) – The ID of the student.

  • event_code (str) – The event code of the homework.

  • homework_id (int) – The ID of the homework.

  • file (IO[Any]) – The file to upload.

  • filename (Optional[str]) – The name of the file (optional).

Returns:

The response from the Classeviva API.

Return type:

dict