luzapp 0.2.0

Luzapp management library

pyluzapp

Python library for reading and writing LuzApp schedule repositories.

A LuzApp schedule repository is a git-tracked directory of XML files that LuzApp uses to store and sync school timetables. This library lets you read, modify, and export those schedules from Python without running LuzApp itself.

Installation

# TODO: Add local repository instructions
pip install luzapp

Or with uv:

# TODO: Add local repository instructions
uv add luzapp

Requires Python 3.13+.

Quick start

from luzapp import ScheduleRepo

repo = ScheduleRepo("/path/to/school-repo")

# List available weeks
print(repo.list_weeks())  # [1, 2, 3, ...]

# Load lessons for a week
lessons = repo.get_lessons(week_number=1)
for lesson in lessons:
    print(lesson.start_time, lesson.array, lesson.display)

# Export weeks 1–3 to an iCalendar file
ics = repo.export_ics([1, 2, 3])
with open("schedule.ics", "w", encoding="utf-8") as f:
    f.write(ics)

Repository layout

The library expects a directory with the following structure:

<root>/
  config.school          # school configuration (XML)
  weeks/
    week01/
      week01.luzng       # week configuration (XML)
      _obj/
        <id>.luzngl      # one file per lesson (XML)
    week02/
      ...

The weeks/ directory name and config.school filename are configurable:

repo = ScheduleRepo(root_path, config_file="school.xml", weeks_dir="schedule")

Translations

Subject codes and group names are school-specific. Implement Translator in your school package to map them:

from luzapp import DictTranslator

translator = DictTranslator(
    subjects={"MATH": "Mathematics", "ENG": "English"},
    groups={"AlphaGroup": "[e-mail]"},
)

ics = repo.export_ics([1, 2], translator=translator)

DictTranslator covers simple lookup tables. For more complex logic, subclass luzapp.Translator directly.

Creating and modifying lessons

All models are immutable. Use model_copy(update={...}) to produce a modified copy, then save it:

from luzapp import Lesson
from datetime import datetime, timedelta

lesson = Lesson(
    lesson_id=repo.generate_lesson_id(),
    array="MATH",
    subject="Algebra",
    start_time=datetime(2026, 3, 16, 9, 0),
    wanted_length=timedelta(hours=1),
    actual_length=timedelta(hours=1),
    groups=("Alpha",),
    is_critical=True,   # adds "קריטי" to the bizur tags
)

repo.save_lesson(week_number=1, lesson=lesson)

Bizur flags

Three scheduling tags can be set via constructor kwargs or read as properties:

Property	Bizur tag	Meaning
is_hidden	Hidden	Excluded from exports and consumer views
is_fake	פיקטיבי	Placeholder concealing a real event
is_critical	קריטי	Marked as critical

Syncing via git

from luzapp import git

git.git_pull("/path/to/school-repo")
# ... make changes ...
git.git_push("/path/to/school-repo", message="update week 5")

Development

uv sync
uv run pytest
uv run pytest --cov=src/luzapp   # with coverage

Legal Notice

This library is open-source under the Apache License, with the copyright holder being the State of Israel. However, LuzApp itself is proprietary software, of which usage and modification is restricted to authorized personnel only.