document custom formatters in readme
This commit is contained in:
parent
422d6bb593
commit
05df375102
76
README.md
76
README.md
|
@ -173,6 +173,82 @@ day in the computer's timezone. Add `Z` or an offset to specify the timezone.
|
|||
* `1h30m ago`
|
||||
* `two hours thirty minutes ago`
|
||||
|
||||
## Custom formatters
|
||||
|
||||
You can implement your own formatters for all subcommands that display entries
|
||||
(like `t display`, `t week` etc.). It is as easy as creating an executable file
|
||||
written in any programming language (interpreted or compiled) and placing it in
|
||||
a path listed in the config value for `formatter_search_paths`.
|
||||
|
||||
This executable will be given as standard input a csv stream with each row
|
||||
representing a time entry with the same structure as the `csv` formatter output.
|
||||
It will also be given as a command line argument representing settings for this
|
||||
formatter stored in the config file.
|
||||
|
||||
### Example
|
||||
|
||||
Suppose we have this config file:
|
||||
|
||||
```toml
|
||||
database_file = "/home/user/.config/tiempo/config.toml"
|
||||
round_in_seconds = 900
|
||||
append_notes_delimiter = " "
|
||||
formatter_search_paths = ["/home/user/.config/tiempo/formatters"]
|
||||
default_formatter = "text"
|
||||
auto_sheet = "dotfiles"
|
||||
auto_sheet_search_paths = ["/home/user/.config/tiempo/auto_sheets"]
|
||||
auto_checkout = false
|
||||
require_note = true
|
||||
week_start = "Monday"
|
||||
|
||||
[formatters.earnings]
|
||||
hourly_rate = 300
|
||||
currency = "USD"
|
||||
```
|
||||
|
||||
then we can create the `earnings` formatter by placing the following file in
|
||||
`/home/user/.config/tiempo/formatters/earnings`:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import sys
|
||||
import json
|
||||
import csv
|
||||
from datetime import datetime, timezone
|
||||
from datetime import timedelta
|
||||
from math import ceil
|
||||
|
||||
config = json.loads(sys.argv[1])
|
||||
|
||||
reader = csv.DictReader(
|
||||
sys.stdin,
|
||||
fieldnames=['id', 'start', 'end', 'note', 'sheet'],
|
||||
)
|
||||
|
||||
total = timedelta(seconds=0)
|
||||
|
||||
for line in reader:
|
||||
if not line['end']:
|
||||
continue
|
||||
|
||||
start = datetime.strptime(line['start'], '%Y-%m-%dT%H:%M:%S.%fZ')
|
||||
end = datetime.strptime(line['end'], '%Y-%m-%dT%H:%M:%S.%fZ')
|
||||
|
||||
total += end - start
|
||||
|
||||
hours = ceil(total.total_seconds() / (3600))
|
||||
earnings = hours * config['hourly_rate']
|
||||
currency = config['currency']
|
||||
|
||||
print(f'You have earned: {earnings} {currency}')
|
||||
```
|
||||
|
||||
Now if you run `t display -f earnings` you will get something like:
|
||||
|
||||
```
|
||||
You have earned: 2400 USD
|
||||
```
|
||||
|
||||
## Why did you write this instead of improving timetrap?
|
||||
|
||||
* timetrap is [hard to install](https://github.com/samg/timetrap/issues/176),
|
||||
|
|
Loading…
Reference in New Issue