feat: adding reports integration (#26)

* 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

* Adding reports

* Version bump

* forgotten file

* remove assignment

* Auto-restubbing

* Adding "__all__" & reformat

* Cleanup

* Tests stuff

* Just run everything at once if possible

* Checkout the PR branch, but only on PR

* restubbing needs full poetry environment

* Fail fast

* Cleaning up a bit

* list installed packages

* Run through poetry

Author: svaningelgem

.gitattributes

@@ -1,4 +1,17 @@
+scripts/list_all_agenda text eol=lf
 scripts/list_all_courses text eol=lf
+scripts/list_all_future_tasks text eol=lf
+scripts/list_all_results text eol=lf
+scripts/smartschool_browse_docs text eol=lf
+scripts/smartschool_cache.sqlite text eol=lf
+scripts/smartschool_download_all_documents text eol=lf
 scripts/smartschool_report_on_future_tasks text eol=lf
+scripts/smartschool_report_on_planned_tasks text eol=lf
 scripts/smartschool_report_on_results text eol=lf
-*.py text eol=lf
+
+scripts/smartschool_report_on_future_tasks text eol=lf
+scripts/smartschool_report_on_results text eol=lf
+
+**/*.py text eol=lf
+run text eol=lf
+restub text eol=lf

.github/workflows/tests.yml

@@ -39,6 +39,69 @@ jobs:
       #----------------------------------------------
 
 
+  generate-stubs:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: cache poetry install
+        uses: actions/cache@v4
+        with:
+          path: ~/.local
+          key: poetry-ubuntu-latest-3.11
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-ubuntu-latest-3.11-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install --no-interaction --no-root
+
+      - name: Install ${{ github.event.repository.name }}
+        run: poetry install --no-interaction
+
+      - name: Generate stubs
+        run: poetry run ./restub
+
+      - name: Check for changes
+        id: check-changes
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          
+          if git diff --quiet src/smartschool; then
+            echo "changes_detected=false" >> $GITHUB_OUTPUT
+          else
+            echo "changes_detected=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and push changes
+        if: steps.check-changes.outputs.changes_detected == 'true'
+        run: |
+          git add src/smartschool
+          git commit -m "Auto-update stub files"
+          git push
+
+
   tests:
     strategy:
       fail-fast: false
@@ -90,4 +153,4 @@ jobs:
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

dev/generate_stubs.py

@@ -5,6 +5,7 @@
 
 import argparse
 import ast
+import collections.abc
 import importlib.util
 import inspect
 import re
@@ -59,6 +60,9 @@ def _format_import(annotation: type, current_module: types.ModuleType) -> str:
     if module == "builtins":
         return ""
 
+    if module == "typing" and getattr(collections.abc, name, None) is not None:
+        module = "collections.abc"
+
     current_parts = current_module.__name__.split(".")
     target_parts = module.split(".")
 
@@ -215,6 +219,7 @@ def load_module_from_file(file_path: Path):
 
         spec = importlib.util.spec_from_file_location(full_module_name, file_path)
         if not spec or not spec.loader:
+            logger.warning(f"Failed to load module {full_module_name} from {file_path}")
             return None
 
         module = importlib.util.module_from_spec(spec)
@@ -340,12 +345,12 @@ def generate_stub_from_class_info(class_info: ClassInfo, imports_needed: set, cu
 
     # Add methods
     for method in class_info.methods:
-        stub += _generate_method_stub(method)
+        stub += _generate_method_stub(method, imports_needed, current_module)
 
     return stub + "\n"
 
 
-def _generate_method_stub(method: MethodInfo | str | None) -> str:
+def _generate_method_stub(method: MethodInfo | str | None, imports_needed: set[str], current_module: types.ModuleType) -> str:
     if not method:
         return ""
 
@@ -368,11 +373,14 @@ def _generate_method_stub(method: MethodInfo | str | None) -> str:
         params.append(param_str)
 
     if method.return_annotation and method.return_annotation is not inspect.Signature.empty:
-        return_type = f" -> {method.return_annotation}"
+        if isinstance(method.return_annotation, str):
+            return_type = f" -> {method.return_annotation}"
+        else:
+            return_type = f" -> {format_type_annotation(method.return_annotation, imports_needed, current_module)}"
     else:
         return_type = ""
 
-    return f"    def {method.name}({', '.join(params)}){return_type}: ...\n"
+    return f"    def {method.name}({', '.join(params)},){return_type}: ...\n"
 
 
 def _inject_typechecking_imports(tree: ast.Module, imports: list[str], module: types.ModuleType) -> None:
@@ -405,10 +413,10 @@ def generate_stub_file(python_file: Path) -> str:
     classes, imports, ast_tree = parse_class_ast_info(python_file)
     module = load_module_from_file(python_file)
     if not module:
-        return "# Failed to load module\n"
+        raise ModuleNotFoundError(f"Failed to load module {python_file}")
 
     if not classes:
-        return "# No classes found\n"
+        raise ValueError("No classes found")
 
     _inject_typechecking_imports(ast_tree, imports, module)
 
@@ -418,7 +426,7 @@ def generate_stub_file(python_file: Path) -> str:
         if inspect.isclass(obj) and obj.__module__ == module.__name__:
             classes[obj.__name__].real_class = obj
 
-    imports_needed = set()
+    imports_needed = set(imports)
 
     # Extract data for all classes
     for cls in classes.values():
@@ -442,31 +450,48 @@ def generate_stub_file(python_file: Path) -> str:
 
 def reformat_file(output_file):
     try:
-        subprocess.run(["ruff", "format", str(output_file)], check=True, capture_output=True)
-        subprocess.run(["ruff", "check", "--select", "I,F,E", "--fix", str(output_file)], check=True, capture_output=True)
+        subprocess.run(
+            ["ruff", "format", str(output_file)],
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        subprocess.run(
+            ["ruff", "check", "--select", "I,F,E", "--fix", "--unsafe-fixes", str(output_file)],
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
         logger.info(f"Generated and formatted {output_file}")
     except subprocess.CalledProcessError as e:
         logger.warning(f"Generated {output_file} but ruff formatting failed: {e}")
+        for line in e.output.splitlines():
+            logger.warning(line)
     except FileNotFoundError:
         logger.warning(f"Generated {output_file} but ruff not found - install ruff for formatting")
 
 
 def main():
     parser = argparse.ArgumentParser(description="Generate .pyi stub files")
-    parser.add_argument("python_file", type=Path, help="Python file to analyze")
-    parser.add_argument("-o", "--output", type=Path, help="Output .pyi file")
+    parser.add_argument("python_files", nargs="+", type=Path, help="Python file to analyze")
 
     args = parser.parse_args()
 
-    if not args.python_file.exists():
-        logger.error(f"File {args.python_file} does not exist")
-        return
+    for file in args.python_files:
+        file = file.resolve().absolute()
+        if file.suffix == ".pyi":
+            file = file.with_suffix(".py")
 
-    output_file = args.output or args.python_file.with_suffix(".pyi")
+        if not file.exists():
+            logger.error(f"File {file} does not exist")
+            continue
 
-    stub_content = generate_stub_file(args.python_file)
-    output_file.write_text(stub_content)
-    reformat_file(output_file)
+        stub_content = generate_stub_file(file)
+        output_file = file.with_suffix(".pyi")
+        output_file.write_text(stub_content)
+        reformat_file(output_file)
 
 
 if __name__ == "__main__":

poetry.lock

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "smartschool"
-version = "0.6.0"
+version = "0.7.0"
 description = "Unofficial API interface to the smartschool system."
 authors = ["Steven Van Ingelgem <[email protected]>"]
 readme = "README.md"

pyproject.toml

@@ -0,0 +1,4 @@
+#!/bin/bash -e
+
+pyi_files=$(find src/smartschool -name "*.pyi" -type f)
+python dev/generate_stubs.py $pyi_files

restub

@@ -19,6 +19,7 @@
 )
 from .periods import Periods
 from .planner import ApplicableAssignmentTypes, PlannedElements
+from .reports import Report, Reports
 from .results import Result, Results
 from .session import Smartschool
 from .student_support import StudentSupportLinks
@@ -50,6 +51,8 @@
     "PathCredentials",
     "Periods",
     "PlannedElements",
+    "Report",
+    "Reports",
     "Result",
     "Results",
     "SmartSchoolAuthenticationError",

src/smartschool/__init__.py

@@ -15,24 +15,44 @@ class CourseCondensed(objects.CourseCondensed, SessionMixin):
     name: str
     teacher: str
     url: str
-    id: int
-    platformId: int
+    id: int | None
+    platformId: int | None
     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 = ""
+        self,
+        session: Smartschool,
+        name: str,
+        teacher: str,
+        url: str,
+        id: int | None = None,
+        platformId: int | None = None,
+        descr: str = "",
+        icon: str = "",
+    ): ...
+    def __str__(
+        self,
     ): ...
-    def __str__(self): ...
 
 class TopNavCourses(SessionMixin):
     session: Smartschool
-    def __init__(self, session: Smartschool): ...
-    def __iter__(self) -> Iterator[CourseCondensed]: ...
+    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]: ...
+    def __init__(
+        self,
+        session: Smartschool,
+    ): ...
+    def __iter__(
+        self,
+    ) -> Iterator[Course]: ...
 
 class FileItem(SessionMixin):
     session: Smartschool
@@ -56,7 +76,11 @@ class FileItem(SessionMixin):
         download_url: str | None = None,
         view_url: str | None = None,
     ): ...
-    def download_to_dir(self, target_directory: Path, overwrite: bool = False) -> Path: ...
+    def download_to_dir(
+        self,
+        target_directory: Path,
+        overwrite: bool = False,
+    ) -> Path: ...
     @overload
     def download(self, to_file: Path | str, *, overwrite: bool) -> Path: ...
     @overload
@@ -94,4 +118,11 @@ class FolderItem(SessionMixin):
     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): ...
+    def __init__(
+        self,
+        session: Smartschool,
+        parent: FolderItem | None,
+        course: CourseCondensed,
+        name: str,
+        browse_url: str | None = None,
+    ): ...