Metadata-Version: 2.5
Name: aer-time-planner
Version: 0.7.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 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,duration_hours_per_day
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,4.0
```

Allowed event types are `sick`, `vacation`, and `project`.
For project events, `duration_hours_per_day` is an optional positive quarter-hour duration applied on every working day in the range. A blank duration retains the legacy full-day behavior. Durations are not used for absence rows, and over-capacity combinations are rejected rather than truncated.

## Teaching and Academic Semesters

Teaching input uses `units`: one teaching unit is 45 minutes, so four units contribute three clock hours. Exports and workload totals always use clock hours. Existing database `hours` values are preserved as clock hours during migration and informational units are derived by dividing by `0.75`.

Summer semester begins on 1 April and winter semester on 1 October by default. The application setting can instead use the first Monday in those months. Winter semester continues through the day before the next summer semester. Bachelor's and Master's thesis records count as teaching; their per-thesis unit defaults are configurable and intentionally start at zero because no institutional values are bundled.

## Haushalt Balancing and Month Locks

Every person has a protected `Haushalt` system project. Fixed monthly commitments are reserved first; active non-Haushalt percentages then consume their stated share of remaining capacity, and Haushalt receives the remainder below 100%. Teaching remains separately displayed, while combined institutional time is direct Haushalt plus Teaching.

Locking a month stores a versioned JSON snapshot of daily rows, calendar values, summaries, metrics, and export metadata. Later changes do not affect preview or export for that month. Unlocking removes the snapshot and resumes calculation from current data. Before the first schema upgrade, the app creates a timestamped `.bak` copy beside the SQLite database.

## Export Cutoff and Application Updates

Downloads default to entries through the computer's local date; future plans stay in SQLite and remain visible in planning views. Clear **Include entries only through today** to export planned future values. The cutoff also applies to future locked snapshots.

The Application section can check PyPI and, after explicit confirmation, run the current interpreter with `-m pip install --upgrade aer-time-planner`. Editable installations are protected. After a successful update, close and reopen the app in the same environment.

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