schoolapp-api 2.0.0__tar.gz

schoolapp_api-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Aferiad Kamal]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

schoolapp_api-2.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: schoolapp-api
+Version: 2.0.0
+Summary: Professional client for interacting with the School App API
+Author: Aferiad Kamal
+License: MIT
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.9.0
+Dynamic: license-file
+
+# School App Client - Refactored
+
+Clean, organized structure for the School App client with proper separation of concerns.
+
+## 📁 Project Structure
+
+```
+├── http_client.py         # Base HTTP client (GET/POST requests, cookie management)
+├── auth.py                # Authentication & CSRF token handling
+├── school_app_client.py   # Main API client (combines everything)
+└── example_usage.py       # Usage example
+```
+
+## 🎯 Architecture
+
+### 1. **http_client.py** - HTTP Layer
+- Handles raw HTTP operations (GET/POST)
+- Cookie jar and session management
+- Common headers configuration
+- Error handling for network requests
+
+### 2. **auth.py** - Authentication Layer
+- Login flow management
+- CSRF token extraction and updates
+- Session state tracking
+- Decoupled from HTTP implementation
+
+### 3. **school_app_client.py** - API Layer
+- High-level API methods (`get_filieres()`, `get_modules()`)
+- Orchestrates HTTP client and auth manager
+- Business logic for School App endpoints
+
+## 🚀 Usage
+
+```python
+from school_app_client import SchoolAppClient
+
+# Initialize
+client = SchoolAppClient()
+
+# Login
+client.login("your.email@example.com", "password")
+
+# Fetch data
+filieres = client.get_filieres()
+modules = client.get_modules(niveau="1A", filiere="API-MPT", semestre="S1")
+
+# If you encounter 403 errors, force CSRF refresh
+modules = client.get_modules(
+    niveau="1A", 
+    filiere="API-MPT", 
+    semestre="S1",
+    refresh_csrf=True
+)
+```
+
+## ✨ Benefits of This Structure
+
+- **Separation of Concerns**: Each module has a single responsibility
+- **Testability**: Easy to mock and unit test each layer
+- **Maintainability**: Changes in one layer don't affect others
+- **Extensibility**: Easy to add new endpoints or authentication methods
+- **Reusability**: HTTP client can be used for other projects
+
+## 🎯 Key Features
+
+- **Automatic CSRF Management**: CSRF tokens are automatically refreshed from page content
+- **Session Persistence**: Cookie-based session management keeps you logged in
+- **Smart Error Handling**: Detects 403 errors and suggests CSRF refresh
+- **Optional CSRF Force Refresh**: Use `refresh_csrf=True` to force token refresh before requests
+- **Clean Separation**: HTTP, Auth, and API layers are completely decoupled
+
+## 🔧 Potential Extensions
+
+- Add logging module
+- Implement response parsers (HTML → structured data)
+- Add caching layer
+- Create async version using `aiohttp`
+- Add retry logic with exponential backoff

schoolapp_api-2.0.0/README.md

@@ -0,0 +1,79 @@
+# School App Client - Refactored
+
+Clean, organized structure for the School App client with proper separation of concerns.
+
+## 📁 Project Structure
+
+```
+├── http_client.py         # Base HTTP client (GET/POST requests, cookie management)
+├── auth.py                # Authentication & CSRF token handling
+├── school_app_client.py   # Main API client (combines everything)
+└── example_usage.py       # Usage example
+```
+
+## 🎯 Architecture
+
+### 1. **http_client.py** - HTTP Layer
+- Handles raw HTTP operations (GET/POST)
+- Cookie jar and session management
+- Common headers configuration
+- Error handling for network requests
+
+### 2. **auth.py** - Authentication Layer
+- Login flow management
+- CSRF token extraction and updates
+- Session state tracking
+- Decoupled from HTTP implementation
+
+### 3. **school_app_client.py** - API Layer
+- High-level API methods (`get_filieres()`, `get_modules()`)
+- Orchestrates HTTP client and auth manager
+- Business logic for School App endpoints
+
+## 🚀 Usage
+
+```python
+from school_app_client import SchoolAppClient
+
+# Initialize
+client = SchoolAppClient()
+
+# Login
+client.login("your.email@example.com", "password")
+
+# Fetch data
+filieres = client.get_filieres()
+modules = client.get_modules(niveau="1A", filiere="API-MPT", semestre="S1")
+
+# If you encounter 403 errors, force CSRF refresh
+modules = client.get_modules(
+    niveau="1A", 
+    filiere="API-MPT", 
+    semestre="S1",
+    refresh_csrf=True
+)
+```
+
+## ✨ Benefits of This Structure
+
+- **Separation of Concerns**: Each module has a single responsibility
+- **Testability**: Easy to mock and unit test each layer
+- **Maintainability**: Changes in one layer don't affect others
+- **Extensibility**: Easy to add new endpoints or authentication methods
+- **Reusability**: HTTP client can be used for other projects
+
+## 🎯 Key Features
+
+- **Automatic CSRF Management**: CSRF tokens are automatically refreshed from page content
+- **Session Persistence**: Cookie-based session management keeps you logged in
+- **Smart Error Handling**: Detects 403 errors and suggests CSRF refresh
+- **Optional CSRF Force Refresh**: Use `refresh_csrf=True` to force token refresh before requests
+- **Clean Separation**: HTTP, Auth, and API layers are completely decoupled
+
+## 🔧 Potential Extensions
+
+- Add logging module
+- Implement response parsers (HTML → structured data)
+- Add caching layer
+- Create async version using `aiohttp`
+- Add retry logic with exponential backoff

