aer-timesheet-assist 0.4.6

A simple Streamlit app for lab timesheet assistance and Excel export.

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.

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.

Timesheet workflow

1. Optionally upload last month's Excel file generated by this app to reuse person name, weekly hours, and projects. When you upload a previous yearly overview workbook, the next yearly overview export preserves the other months and replaces only the selected month. This lets you keep one master workbook for the year.
2. Select year and month.
3. Enter the person's weekly working hours.
4. Import or edit public holidays. 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. Mark sick days and vacation days.
7. Enter project allocations.
8. Review the selected month preview and export the yearly overview Excel sheet.
9. Download the updated master Excel timesheet.

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.

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.

Excel output

The exported 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 the selected month.

The app also exports the selected month 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/*