aer-time-planner

AER Time Planner

AER Time Planner is a local Streamlit app for planning how working days are distributed across projects, teaching, absences, and fixed project events.

It helps you keep a year-wide plan for one or more people, preview each month, and export the planned allocation into the required Excel workbooks.

Install

Install from PyPI:

pip install aer-time-planner

Update an existing installation:

pip install --upgrade aer-time-planner

Run

Start the app with:

aer-time-planner

Your browser should open automatically. The app runs locally on your computer.

Optional Desktop Launcher

After installing, you can create a clickable launcher:

aer-time-planner --install-desktop-shortcut

The launcher uses the same Python environment that created it. This means it can work from a virtual environment, conda environment, or base Python installation without manually activating that environment each time.

On Windows this creates a .cmd launcher. On macOS it creates a .command launcher. On Linux it creates a .desktop launcher. The launcher opens a terminal window and starts Streamlit; closing that terminal stops the app.

Planning Workflow

1. Select a saved person from the sidebar, or add a new person.
2. Set the year, weekly hours, and university template fields.
3. Add public holidays for the year, or load shaded holidays from a compatible university template.
4. Add teaching entries for fixed teaching dates and hours.
5. Add events for sick leave, vacation, and fixed project days.
6. Add the person's projects, allocation percentages or monthly hours, and project start/end dates.
7. Preview the selected month.
8. Export the yearly overview or the university template workbook.

Exports are generated for all 12 months of the selected year.

What Is Saved Locally

The app stores planning data in a local SQLite database on your computer:

~/.aer_time_planner/time_planner.sqlite

Saved data includes people, project date ranges, holidays, teaching, and events. No server account is needed.

To use a different database file, set this environment variable before starting the app:

export AER_TIME_PLANNER_DB=/path/to/time_planner.sqlite

Events

Events combine sick leave, vacation, and fixed project days in one table.

For fixed project days, set type to project and enter the project name. These days are reserved for that project before the remaining time is distributed across other projects.

Example:

date_start,date_end,type,project,label,duration_hours_per_day
2026-05-04,2026-05-05,vacation,,Annual leave,
2026-05-18,2026-05-18,sick,,Sick leave,
2026-06-10,2026-06-12,project,RESIST Z02,CRC RESIST assembly,4.0

Allowed event types are sick, vacation, and project. For project events, duration_hours_per_day is an optional positive quarter-hour duration applied on every working day in the range. A blank duration retains the legacy full-day behavior. Durations are not used for absence rows, and over-capacity combinations are rejected rather than truncated.

Teaching and Academic Semesters

Teaching input uses units: one teaching unit is 45 minutes, so four units contribute three clock hours. Exports and workload totals always use clock hours. Existing database hours values are preserved as clock hours during migration and informational units are derived by dividing by 0.75.

Summer semester begins on 1 April and winter semester on 1 October by default. The application setting can instead use the first Monday in those months. Winter semester continues through the day before the next summer semester. Bachelor's and Master's thesis records count as teaching; their per-thesis unit defaults are configurable and intentionally start at zero because no institutional values are bundled.

Haushalt Balancing and Month Locks

Every person has a protected Haushalt system project. Fixed monthly commitments are reserved first; active non-Haushalt percentages then consume their stated share of remaining capacity, and Haushalt receives the remainder below 100%. Teaching remains separately displayed, while combined institutional time is direct Haushalt plus Teaching.

Locking a month stores a versioned JSON snapshot of daily rows, calendar values, summaries, metrics, and export metadata. Later changes do not affect preview or export for that month. Unlocking removes the snapshot and resumes calculation from current data. Before the first schema upgrade, the app creates a timestamped .bak copy beside the SQLite database.

Export Cutoff and Application Updates

Downloads default to entries through the computer's local date; future plans stay in SQLite and remain visible in planning views. Clear Include entries only through today to export planned future values. The cutoff also applies to future locked snapshots.

The Application section can check PyPI and, after explicit confirmation, run the current interpreter with -m pip install --upgrade aer-time-planner. Editable installations are protected. After a successful update, close and reopen the app in the same environment.

Project Allocation

Each person has their own project table. This is useful when several people work on the same project for different periods.

The project table supports two allocation modes:

project,start_date,end_date,monthly_hours,allocation_percent,is_eu_project
LTER-D,2026-01-01,2026-12-31,48,0,false
RESIST Z02,2026-01-01,2026-06-30,0,60,true
GCF support,2026-07-01,2026-12-31,0,40,false

• Use monthly_hours when a project has a fixed monthly quota.
• Use allocation_percent to split the remaining available monthly working hours.
• Use start_date and end_date to control which months the project is active.
• Use is_eu_project for projects that should be written into the EU project section of the university template.

The app schedules projects as readable day blocks instead of splitting every day into small percentages. Calculated targets and daily capacities are rounded to quarter-hour increments.

Excel Outputs

The yearly overview export includes:

• Year Overview: all 12 months arranged as a compact day-by-day year overview.
• Overview: person, month, hour, and metric metadata.
• Project Summary: target, scheduled, and unscheduled hours per project.
• Daily Details: row-wise machine-readable details.
• Calendar_Data: machine-readable calendar cells.

The app can also export all 12 months into the university Stundenzettel template. By default it uses the bundled vorlage_stundenzettel_2026_v0.xlsx file. You can upload another compatible .xlsx template in the sidebar before exporting.

Templates

The app offers template download buttons inside the Streamlit interface. The same templates can also be created from the command line.

Holiday template:

aer-time-planner --make-holiday-template

Teaching template:

aer-time-planner --make-teaching-template

Event template:

aer-time-planner --make-events-template

Each command writes a CSV template in the current folder. You can also provide a custom output path.

Install From Source

After cloning or downloading this repository:

pip install -e .

Run directly with Streamlit during development:

streamlit run src/aer_time_planner/app.py

Build a distribution package:

python -m build