114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
# Timesheets
|
|
|
|
A Python CLI tool that parses markdown pipe-delimited timesheet tables and
|
|
exports them to CSV for import into Odoo. It also supports a human-readable
|
|
summary view, a stories list, a work status dashboard, and can fetch notes
|
|
directly from Joplin.
|
|
|
|
## Package layout
|
|
|
|
```
|
|
timesheets/
|
|
├── pyproject.toml # package metadata, entry point, dev dependencies
|
|
├── timesheets.example.toml # example config file
|
|
└── src/timesheets/
|
|
├── cli.py # argument parsing, main() entry point
|
|
├── parser.py # markdown table parsing, aggregation, date filtering
|
|
├── projects.py # project_map.json loading and key resolution
|
|
├── output.py # CSV writing, summary, stories, and status printing
|
|
├── config.py # TOML config file loading and key extraction
|
|
├── joplin.py # Joplin API integration (notebook traversal, note fetching)
|
|
├── status.py # day/week status calculations
|
|
└── utils.py # shared low-level helpers (duration parsing, formatting, etc.)
|
|
```
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
cd timesheets
|
|
uv sync
|
|
```
|
|
|
|
## Subcommands
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `summary` | Human-readable summary of time spent per project |
|
|
| `csv` | Export timesheet entries as CSV for Odoo import |
|
|
| `stories` | List stories worked on, grouped by project |
|
|
| `status` | Show hours remaining today and projected week total |
|
|
|
|
All subcommands accept the same source and day arguments:
|
|
|
|
```sh
|
|
# Source: Joplin (recommended) or a local file
|
|
uv run timesheets <cmd> --joplin
|
|
uv run timesheets <cmd> --input timesheet.md
|
|
|
|
# Day: defaults to today, accepts YYYY-MM-DD, MM-DD, natural language
|
|
uv run timesheets <cmd> 2026-05-22 --joplin
|
|
uv run timesheets <cmd> yesterday --joplin
|
|
uv run timesheets <cmd> 3 days ago --joplin
|
|
```
|
|
|
|
### summary
|
|
|
|
```sh
|
|
uv run timesheets summary --joplin # today, full detail
|
|
uv run timesheets summary -w --joplin # full week
|
|
uv run timesheets summary -s --joplin # short: one line per project
|
|
uv run timesheets summary -w -s --joplin # weekly short: per-day project totals
|
|
uv run timesheets summary -w -ss --joplin # weekly totals only: one line per day
|
|
```
|
|
|
|
### csv
|
|
|
|
```sh
|
|
uv run timesheets csv --joplin # stdout
|
|
uv run timesheets csv --joplin -o output.csv # write to file
|
|
```
|
|
|
|
### stories
|
|
|
|
```sh
|
|
uv run timesheets stories --joplin # today
|
|
uv run timesheets stories -w --joplin # full week
|
|
```
|
|
|
|
### status
|
|
|
|
```sh
|
|
uv run timesheets status --joplin
|
|
```
|
|
|
|
## Config file
|
|
|
|
Copy `timesheets.example.toml` to `timesheets.toml` in the working directory
|
|
(or pass `--config /path/to/file.toml`):
|
|
|
|
```toml
|
|
[joplin]
|
|
token = "your_api_token_here"
|
|
|
|
[projects]
|
|
map = "/path/to/project_map.json"
|
|
|
|
[work]
|
|
daily_hours = 8.0
|
|
weekly_hours = 40.0
|
|
```
|
|
|
|
Priority order: **CLI flag > config file > environment variable > default**.
|
|
|
|
## Joplin notebook structure
|
|
|
|
```
|
|
Work/
|
|
└── Timesheets/
|
|
└── YYYY/
|
|
└── YYYY - WNN ← note per week, one table per day
|
|
```
|
|
|
|
Each table is preceded by a heading of the form `# <weekday> - YYYY-MM-DD`.
|
|
Open entries (start time present, end time absent) are used by the `status`
|
|
command to calculate expected end time.
|