Unofficial Python library providing programmatic access to Smartschool's web platform. Access courses, documents, messages, results, agenda, and more through a clean, type-safe API.
Create credentials.yml with your Smartschool credentials:
username: your_username
password: your_password
main_url: your_school.smartschool.be
mfa: your_birthday_or_2fa_secret # YYYY-mm-dd or Google Authenticator secret
# Optional: email configuration for scripts
email_from: [email protected]
email_to:
- [email protected]from smartschool import Smartschool, PathCredentials, Courses
session = Smartschool(PathCredentials())
for course in Courses(session):
print(course.name)- Courses: List all available courses with metadata
- TopNavCourses: Navigation bar courses with full document access
- Document Browser: Navigate course folders and download files
- File Downloads: Support for all file types with automatic extension detection
- Results: Retrieve grades and detailed evaluations with teacher feedback
- Reports: Download official academic reports (PDF format)
- Periods: Academic terms and grading periods
- FutureTasks: Upcoming assignments and deadlines
- PlannedElements: Scheduled assignments and activities from the planner
- Messages: Complete inbox/outbox management with threading support
- Attachments: Download and manage message attachments
- Message Operations: Mark read/unread, archive, delete, apply labels
- SmartschoolLessons: Daily lesson schedules with detailed information
- SmartschoolHours: Class period definitions and timings
- SmartschoolMomentInfos: Detailed lesson content and assignments
- StudentSupportLinks: Access to school support resources and links
from smartschool import Smartschool, PathCredentials
# Automatically searches for credentials.yml in common locations
session = Smartschool(PathCredentials())from smartschool import Smartschool, EnvCredentials
# Uses SMARTSCHOOL_USERNAME, SMARTSCHOOL_PASSWORD, etc.
session = Smartschool(EnvCredentials())from smartschool import Smartschool, AppCredentials
creds = AppCredentials(
username="your_username",
password="your_password",
main_url="school.smartschool.be",
mfa="your_birthday_or_2fa_secret"
)
session = Smartschool(creds)- Birthday verification: Use format
YYYY-mm-dd - Google Authenticator: Requires
pip install smartschool[mfa]
from smartschool import TopNavCourses
from pathlib import Path
# Browse and download course documents
for course in TopNavCourses(session):
print(f"📚 Course: {course.name}")
for item in course.items:
if isinstance(item, FileItem):
# Download individual files
target_dir = Path("downloads") / course.name
item.download_to_dir(target_dir)
print(f" 📄 Downloaded: {item.name}")
elif isinstance(item, FolderItem):
# Navigate folders recursively
print(f" 📁 Folder: {item.name}")
for subitem in item.items:
print(f" - {subitem.name}")from smartschool import Results
# Analyze academic performance
for result in Results(session):
points = result.graphic.achieved_points
total = result.graphic.total_points
percentage = result.graphic.percentage
print(f"📊 {result.name}: {points}/{total} ({percentage:.1%})")
print(f" 📅 Date: {result.date}")
print(f" 👨🏫 Teacher: {result.gradebookOwner.name.startingWithFirstName}")
# Access detailed feedback
if result.feedback:
for fb in result.feedback:
print(f" 💬 {fb.user.name.startingWithFirstName}: {fb.text}")from smartschool import MessageHeaders, Message, BoxType
# Process inbox messages
for header in MessageHeaders(session, box_type=BoxType.INBOX):
if header.unread:
# Get full message content
full_message = Message(session, header.id).get()
print(f"📧 From: {full_message.from_}")
print(f" Subject: {full_message.subject}")
print(f" Body: {full_message.body[:100]}...")
# Download attachments if present
if header.attachment:
from smartschool import Attachments
for attachment in Attachments(session, header.id):
content = attachment.download()
Path(f"attachments/{attachment.name}").write_bytes(content)from smartschool import FutureTasks, PlannedElements
from datetime import datetime
# Track upcoming assignments
print("📋 Upcoming Tasks:")
for day in FutureTasks(session):
print(f"\n📅 {day.date}")
for course in day.courses:
for task in course.items.tasks:
print(f" 📝 {course.course_title}: {task.label}")
print(f" {task.description}")
# Check planned activities
print("\n📅 Planned Activities:")
for element in PlannedElements(session):
start_time = element.period.dateTimeFrom
course_names = [c.name for c in element.courses]
print(f"🎯 {element.name}")
print(f" 📅 {start_time.strftime('%Y-%m-%d %H:%M')}")
print(f" 📚 Courses: {', '.join(course_names)}")from smartschool import SmartschoolLessons, SmartschoolHours
from datetime import date, timedelta
# Get tomorrow's schedule
tomorrow = date.today() + timedelta(days=1)
lessons = SmartschoolLessons(session, timestamp_to_use=tomorrow)
for lesson in lessons:
hour_details = lesson.hour_details
print(f"🕐 {hour_details.start}-{hour_details.end}: {lesson.course}")
print(f" 📍 Room: {lesson.classroom}")
print(f" 👨🏫 Teacher: {lesson.teacher}")
if lesson.subject:
print(f" 📝 Subject: {lesson.subject}")The package includes several command-line utilities:
# Interactive document browser
smartschool_browse_docs
# Bulk download all course documents
smartschool_download_all_documents# Email notifications for new results
smartschool_report_on_results
# Daily task summaries
smartschool_report_on_future_tasks
# Planned assignment alerts
smartschool_report_on_planned_tasksfrom smartschool.exceptions import (
SmartSchoolException,
SmartSchoolAuthenticationError,
SmartSchoolDownloadError,
SmartSchoolParsingError
)
try:
session = Smartschool(PathCredentials())
results = list(Results(session))
except SmartSchoolAuthenticationError:
print("❌ Login failed - check your credentials")
except SmartSchoolDownloadError as e:
print(f"❌ Download failed: {e}")
except SmartSchoolParsingError as e:
print(f"❌ Data parsing error: {e}")
except SmartSchoolException as e:
print(f"❌ General API error: {e}")git clone https://github.com/svaningelgem/smartschool.git
cd smartschool
# Using conda/mamba (recommended)
mamba create -n smartschool python=3.11
mamba activate smartschool
# Install with poetry
pip install poetry
poetry install
# Run tests
poetry run pytest
# Code formatting and linting
poetry run ruff format .
poetry run ruff check .- Stub Generation:
./restub- Auto-generates.pyifiles - Testing: pytest with coverage reporting
- Linting: ruff for formatting and code quality
- CI/CD: GitHub Actions with automated PyPI publishing
Smartschool: Main session handler with automatic authenticationPathCredentials,EnvCredentials,AppCredentials: Authentication methods
Courses,TopNavCourses: Course information and navigationResults: Grade and evaluation managementReports: Official academic reportsPeriods: Academic term information
MessageHeaders,Message: Email-like messaging systemAttachments: File attachment handlingBoxType,MessageLabel: Message organization
FutureTasks: Assignment deadlines and tasksPlannedElements: Calendar events and activitiesSmartschoolLessons,SmartschoolHours: Daily schedules
FileItem,FolderItem,InternetShortcut: Document typesDocumentOrFolderItem: Union type for navigation
StudentSupportLinks: School support resources
- Python: 3.11+
- Core Dependencies: requests, beautifulsoup4, pydantic, pyyaml, logprise
- Optional: pyotp (for 2FA support)
GNU General Public License v3.0
Contributions welcome! Please ensure:
- Tests pass:
poetry run pytest - Code is formatted:
poetry run ruff format . - Linting passes:
poetry run ruff check . - Type stubs are updated:
./restub
- Documentation: Check docstrings and type hints
- Issues: GitHub Issues
- API Changes: See CHANGELOG.md