Client

The module where the ClassevivaClient class is located.

class aiocvv.client.ClassevivaClient(username, password, identity=None, *, loop=None, base_url='https://web.spaggiari.eu/rest/v1/', strict_caching=True)

The client class for Classeviva.

This class provides an interface to interact with the Classeviva REST APIs, where all the requests from this module are made. You can get any information from Classeviva by either using the me attribute or by making manual requests using the appropriate module or the request() method-

The modules are used to make manual HTTP requests to the Classeviva APIs. This is useful when:

  • You use the me attribute to automatically get the information you need, which chooses the correct module to use;

  • You want to make a request to an endpoint that is not (yet) or 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.

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

Parameters:

  • username (str) – The username for authentication.

  • password (str) – The password for authentication.

  • identity (str) – Optional. The identity for authentication.

  • loop (asyncio.AbstractEventLoop) – Optional. The event loop to use. If not provided, the default event loop will be used.

  • base_url (str) – Optional. The base URL for the Classeviva REST APIs. Default is https://web.spaggiari.eu/rest/v1/.

  • strict_caching (bool) – Optional. Whether to strictly use caching. Setting this to True might introduce some delays in updates, but will reduce the number of requests made and will make the client faster.

property base_url: str

The base URL for the Classeviva REST APIs.

You can change this if: * You’re trying to fetch data from a past school year; * You’re testing against a local or private instance of Classeviva.

Note

If you’re changing this to get data from a past school year, the base URL will be something like https://webYY.spaggiari.eu/rest/v1/, where YY is the last two digits of the year. For example, in August 2025, the previous school year was “2024-2025”, so the base URL would be https://web24.spaggiari.eu/rest/v1/.

Returns:

The base URL.

async login(raise_exceptions=True)

Log in to Classeviva using the passed credentials.

Parameters:

raise_exceptions (bool) – Optional. Whether to raise exceptions for authentication errors.

Returns:

True if login is successful, False otherwise.

Return type:

bool

property me: Student | Parent | Teacher | None

Get the current user.

Note

This will be None until login() is called or the class is awaited.

Returns:

The current user instance.

property parents: ParentsModule

Get the parents module for manually making requests to the parents’ endpoints.

Returns:

The module instance.

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.

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/.

  • 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.

Return type:

Union[OKResponse, ErrorResponse]

Returns:

The HTTP response dictionary.

property students: StudentsModule

Get the students module for manually making requests to the students’ endpoints.

Returns:

The module instance.

property teachers: TeachersModule

Get the teachers module for manually making requests to the teachers’ endpoints.

Warning

This whole module has not been implemented yet, because it’s not possible to test it without having a teacher account. Therefore, this is just a placeholder for future updates, which means there are no endpoints in here. If you are a teacher and you want to contribute to this project, feel free to open a pull request. Otherwise, you’ll have to manually make requests using the request() method.

Returns:

The (empty) module instance.

This module contains the class that represents students, teachers and parents all together.

class aiocvv.me.Me(client, **kwargs)

Represents a Classeviva user, whether it’s a student, a teacher or a parent.

Note

This class is not meant to be manually constructed, but to be used through the ClassevivaClient class.

property birth_date: datetime

The user’s birth date.

property first_name: str

The user’s first name.

property fiscal_code: str

The user’s fiscal code.

async get_avatar()

Returns the user’s avatar as a BytesIO object.

Return type:

BytesIO

async get_enabled_apps()

Get the enabled apps for the user.

property id: int

The user’s ID.

property identity: str

The user’s identity.

property last_name: str

The user’s last name.

property name: str

The user’s full name.

property noticeboard: MyNoticeboard

The user’s noticeboard.

async refresh()

Refresh the user’s data.

property school: School

The user’s school details.

property type: UserType

The type of the logged in user.

class aiocvv.me.Parent(client, **kwargs)

Represents a Classeviva parent, which also has access to the students’ data (refer to Student).

Note

This class is not meant to be manually constructed, but to be used through the ClassevivaClient class.

class aiocvv.me.Student(client, **kwargs)

Represents a Classeviva student.

Note

This class is not meant to be manually constructed, but to be used through the ClassevivaClient class.

property calendar: Calendar

The user’s calendar.

async get_grades(subject=None)

Get the user’s grades.

Parameters:

subject (Optional[Subject]) – The subject to get the grades from.

Return type:

list[Grade]

async get_notes(type=None)

Get the user’s notes.

Return type:

list[Note]

Parameters:

type (NoteType | None)

async get_subjects(include_grades=False)

Get the user’s subjects.

Parameters:

include_grades (bool) – Whether to include the grades for each subject.

Return type:

list[Subject]

Returns:

A list of the user’s subjects.

class aiocvv.me.Teacher(client, **kwargs)

Represents a Classeviva teacher.

Note

This class is not meant to be manually constructed, but to be used through the ClassevivaClient class.

Warning

This class is not yet implemented. You have to use the request() method to manually make requests to the Classeviva API.