Metadata-Version: 2.4
Name: nytid
Version: 11.37
Summary: TA bookings, schedules, time tracking, and task management
License-Expression: MIT
License-File: LICENSE
Author: Daniel Bosk
Author-email: daniel@bosk.se
Maintainer: Daniel Bosk
Maintainer-email: dbosk@kth.se
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Utilities
Requires-Dist: Pillow (>=9.3,<11.0)
Requires-Dist: cachetools (>=5.3.1,<6.0.0)
Requires-Dist: canvaslms (>=6.11,<7.0)
Requires-Dist: click (>=8.4.1,<9.0.0)
Requires-Dist: icalendar (>=7.1,<8)
Requires-Dist: ladok3 (>=5.15,<6.0)
Requires-Dist: lxml (>=5.0,<7.0)
Requires-Dist: openpyxl (>=3.0.10,<4.0.0)
Requires-Dist: platformdirs (>=4.9,<5.0)
Requires-Dist: recurring-ical-events (>=3,<4)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: rich (>=13.0.0,<14.0.0)
Requires-Dist: typer (>=0.26.7,<1.0.0)
Requires-Dist: typerconf (>=2.13,<3.0)
Requires-Dist: tzlocal (>=5.4.4,<6.0.0)
Requires-Dist: weblogin (>=1.25,<2.0)
Requires-Dist: zulipcli (>=0.11,<1.0)
Project-URL: Bug Tracker, https://github.com/dbosk/nytid/issues
Project-URL: Documentation, https://github.com/dbosk/nytid/releases
Project-URL: Repository, https://github.com/dbosk/nytid
Description-Content-Type: text/markdown

# nytid

A CLI and library for managing TA bookings, course schedules, sign-up sheets,
employment contracts, the hours TAs report in Medvind, time tracking, and task
management. Every interactive
workflow has a scriptable equivalent, so repetitive tasks can be handed off to
Cron or AI agents.

## Command overview

### `courses` — manage course registries and configurations

Maintain a set of course registries (directories of course data), add or remove
courses, and configure per-course settings such as Canvas URLs and TimeEdit ICS
links.

```bash
nytid courses list
nytid courses new DD1310
nytid courses config DD1310
```

### `schedule` — view and export combined schedules

Display a unified schedule that merges course events, external ICS calendars,
and pending tasks. Export the result as an ICS file for import into any calendar
application.

```bash
nytid schedule view
nytid schedule next      # every detail of the next event, links included
nytid schedule ics > schedule.ics
nytid schedule external add https://cloud.timeedit.net/…
```

### `signupsheets` — generate TA sign-up sheets

Generate CSV sign-up sheets from the course schedule so that TAs can indicate
which lab sessions they want to work. The sheets are designed for Google Sheets.

```bash
nytid signupsheets generate DD1310
nytid signupsheets set_url DD1310 https://docs.google.com/…
```

### `hr` — employment contracts, time sheets and reported hours

Compute employment data from completed sign-up sheets: generate amanuensis
contracts, produce time sheets for hourly-employed TAs, and summarize hours per
course.

```bash
nytid hr amanuensis create DD1310
nytid hr timesheets generate DD1310
nytid hr time DD1310
```

Instead of a time sheet for the extra (or missed) sessions of one period,
the difference can be carried into the next contract by letting `--start`
reach back before the contract period:

```bash
nytid hr amanuensis create DD1310 --period 25/26-2 --start 2025-08-25
```

The `hr medvind` commands read the times TAs have reported in Medvind (Visma),
KTH's time-reporting system, to check them against what the TAs were booked
for. Logging in reuses the KTH credentials and session of `ladok login`, and
may ask for an Authenticator approval. Piped output is tab-separated rows for
scripts. `hours` prints the reported times, only those reported to the work
leader in `--leader` or `hr.medvind.leader` if one is set; `--leader ''` shows
every work leader's despite the key. `--no-approved` keeps the times a work
leader has not approved yet, which comes before attestation (`--no-attested`).
`deviations` lists the TAs whose reports since `hr.medvind.since` differ from
what their hourly time sheets asked them to report (prep time included), which
the monthly cron script mails out. Without `--leader` or `hr.medvind.leader` it
lists only the TAs booked on the courses and counts their times for any work
leader, so hours they reported to a colleague show as over-reported. With
`--user`/`-u` it checks only the booked TAs whose usernames match the regex,
from the start of the username, so `tolva$` is needed to leave out `tolvan`.

```bash
nytid hr medvind plans
nytid hr medvind hours --leader 'Ada Lärare' --no-approved
nytid hr medvind hours --leader 'Ada Lärare' --no-attested
nytid hr medvind hours --ta 'Tolvan' --comment DD1301 --from 2026-09-01 --to 2026-09-30
nytid hr medvind deviations "(datintro|prg[im])" --leader 'Ada Lärare'
nytid hr medvind deviations "(datintro|prg[im])" --user 'tolva$'
```

### `track` — track time on activities

Track time spent on course activities with free-form labels. Start a label
directly, or launch a command or tmux shell from the same entry point. View
statistics, export to JSON/CSV/ICS, and edit past entries.

```bash
nytid track start DD1310 grading
nytid track start email --run mutt
nytid track stop
nytid track today
nytid track stats weekly
```

### `todo` — task management with agent support

Priority-based task list with working-directory capture, notes, and GitHub issue
sync. Tasks can be started interactively or handed off to AI agents in headless
mode. Tasks can wait for other tasks: `todo ready` and `todo next` offer only
the tasks that nothing blocks, and the schedule view automatically slots those,
and the tasks already in progress, into free time. A task that others wait for
shares their urgency: it ranks as high as the most urgent of them and is due
when they have to start.

```bash
nytid todo add "Grade assignment 3" --prio 2
nytid todo list
nytid todo ready
nytid todo start 5
nytid todo done
nytid todo sync
```

### `prompt-nytid` — fast status for shell prompts

A separate, minimal entry point that prints the current todo context and the
currently tracked labels as two machine-readable lines. In a tracked tmux
window the context is the chain from the root task down to the window's
current task (`353>356>359`, the task an ID-less `todo done` there would
complete); elsewhere it is the active todo ids. It skips the CLI's import
overhead so it is cheap enough to run on every shell prompt render:

```bash
readarray -t _nytid < <(prompt-nytid --who "$USER")
# ${_nytid[0]} = todo context, ${_nytid[1]} = tracked labels
```

### `utils` — room availability and other utilities

```bash
nytid utils rooms set-url https://… "Sal A" "Sal B"
```

## Quick start

```bash
pip install nytid
nytid courses registry add kth ~/courses
nytid courses new DD1310
nytid schedule view
```

## Where the data lives

nytid keeps its configuration in `~/.config/nytid/config.json` and its data
(todos, time tracking, caches) under `~/.nytid`. Set `NYTID_HOME` to move all
of it at once, for example to try a new version or run a script on throw-away
data:

```bash
NYTID_HOME=/tmp/nytid-sandbox nytid todo list
```

The configuration then lives in `$NYTID_HOME/config.json` and the data
directly under `$NYTID_HOME`.

## Documentation

For a full introduction and design overview, read the PDF found in the latest
[release](https://github.com/dbosk/nytid/releases).