schoolapp_api-2.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "schoolapp-api"
+version = "2.0.0"
+description = "Professional client for interacting with the School App API"
+readme = "README.md"
+requires-python = ">=3.7"
+license = {text = "MIT"}
+authors = [
+    {name = "Aferiad Kamal"}
+]
+dependencies = [
+    "beautifulsoup4>=4.9.0",
+]
+
+[tool.setuptools]
+packages = ["schoolapp_api", "schoolapp_api.managers", "schoolapp_api.parsers", "schoolapp_api.types"]

schoolapp_api-2.0.0/schoolapp_api/__init__.py

@@ -0,0 +1,10 @@
+"""
+Professional School App API Client
+"""
+
+from .school_app_client import SchoolAppClient
+from .http_client import HTTPClient
+from .auth import AuthManager
+
+__version__ = "2.0.0"
+__all__ = ["SchoolAppClient", "HTTPClient", "AuthManager"]

schoolapp_api-2.0.0/schoolapp_api/auth.py

@@ -0,0 +1,81 @@
+"""
+Authentication and CSRF token management
+"""
+import re
+import logging
+from schoolapp_api.constants import LOGIN_URL
+
+logger = logging.getLogger(__name__)
+
+class AuthManager:
+    """Handles authentication and CSRF token management"""
+    
+    def __init__(self, http_client, base_url):
+        self.http_client = http_client
+        self.base_url = base_url
+        self.login_url = LOGIN_URL
+        self.csrf_token = None
+        self.logged_in = False
+    
+    @staticmethod
+    def extract_csrf_token(html_content):
+        """Extract CSRF token from HTML content"""
+        match = re.search(r'name="_csrf"\s+value="([^"]+)"', html_content)
+        return match.group(1) if match else None
+    
+    def update_csrf_token(self, html_content):
+        """Update CSRF token from HTML content"""
+        new_csrf = self.extract_csrf_token(html_content)
+        if new_csrf:
+            self.csrf_token = new_csrf
+            return True
+        return False
+    
+    def login(self, email, password):
+        """Login and maintain session"""
+        if self.logged_in:
+            logger.info("Already logged in!")
+            return True
+        
+        logger.info("Fetching login page...")
+        code, url, content = self.http_client.get(self.login_url)
+        
+        if not content or not self.update_csrf_token(content):
+            logger.error("Failed to fetch login page or retrieve CSRF token.")
+            return False
+        
+        logger.info(f"Got CSRF token, logging in...")
+        login_data = {
+            '_csrf': self.csrf_token,
+            'email': email,
+            'password': password
+        }
+        
+        code, response_url, content = self.http_client.post(
+            self.login_url, 
+            login_data, 
+            referer=self.login_url
+        )
+        
+        if response_url and ("/login" in response_url and "error" in response_url):
+            logger.error("Login failed! Invalid credentials.")
+            return False
+        
+        logger.info("Login successful!")
+        self.logged_in = True
+        return True
+    
+    def is_logged_in(self):
+        """Check if currently logged in"""
+        return self.logged_in
+    
+    def refresh_csrf_from_url(self, url):
+        """Fetch a fresh CSRF token from a specific page"""
+        try:
+            code, response_url, content = self.http_client.get(url)
+            if content and self.update_csrf_token(content):
+                return True
+            return False
+        except Exception as e:
+            logger.warning(f"CSRF refresh warning: {e}")
+            return False

schoolapp_api-2.0.0/schoolapp_api/constants.py

