Metadata-Version: 2.4
Name: aer-timesheet-assist
Version: 0.4.6
Summary: A simple Streamlit app for lab timesheet assistance and Excel export.
Project-URL: Homepage, https://git.uni-due.de/ag-leese/timesheet_helper
Project-URL: Issues, https://git.uni-due.de/ag-leese/timesheet_helper/-/issues
Author: AER Timesheet Assist contributors
License: MIT
License-File: LICENSE
Keywords: excel,lab,project-management,streamlit,timesheet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: streamlit>=1.32
Description-Content-Type: text/markdown

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

```bash
pip install -e .
```

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

```bash
pip install aer-timesheet-assist
```

## Run the app

```bash
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:

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

```bash
aer-timesheet-assist --demo
```

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

## Create a holiday template

```bash
aer-timesheet-assist --make-holiday-template
```

This writes `holiday_template.csv` in the current folder.

You can also provide a custom path:

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

Holiday file format:

```csv
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.

```bash
aer-timesheet-assist --make-teaching-template
```

Teaching file format:

```csv
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:

```csv
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:

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

Run directly with Streamlit during development:

```bash
streamlit run src/aer_timesheet_assist/app.py
```

Build a distribution package:

```bash
python -m pip install build
python -m build
```

Upload to PyPI after configuring your credentials:

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