aer-time-planner 0.6.1

A Streamlit app for planning project time distribution and exporting university work records.

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
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

Allowed event types are sick, vacation, and project.

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