@@ -0,0 +1,38 @@
+"""
+Centralized constants for the School App API
+"""
+
+BASE_URL = "https://schoolapp.ensam-umi.ac.ma"
+
+# Endpoints
+LOGIN_URL = f"{BASE_URL}/login"
+INDEX_URL = f"{BASE_URL}/index"
+MODULES_URL = f"{BASE_URL}/plan-etudes-view/modules"
+FILIERES_URL = f"{BASE_URL}/plan-etudes-view/filieres"
+
+# Student Grade Endpoints
+CURRENT_ELEM_URL = f"{BASE_URL}/student/noteselem-encours"
+CURRENT_MOD_URL = f"{BASE_URL}/student/notesmod-encours"
+ELEM_URL = f"{BASE_URL}/student/noteselem"
+MOD_URL = f"{BASE_URL}/student/notesmod"
+ANNEES_URL = f"{BASE_URL}/student/notesannee"
+SEMESTRES_URL = f"{BASE_URL}/student/notessem"
+
+# Absence and Sanctions Endpoints
+ABSENCES_URL = f"{BASE_URL}/student/absence/bilan"
+SANCTIONS_URL = f"{BASE_URL}/student/absence/sanctions"
+
+# Stats Endpoints
+EVAL_STAT_URL = f"{BASE_URL}/notes-stat/elemevalsat"
+MOD_STAT_URL = f"{BASE_URL}/notes-stat/modsat"
+ANNEE_STAT_URL = f"{BASE_URL}/notes-stat/anneesat"
+SEM_STAT_URL = f"{BASE_URL}/notes-stat/semsat"
+
+# Default Headers
+DEFAULT_HEADERS = {
+    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7',
+    'Accept-Language': 'en-US,en;q=0.9,fr;q=0.8',
+    'Connection': 'keep-alive',
+    'Upgrade-Insecure-Requests': '1'
+}

schoolapp_api-2.0.0/schoolapp_api/http_client.py

@@ -0,0 +1,67 @@
+"""
+HTTP Client with session and cookie management
+"""
+import urllib.request
+import urllib.parse
+import urllib.error
+import http.cookiejar
+import logging
+
+from schoolapp_api.constants import DEFAULT_HEADERS
+
+logger = logging.getLogger(__name__)
+
+class HTTPClient:
+    """Base HTTP client for making authenticated requests"""
+    
+    def __init__(self, base_url):
+        self.base_url = base_url
+        self.cookie_jar = http.cookiejar.CookieJar()
+        opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(self.cookie_jar))
+        urllib.request.install_opener(opener)
+        self.headers = DEFAULT_HEADERS.copy()
+    
+    def get(self, url, params=None):
+        """Perform GET request"""
+        try:
+            if params:
+                query_string = urllib.parse.urlencode(params, doseq=True)
+                separator = "&" if "?" in url else "?"
+                url = f"{url}{separator}{query_string}"
+
+            req = urllib.request.Request(url, headers=self.headers, method="GET")
+
+            with urllib.request.urlopen(req) as response:
+                code = response.getcode()
+                response_url = response.geturl()
+                content = response.read().decode("utf-8")
+                return code, response_url, content
+
+        except urllib.error.HTTPError as e:
+            logger.error(f"HTTP Error {e.code}: {e.reason}")
+            return e.code, None, None
+        except Exception as e:
+            logger.error(f"GET Error: {e}")
+            return None, None, None
+    
+    def post(self, url, data, referer=None):
+        """Perform POST request"""
+        try:
+            encoded_data = urllib.parse.urlencode(data).encode('utf-8')
+            req = urllib.request.Request(url, data=encoded_data, headers=self.headers)
+            req.add_header('Content-Type', 'application/x-www-form-urlencoded')
+            req.add_header('Origin', self.base_url)
+            if referer:
+                req.add_header('Referer', referer)
+            
+            with urllib.request.urlopen(req) as response:
+                code = response.getcode()
+                response_url = response.geturl()
+                content = response.read().decode('utf-8')
+                return code, response_url, content
+        except urllib.error.HTTPError as e:
+            logger.error(f"HTTP Error {e.code}: {e.reason}")
+            return e.code, None, None
+        except Exception as e:
+            logger.error(f"POST Error: {e}")
+            return None, None, None

schoolapp_api-2.0.0/schoolapp_api/managers/__init__.py

@@ -0,0 +1,11 @@
+from .grades_manager import GradesManager
+from .attendance_manager import AttendanceManager
+from .profile_manager import ProfileManager
+from .course_manager import CourseManager
+
+__all__ = [
+    'GradesManager',
+    'AttendanceManager',
+    'ProfileManager',
+    'CourseManager'
+]

schoolapp_api-2.0.0/schoolapp_api/managers/attendance_manager.py

