Metadata-Version: 2.4
Name: aer-time-planner
Version: 0.6.1
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 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:

```bash
pip install aer-time-planner
```

Update an existing installation:

```bash
pip install --upgrade aer-time-planner
```

## Run

Start the app with:

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

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

```text
~/.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:

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

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

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

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

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

Teaching template:

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

Event template:

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

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