feat: adding pyi files to provide type hints in IDEs (#25)

* Rework the results a little bit to account for Mauros missing component.

* Added stub generation script

* classes loading correctly

* WIP (not working)

* Generating a nice stub already

* Already working really really nice!

* Already working really really really nice!

* Only type attribute is generated wrongly

* Different approach, more unified

* Working nicely

* WIP

* WIP (but not working yet)

* results is fine now

* implement type checking

* Working on "courses"

* re-ran everything

* Fix floating point comparisons

* reformat

* Resolving sonar issues

* Resolving sonar issues

Author: svaningelgem

dev/generate_stubs.py

@@ -168,7 +168,7 @@ def download_to_dir(self, target_directory: Path, *, overwrite: bool = False) ->
         return self.download(target_directory / self.filename, overwrite=overwrite)
 
     @overload
-    def download(self, to_file: Path | str, overwrite: bool) -> Path: ...  # noqa: FBT001
+    def download(self, to_file: Path | str, *, overwrite: bool) -> Path: ...
 
     @overload
     def download(self) -> bytes: ...

src/smartschool/courses.py

@@ -0,0 +1,97 @@
+# Auto-generated stub file
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import datetime
+from pathlib import Path
+from typing import overload
+
+from . import objects
+from .objects import Course
+from .session import SessionMixin, Smartschool
+
+class CourseCondensed(objects.CourseCondensed, SessionMixin):
+    session: Smartschool
+    name: str
+    teacher: str
+    url: str
+    id: int
+    platformId: int
+    descr: str
+    icon: str
+    def __init__(
+        self, session: Smartschool, name: str, teacher: str, url: str, id: int | None = None, platformId: int | None = None, descr: str = "", icon: str = ""
+    ): ...
+    def __str__(self): ...
+
+class TopNavCourses(SessionMixin):
+    session: Smartschool
+    def __init__(self, session: Smartschool): ...
+    def __iter__(self) -> Iterator[CourseCondensed]: ...
+
+class Courses(SessionMixin):
+    session: Smartschool
+    def __init__(self, session: Smartschool): ...
+    def __iter__(self) -> Iterator[Course]: ...
+
+class FileItem(SessionMixin):
+    session: Smartschool
+    parent: FolderItem
+    id: int
+    name: str
+    mime_type: str
+    size_kb: float | str
+    last_modified: datetime | str
+    download_url: str | None
+    view_url: str | None
+    def __init__(
+        self,
+        session: Smartschool,
+        parent: FolderItem,
+        id: int,
+        name: str,
+        mime_type: str,
+        size_kb: float | str,
+        last_modified: datetime | str,
+        download_url: str | None = None,
+        view_url: str | None = None,
+    ): ...
+    def download_to_dir(self, target_directory: Path, overwrite: bool = False) -> Path: ...
+    @overload
+    def download(self, to_file: Path | str, *, overwrite: bool) -> Path: ...
+    @overload
+    def download(self) -> bytes: ...
+    def download(self, to_file: Path | str | None = None, *, overwrite: bool = False) -> bytes | Path: ...
+
+class InternetShortcut(FileItem):
+    session: Smartschool
+    parent: FolderItem
+    id: int
+    name: str
+    mime_type: str
+    size_kb: float | str
+    last_modified: datetime | str
+    download_url: str | None
+    view_url: str | None
+    link: str
+    def __init__(
+        self,
+        session: Smartschool,
+        parent: FolderItem,
+        id: int,
+        name: str,
+        mime_type: str,
+        size_kb: float | str,
+        last_modified: datetime | str,
+        download_url: str | None = None,
+        view_url: str | None = None,
+        link: str = "",
+    ): ...
+
+class FolderItem(SessionMixin):
+    session: Smartschool
+    parent: FolderItem | None
+    course: CourseCondensed
+    name: str
+    browse_url: str | None
+    def __init__(self, session: Smartschool, parent: FolderItem | None, course: CourseCondensed, name: str, browse_url: str | None = None): ...

src/smartschool/courses.pyi

@@ -113,8 +113,12 @@ class Component:
     abbreviation: String
 
 
-Teacher = _User
-Student = _User
+@dataclass
+class Teacher(_User): ...
+
+
+@dataclass
+class Student(_User): ...
 
 
 @dataclass
@@ -190,7 +194,7 @@ class ResultDetails:
 class CourseCondensed:
     name: String
     teacher: String
-    url: Url
+    url: Url = Field()
 
     id: int = Field(repr=False, default=None)
     platformId: int = Field(repr=False, default=None)

src/smartschool/objects.py

@@ -1,13 +1,20 @@
-from collections.abc import Iterable, Iterator
+from __future__ import annotations
+
+from collections.abc import Iterable
 from dataclasses import dataclass
 from itertools import count
 
 from . import objects
 
 __all__ = ["Results"]
 
+from typing import TYPE_CHECKING
+
 from .session import SessionMixin
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
 RESULTS_PER_PAGE = 50
 
 

src/smartschool/results.py

@@ -0,0 +1,55 @@
+# Auto-generated stub file
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from datetime import datetime
+from typing import Literal
+
+from . import objects
+from .objects import Component, Course, Feedback, FeedbackFull, Period, ResultDetails, ResultGraphic, Teacher
+from .session import SessionMixin, Smartschool
+
+class Result(objects.Result, SessionMixin):
+    session: Smartschool
+    identifier: str
+    type: Literal["normal"]
+    name: str
+    graphic: ResultGraphic
+    date: datetime
+    gradebookOwner: Teacher
+    component: Component | None
+    courses: list[Course]
+    period: Period
+    feedback: list[Feedback]
+    feedbacks: list[FeedbackFull]
+    availabilityDate: datetime
+    isPublished: bool
+    doesCount: bool
+    deleted: bool
+    details: ResultDetails | None
+    def __init__(
+        self,
+        session: Smartschool,
+        identifier: str,
+        type: Literal["normal"],
+        name: str,
+        graphic: ResultGraphic,
+        date: datetime,
+        gradebookOwner: Teacher,
+        component: Component | None,
+        courses: list[Course],
+        period: Period,
+        feedback: list[Feedback],
+        feedbacks: list[FeedbackFull],
+        availabilityDate: datetime,
+        isPublished: bool,
+        doesCount: bool,
+        deleted: bool = False,
+        details: ResultDetails | None = None,
+    ): ...
+    def __getattribute__(self, name: str): ...
+
+class Results(SessionMixin, Iterable[Result]):
+    session: Smartschool
+    def __init__(self, session: Smartschool): ...
+    def __iter__(self) -> Iterator[Result]: ...

src/smartschool/results.pyi

@@ -1,5 +1,7 @@
 from pathlib import Path
 
+import pytest
+
 from smartschool import Results, Smartschool
 
 
@@ -13,8 +15,8 @@ def test_results_normal_flow(mocker, session: Smartschool):
     result = sut[0]
     assert result.name == "Repetitie hoofdstuk 1"
     assert result.graphic.total_points == 18
-    assert result.graphic.achieved_points == 13.5
-    assert result.graphic.percentage == 0.75
+    assert result.graphic.achieved_points == pytest.approx(13.5)
+    assert result.graphic.percentage == pytest.approx(0.75)
 
     assert result.details is not None
     assert result.details.class_.name == "3ENW"
@@ -24,7 +26,9 @@ def test_mauro_results(session: Smartschool, requests_mock):
     component_file = Path(__file__).parent / "requests/get/results/api/v1/evaluations/mauro_component.json"
     requests_mock.get("https://site/results/api/v1/evaluations/?pageNumber=1&itemsOnPage=50", content=component_file.read_bytes())
     sut = list(Results(session))
+
     assert len(sut) == 1
+
     result = sut[0]
     assert result.graphic.color == "olive"
     assert result.component is None