@@ -0,0 +1,15 @@
+"""
+Manager for attendance and sanctions
+"""
+from schoolapp_api.managers.base_manager import BaseManager
+from schoolapp_api.constants import ABSENCES_URL, SANCTIONS_URL
+from schoolapp_api import parsers
+
+class AttendanceManager(BaseManager):
+    """Handles fetching of absences and sanctions"""
+
+    def get_absences(self):
+        return self.get_json_or_parse(ABSENCES_URL, parsers.absences)
+
+    def get_sanctions(self):
+        return self.get_json_or_parse(SANCTIONS_URL, parsers.sanctions)

schoolapp_api-2.0.0/schoolapp_api/managers/base_manager.py

@@ -0,0 +1,36 @@
+"""
+Base client for shared manager logic
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+class BaseManager:
+    """Base class for all managers"""
+    
+    def __init__(self, client):
+        self.client = client
+        self.http_client = client.http_client
+        self.auth = client.auth
+
+    def ensure_logged_in(self):
+        """Ensures the client is logged in before making requests"""
+        if not self.auth.is_logged_in():
+            logger.error("Not logged in! Call login() first.")
+            return False
+        return True
+
+    def get_json_or_parse(self, url, parser, params=None, refresh_csrf=True):
+        """Helper to fetch content, update CSRF, and parse"""
+        if not self.ensure_logged_in():
+            return None
+            
+        code, url, content = self.http_client.get(url, params=params)
+        
+        if not content:
+            return None
+            
+        if refresh_csrf:
+            self.auth.update_csrf_token(content)
+            
+        return parser.parse(content)

schoolapp_api-2.0.0/schoolapp_api/managers/course_manager.py

@@ -0,0 +1,45 @@
+"""
+Manager for courses and study plans
+"""
+import logging
+from schoolapp_api.managers.base_manager import BaseManager
+from schoolapp_api.constants import MODULES_URL
+from schoolapp_api import parsers
+
+logger = logging.getLogger(__name__)
+
+class CourseManager(BaseManager):
+    """Handles fetching of modules and study plans"""
+
+    def get_modules(self, niveau, filiere, semestre, refresh_csrf=False):
+        """Fetch modules for specific niveau/filiere/semestre"""
+        if not self.ensure_logged_in():
+            return None
+        
+        # Always GET modules page first to refresh CSRF token
+        logger.info("Opening modules page to refresh state...")
+        code, url, content = self.http_client.get(MODULES_URL)
+        
+        if not content:
+            return None
+        
+        self.auth.update_csrf_token(content)
+        
+        if refresh_csrf:
+            self.auth.refresh_csrf_from_url(MODULES_URL)
+        
+        logger.info(f"Fetching modules for {niveau} {filiere} {semestre}...")
+        modules_data = {
+            '_csrf': self.auth.csrf_token,
+            'niveau': niveau,
+            'filiere': filiere,
+            'semestre': semestre
+        }
+        
+        code, response_url, content = self.http_client.post(
+            MODULES_URL,
+            modules_data,
+            referer=MODULES_URL
+        )
+        
+        return parsers.modules.parse(content)

schoolapp_api-2.0.0/schoolapp_api/managers/grades_manager.py

@@ -0,0 +1,35 @@
+"""
+Manager for grades and academic results
+"""
+from schoolapp_api.managers.base_manager import BaseManager
+from schoolapp_api.constants import (
+    CURRENT_ELEM_URL, CURRENT_MOD_URL, ELEM_URL, MOD_URL, 
+    ANNEES_URL, SEMESTRES_URL
+)
+from schoolapp_api import parsers, types
+
+class GradesManager(BaseManager):
+    """Handles fetching of grades for elements, modules, years, and semesters"""
+
+    def get_element_notes(self, current=False):
+        url = CURRENT_ELEM_URL if current else ELEM_URL
+        data = self.get_json_or_parse(url, parsers.note_elem)
+        return [types.Element(self.client, item) for item in data] if data else []
+
+    def get_module_notes(self, current=False):
+        url = CURRENT_MOD_URL if current else MOD_URL
+        data = self.get_json_or_parse(url, parsers.note_mod)
+        # Note: In the original code, get_mod_note returned types.Element, 
+        # but it should probably return types.Module if it's for modules.
+        # Looking at original school_app_client.py:L272 it used types.Element.
+        # I'll stick to what was there but maybe use Module if appropriate.
+        # types/Module.py exists.
+        return [types.Module(self.client, item) for item in data] if data else []
+
+    def get_years(self):
+        data = self.get_json_or_parse(ANNEES_URL, parsers.annees)
+        return [types.Annee(self.client, item) for item in data] if data else []
+
+    def get_semesters(self):
+        data = self.get_json_or_parse(SEMESTRES_URL, parsers.semestres)
+        return [types.Semestre(self.client, item) for item in data] if data else []

schoolapp_api-2.0.0/schoolapp_api/managers/profile_manager.py

@@ -0,0 +1,15 @@
+"""
+Manager for student profile and programs
+"""
+from schoolapp_api.managers.base_manager import BaseManager
+from schoolapp_api.constants import INDEX_URL, FILIERES_URL
+from schoolapp_api import parsers
+
+class ProfileManager(BaseManager):
+    """Handles fetching of student profile and filieres"""
+
+    def get_profile(self):
+        return self.get_json_or_parse(INDEX_URL, parsers.profile)
+
+    def get_filieres(self):
+        return self.get_json_or_parse(FILIERES_URL, parsers.filieres)

schoolapp_api-2.0.0/schoolapp_api/parsers/__init__.py

@@ -0,0 +1,6 @@
+"""
+Parsers for School App API HTML content
+"""
+from . import absences, annees, filieres, modules, note_elem, note_mod, profile, sanctions, semestres, stats
+
+__all__ = ["absences", "annees", "filieres", "modules", "note_elem", "note_mod", "profile", "sanctions", "semestres", "stats"]

schoolapp_api-2.0.0/schoolapp_api/parsers/absences.py

@@ -0,0 +1,45 @@
+from bs4 import BeautifulSoup
+import re
+
+def parse(html_content):
+    """Parse HTML content containing absence details."""
+    soup = BeautifulSoup(html_content, 'html.parser')
+    result = {"summary": [], "details": []}
+    
+    tables = soup.find_all('table', class_='table table-striped table-sm')
+    if len(tables) < 2:
+        return result
+    
+    # Summary
+    for row in tables[0].find_all('tr')[1:]:
+        cells = row.find_all('td')
+        if len(cells) >= 4:
+            result["summary"].append({
+                "CodeElem": cells[0].get_text(strip=True),
+                "Intitule": cells[1].get_text(strip=True),
+                "Non_Justifiee": int(cells[2].get_text(strip=True) or 0),
+                "Justifiee": int(cells[3].get_text(strip=True) or 0)
+            })
+            
+    # Details
+    for row in tables[1].find_all('tr')[1:]:
+        cells = row.find_all('td')
+        if len(cells) >= 5:
+            result["details"].append({
+                "Element": cells[0].get_text(strip=True),
+                "Date": cells[1].get_text(strip=True),
+                "Seance": cells[2].get_text(strip=True),
+                "Justif": cells[3].get_text(strip=True).lower() == "true",
+                "Remarques": cells[4].get_text(strip=True)
+            })
+            
+    # Semester info
+    alerts = soup.find_all('div', class_='alert alert-info')
+    for alert in alerts:
+        text = alert.get_text()
+        if "semestre" in text.lower():
+            match = re.search(r'S\d', text)
+            if match:
+                result["semestre"] = match.group()
+    
+    return result

schoolapp_api-2.0.0/schoolapp_api/parsers/annees.py

@@ -0,0 +1,37 @@
+from bs4 import BeautifulSoup
+
+def parse(html_content):
+    """Parse HTML content containing annual averages."""
+    soup = BeautifulSoup(html_content, 'html.parser')
+    table = soup.find('table', class_='table table-striped table-sm') or soup.find('table')
+    
+    if not table:
+        return []
+    
+    headers = [th.get_text(strip=True) for th in table.find_all('th')]
+    if len(headers) < 9:
+        headers = ["Niveau", "Filiere", "AU", "Statut", "Moy Année", "PJ", "Decision", "Classement", "Releve de Notes"]
+    
+    data = []
+    tbody = table.find('tbody') or table
+    
+    for row in tbody.find_all('tr'):
+        cells = row.find_all('td')
+        if len(cells) >= 9:
+            row_data = {}
+            for i, cell in enumerate(cells[:9]):
+                if i == 8: # Download link
+                    link = cell.find('a')
+                    row_data[headers[i]] = link.get('href') if link else cell.get_text(strip=True)
+                else:
+                    val = cell.get_text(strip=True)
+                    if headers[i] in ["Moy Année", "PJ"]:
+                        try:
+                            row_data[headers[i]] = float(val) if val and val != "--" else None
+                        except ValueError:
+                            row_data[headers[i]] = val
+                    else:
+                        row_data[headers[i]] = val
+            data.append(row_data)
+            
+    return data