classcharts-api 1.0.0__tar.gz

classcharts_api-1.0.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2022 James Cook
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

classcharts_api-1.0.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: classcharts-api
+Version: 1.0.0
+Summary: Async Python wrapper for the ClassCharts API
+License: ISC
+Keywords: classcharts,school,api,home-assistant
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: aioresponses>=0.7; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file

classcharts_api-1.0.0/README.md

@@ -0,0 +1,38 @@
+# classcharts-api
+
+A Python port of [classcharts-api-js](https://github.com/classchartsapi/classcharts-api-js) by James Cook.
+
+Provides an async Python client for the ClassCharts parent and student APIs.
+
+## Installation
+
+```bash
+pip install classcharts-api
+```
+
+## Usage
+
+```python
+import asyncio
+from classcharts_api import ParentClient
+
+async def main():
+    async with ParentClient("email@example.com", "password") as client:
+        await client.login()
+        pupils = client.pupils
+        homeworks = await client.get_homeworks_for_each_pupil(
+            display_date="due_date",
+            from_date="2026-01-01",
+            to_date="2026-07-01",
+        )
+        for pupil_id, resp in homeworks.items():
+            print(f"Pupil {pupil_id}: {len(resp['data'])} homework items")
+
+asyncio.run(main())
+```
+
+## License
+
+ISC License — see [LICENSE](LICENSE).
+
+This project is a Python port of [classcharts-api-js](https://github.com/classchartsapi/classcharts-api-js), copyright (c) 2022 James Cook, used under the ISC License.

classcharts_api-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "classcharts-api"
+version = "1.0.0"
+description = "Async Python wrapper for the ClassCharts API"
+license = { text = "ISC" }
+requires-python = ">=3.11"
+keywords = ["classcharts", "school", "api", "home-assistant"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: ISC License (ISCL)",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "aioresponses>=0.7",
+    "pytest-cov>=5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

classcharts_api-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

classcharts_api-1.0.0/src/classcharts_api/__init__.py

@@ -0,0 +1,14 @@
+"""ClassCharts API Python wrapper."""
+
+from .parent_client import ParentClient
+from .student_client import StudentClient
+from .exceptions import ClassChartsAuthError, ClassChartsApiError
+from . import models
+
+__all__ = [
+    "ParentClient",
+    "StudentClient",
+    "ClassChartsAuthError",
+    "ClassChartsApiError",
+    "models",
+]

classcharts_api-1.0.0/src/classcharts_api/base_client.py

@@ -0,0 +1,336 @@
+"""Base async client — shared logic for both ParentClient and StudentClient.
+
+Mirrors src/core/baseClient.ts from classcharts-api-js.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from abc import ABC, abstractmethod
+from typing import Any
+
+import aiohttp
+
+from .const import PING_INTERVAL
+from .exceptions import ClassChartsApiError
+
+
+class BaseClient(ABC):
+    """Shared async HTTP client for ClassCharts."""
+
+    def __init__(self, api_base: str) -> None:
+        self._api_base = api_base
+        self.student_id: int = 0
+        self.session_id: str = ""
+        self.auth_cookies: list[str] = []
+        self._last_ping: float = 0.0
+        self._session: aiohttp.ClientSession | None = None
+
+    # ------------------------------------------------------------------
+    # Session management
+    # ------------------------------------------------------------------
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def close(self) -> None:
+        """Close the underlying aiohttp session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self) -> "BaseClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    @abstractmethod
+    async def login(self) -> None:
+        """Authenticate with ClassCharts and store session credentials."""
+
+    # ------------------------------------------------------------------
+    # Session revalidation (ping)
+    # ------------------------------------------------------------------
+
+    async def get_new_session_id(self) -> None:
+        """Revalidate the session ID.
+
+        Called automatically when the session is older than PING_INTERVAL
+        seconds, and immediately after login for student clients.
+        Mirrors getNewSessionId() in baseClient.ts.
+        """
+        data = aiohttp.FormData()
+        data.add_field("include_data", "true")
+        response = await self._make_authed_request(
+            f"{self._api_base}/ping",
+            method="POST",
+            data=data,
+            revalidate_token=False,
+        )
+        self.session_id = response["meta"]["session_id"]
+        self._last_ping = time.monotonic()
+
+    # ------------------------------------------------------------------
+    # Core request helper
+    # ------------------------------------------------------------------
+
+    async def _make_authed_request(
+        self,
+        url: str,
+        method: str = "GET",
+        data: Any = None,
+        params: dict[str, str] | None = None,
+        revalidate_token: bool = True,
+    ) -> dict[str, Any]:
+        """Make an authenticated request to the ClassCharts API.
+
+        Mirrors makeAuthedRequest() in baseClient.ts.
+        """
+        if not self.session_id:
+            raise ClassChartsApiError("No session ID — call login() first")
+
+        if revalidate_token and self._last_ping:
+            elapsed = time.monotonic() - self._last_ping
+            if elapsed + 5 > PING_INTERVAL:
+                await self.get_new_session_id()
+
+        headers = {
+            "Cookie": "; ".join(c.split(";")[0] for c in self.auth_cookies),
+            "Authorization": f"Basic {self.session_id}",
+            "User-Agent": "classcharts-api https://github.com/classchartsapi/classcharts-api-js",
+        }
+
+        session = self._get_session()
+        async with session.request(
+            method,
+            url,
+            headers=headers,
+            data=data,
+            params=params,
+        ) as resp:
+            try:
+                payload: dict[str, Any] = await resp.json(content_type=None)
+            except Exception as exc:
+                text = await resp.text()
+                raise ClassChartsApiError(
+                    f"Error parsing JSON. Response: {text}"
+                ) from exc
+
+        if payload.get("success") == 0:
+            raise ClassChartsApiError(payload.get("error", "Unknown API error"))
+
+        return payload
+
+    # ------------------------------------------------------------------
+    # Shared endpoints
+    # ------------------------------------------------------------------
+
+    async def get_student_info(self) -> dict[str, Any]:
+        """Get general information about the current student.
+
+        Mirrors getStudentInfo() in baseClient.ts.
+        """
+        data = aiohttp.FormData()
+        data.add_field("include_data", "true")
+        return await self._make_authed_request(
+            f"{self._api_base}/ping", method="POST", data=data
+        )
+
+    async def get_activity(
+        self,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        last_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Get the current student's activity (paginated).
+
+        Mirrors getActivity() in baseClient.ts.
+        """
+        params: dict[str, str] = {}
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        if last_id:
+            params["last_id"] = last_id
+        return await self._make_authed_request(
+            f"{self._api_base}/activity/{self.student_id}", params=params
+        )
+
+    async def get_full_activity(
+        self, from_date: str, to_date: str
+    ) -> list[dict[str, Any]]:
+        """Get all activity between two dates, handling pagination automatically.
+
+        Mirrors getFullActivity() in baseClient.ts.
+        """
+        data: list[dict[str, Any]] = []
+        prev_last: str | None = None
+        while True:
+            response = await self.get_activity(
+                from_date=from_date, to_date=to_date, last_id=prev_last
+            )
+            fragment = response.get("data") or []
+            if not fragment:
+                break
+            data.extend(fragment)
+            prev_last = str(fragment[-1]["id"])
+        return data
+
+    async def get_behaviour(
+        self,
+        from_date: str | None = None,
+        to_date: str | None = None,
+    ) -> dict[str, Any]:
+        """Get the current student's behaviour.
+
+        Mirrors getBehaviour() in baseClient.ts.
+        """
+        params: dict[str, str] = {}
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        return await self._make_authed_request(
+            f"{self._api_base}/behaviour/{self.student_id}", params=params
+        )
+
+    async def get_homeworks(
+        self,
+        display_date: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+    ) -> dict[str, Any]:
+        """Get the current student's homeworks.
+
+        Mirrors getHomeworks() in baseClient.ts.
+
+        Args:
+            display_date: "due_date" or "issue_date" (default: "issue_date")
+            from_date: Start date in YYYY-MM-DD format
+            to_date: End date in YYYY-MM-DD format
+        """
+        params: dict[str, str] = {}
+        if display_date:
+            params["display_date"] = display_date
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        return await self._make_authed_request(
+            f"{self._api_base}/homeworks/{self.student_id}", params=params
+        )
+
+    async def get_lessons(self, date: str) -> dict[str, Any]:
+        """Get the current student's lessons for a given date.
+
+        Mirrors getLessons() in baseClient.ts.
+
+        Args:
+            date: Date in YYYY-MM-DD format
+        """
+        return await self._make_authed_request(
+            f"{self._api_base}/timetable/{self.student_id}",
+            params={"date": date},
+        )
+
+    async def get_badges(self) -> dict[str, Any]:
+        """Get the current student's earned badges.
+
+        Mirrors getBadges() in baseClient.ts.
+        """
+        return await self._make_authed_request(
+            f"{self._api_base}/eventbadges/{self.student_id}"
+        )
+
+    async def get_announcements(self) -> dict[str, Any]:
+        """Get the current student's announcements.
+
+        Mirrors getAnnouncements() in baseClient.ts.
+        """
+        return await self._make_authed_request(
+            f"{self._api_base}/announcements/{self.student_id}"
+        )
+
+    async def get_detentions(self) -> dict[str, Any]:
+        """Get the current student's detentions.
+
+        Mirrors getDetentions() in baseClient.ts.
+        """
+        return await self._make_authed_request(
+            f"{self._api_base}/detentions/{self.student_id}"
+        )
+
+    async def get_attendance(
+        self,
+        from_date: str | None = None,
+        to_date: str | None = None,
+    ) -> dict[str, Any]:
+        """Get the current student's attendance.
+
+        Mirrors getAttendance() in baseClient.ts.
+        """
+        params: dict[str, str] = {}
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        return await self._make_authed_request(
+            f"{self._api_base}/attendance/{self.student_id}", params=params
+        )
+
+    async def get_pupil_fields(self) -> dict[str, Any]:
+        """Get the current student's custom fields.
+
+        Mirrors getPupilFields() in baseClient.ts.
+        """
+        return await self._make_authed_request(
+            f"{self._api_base}/customfields/{self.student_id}"
+        )
+
+    async def get_classes(self) -> dict[str, Any]:
+        """Get the classes the current student is enrolled in."""
+        return await self._make_authed_request(
+            f"{self._api_base}/classes/{self.student_id}"
+        )
+
+    async def get_academic_reports(self) -> dict[str, Any]:
+        """List available academic reports for the current student."""
+        return await self._make_authed_request(
+            f"{self._api_base}/getacademicreports"
+        )
+
+    async def get_academic_report(self, report_id: int) -> dict[str, Any]:
+        """Get a specific academic report by ID."""
+        return await self._make_authed_request(
+            f"{self._api_base}/getacademicreport/{report_id}"
+        )
+
+    async def get_report_cards(self) -> dict[str, Any]:
+        """List on-report cards for the current student."""
+        data = aiohttp.FormData()
+        data.add_field("pupil_id", str(self.student_id))
+        return await self._make_authed_request(
+            f"{self._api_base}/getpupilreportcards", method="POST", data=data
+        )
+
+    async def get_report_card(self, report_card_id: int) -> dict[str, Any]:
+        """Get a specific on-report card by ID."""
+        return await self._make_authed_request(
+            f"{self._api_base}/getpupilreportcard/{report_card_id}"
+        )
+
+    async def get_report_card_summary_comment(self, report_card_id: int) -> dict[str, Any]:
+        """Get the summary comment for a specific on-report card."""
+        return await self._make_authed_request(
+            f"{self._api_base}/getpupilreportcardsummarycomment/{report_card_id}"
+        )
+
+    async def get_report_card_target(self, report_card_id: int) -> dict[str, Any]:
+        """Get the target for a specific on-report card."""
+        return await self._make_authed_request(
+            f"{self._api_base}/getpupilreportcardtarget/{report_card_id}"
+        )

classcharts_api-1.0.0/src/classcharts_api/const.py

@@ -0,0 +1,6 @@
+BASE_URL = "https://www.classcharts.com"
+API_BASE_STUDENT = f"{BASE_URL}/apiv2student"
+API_BASE_PARENT = f"{BASE_URL}/apiv2parent"
+
+# Session revalidation interval in seconds (3 minutes)
+PING_INTERVAL = 60 * 3

classcharts_api-1.0.0/src/classcharts_api/exceptions.py

@@ -0,0 +1,6 @@
+class ClassChartsApiError(Exception):
+    """Raised when the ClassCharts API returns an error response."""
+
+
+class ClassChartsAuthError(ClassChartsApiError):
+    """Raised when authentication with ClassCharts fails."""