Metadata-Version: 2.4
Name: aer-time-planner
Version: 0.6.0
Summary: A Streamlit app for planning project time distribution and exporting university work records.
Author: AER Time Planner contributors
License: MIT
License-File: LICENSE
Keywords: excel,lab,project-management,streamlit,time-planning
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 Time Planner

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

It helps people plan monthly working time across projects while accounting for public holidays, sick days, vacation days, and individual weekly working hours. The planned allocation can then be exported into the required Excel formats.

The app stores local planning data in SQLite at `~/.aer_time_planner/time_planner.sqlite` by default. Set
`AER_TIME_PLANNER_DB=/path/to/time_planner.sqlite` before launching the app if you want to use a different database file.

## 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-time-planner
```

## Run the app

```bash
aer-time-planner
```

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-time-planner --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-time-planner --demo
```

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

## Create a holiday template

```bash
aer-time-planner --make-holiday-template
```

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

You can also provide a custom path:

```bash
aer-time-planner --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-time-planner --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.

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

```bash
aer-time-planner --make-events-template
```

Event file format:

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

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

```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.
- `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 export 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:

```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_time_planner/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/*
```
