aer-timesheet-assist

AER Timesheet Assist

AER Timesheet Assist is a small Streamlit app for generating readable yearly-overview lab timesheets.

It helps people distribute monthly working time across projects while accounting for public holidays, sick days, vacation days, and individual weekly working hours.

The app stores local working data in SQLite at ~/.aer_timesheet_assist/timesheet_assist.sqlite by default. Set AER_TIMESHEET_DB=/path/to/timesheet.sqlite before launching the app if you want to use a different database file.

Install from local source

From this project folder:

pip install -e .

After publishing to PyPI, users should be able to install it with:

pip install aer-timesheet-assist

Run the app

aer-timesheet-assist

This opens a local Streamlit app in your browser.

Create a desktop launcher

After installing the package in the Python environment you want to use, create a clickable desktop launcher:

aer-timesheet-assist --install-desktop-shortcut

The launcher uses the exact Python interpreter that ran the command. This means it works from a virtual environment, conda environment, or base Python install without needing to activate the environment again when clicked.

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 running app.

Run in demo mode

aer-timesheet-assist --demo

Demo mode pre-fills example project allocations, public holidays, sick days, and vacation days.

Create a holiday template

aer-timesheet-assist --make-holiday-template

This writes holiday_template.csv in the current folder.

You can also provide a custom path:

aer-timesheet-assist --make-holiday-template holidays_2026_05_nrw.csv

Holiday file format:

date,name,type
2026-05-01,Labour Day,public_holiday
2026-05-14,Ascension Day,public_holiday
2026-05-25,Whit Monday,public_holiday

Only the date column is required. The app accepts CSV and XLSX holiday files.

Create a teaching template

Teaching can be imported from CSV/XLSX with fixed dates and hours. The app also offers a download button for this template in the Teaching section.

aer-timesheet-assist --make-teaching-template

Teaching file format:

date,hours,course
2026-05-07,2.0,Example course
2026-05-21,2.0,Example course

Teaching hours take priority over flexible project scheduling. If an uploaded university template already contains hours in Lehre rows for the selected month, the app can load those rows into the teaching table.

Create an event template

Events combine sick leave, vacation, and fixed project days in one CSV/XLSX table. Fixed project days reserve the person's full working day for that project before flexible project allocation is calculated.

aer-timesheet-assist --make-events-template

Event file format:

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. The project column is required only for project events.

Timesheet workflow

1. Select an existing person from the sidebar, or add a new person. Person settings, projects, teaching, and events are saved locally in SQLite for reuse the next time the app starts.
2. Optionally upload a previous Excel file generated by this app or a compatible university template to reuse person name, weekly hours, header fields, and project names.
3. Select the year and a preview month.
4. Import or edit public holidays. Holidays are shared across all saved people for the selected year. If you upload the university template in the sidebar, you can load shaded weekday columns from that template into the holiday table. Review the imported list because templates may mark university closure or bridge days as well as official public holidays.
5. Enter or import fixed teaching hours.
6. Enter or import events for sick leave, vacation, and fixed project days.
7. Enter person-specific project allocations with start and end dates.
8. Review the selected month preview.
9. Export the yearly overview or university template workbook. Exports are generated for all 12 months of the selected year.

Project allocation

The app supports two allocation modes in the same project table:

project,monthly_hours,allocation_percent
LTER-D,48,0
RESIST Z02,72,0
GCF support,0,20

• monthly_hours is best when you already know the exact monthly project quota, such as 48 hours for LTER-D.
• If monthly_hours is 0, allocation_percent is used to split the remaining available monthly working hours.
• start_date and end_date control which months the project is active for the selected person.

The app does not split every day into percentages. Instead, it schedules projects as readable blocks across the selected month. For example, with an 8 h working day and 48 h assigned to LTER-D, the yearly sheet will reserve six full working days for LTER-D in that month. If a project has 12 h remaining, it will use one full day plus a partial day.

Calculated project targets and daily capacities are rounded to quarter-hour increments to avoid awkward decimal-hour fragments.

Excel output

The yearly overview Excel file includes:

• Year Overview: the main Excel sheet, with all 12 months arranged as a compact day-by-day year overview.
• Overview: person/month/hour metadata and metrics.
• Project Summary: target, scheduled, and unscheduled hours per project.
• Daily Details: row-wise machine-readable details.
• Calendar_Data: machine-readable cells for each exported month.

The app also exports 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 downloading the university template export.

Development

Recommended setup:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows PowerShell
pip install -e .

Run directly with Streamlit during development:

streamlit run src/aer_timesheet_assist/app.py

Build a distribution package:

python -m pip install build
python -m build

Upload to PyPI after configuring your credentials:

python -m pip install twine
python -m twine upload dist/*