mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
Docs: Added API specification, eliminated reports.txt
This commit is contained in:
parent
1cd019167d
commit
c65833b706
3 changed files with 132 additions and 96 deletions
103
doc/api.txt
Normal file
103
doc/api.txt
Normal file
|
@ -0,0 +1,103 @@
|
|||
Extension API
|
||||
=============
|
||||
Timewarrior reports are written as extensions, which uses an API to provide
|
||||
filtered data and configuration to the external command. This is a one-way
|
||||
process, and the extension has no way to communicate back to Timewarrior.
|
||||
However, future rules features will allow this.
|
||||
|
||||
|
||||
Integration
|
||||
-----------
|
||||
Simply placing an executable script/program in the ~/.timewarrior/ext directory
|
||||
is sufficient to configure nad enable the extension. The name of the program is
|
||||
leftmost matched, so that this extension:
|
||||
|
||||
~/.timewarrior/ext/my_report.py
|
||||
|
||||
Can be run using all of the following commands, depending on the uniqueness of
|
||||
the name:
|
||||
|
||||
$ timew report my_report.py
|
||||
$ timew report my_report
|
||||
$ timew report my_r
|
||||
$ timew my_report.py
|
||||
$ timew my_report
|
||||
$ timew my_r
|
||||
|
||||
|
||||
APІ Mechanism
|
||||
-------------
|
||||
Timewarrior will provide all configuration and filtered data in JSON format to
|
||||
the standard input of the extension program. There are no command line arguments
|
||||
used, and no environment changes. The extension must be a standalone executable
|
||||
entiry, as Timewarrior will fork/exec and not invoke a shell.
|
||||
|
||||
All standard output generated by the extension is captured and presented
|
||||
verbatim by Timewarrior. There may be additional text prepended or appended to
|
||||
this.
|
||||
|
||||
|
||||
Input Format
|
||||
------------
|
||||
The input format looks like this:
|
||||
|
||||
name1: value1
|
||||
name2: value2
|
||||
version: 0.1.0
|
||||
...
|
||||
|
||||
[
|
||||
{ ... },
|
||||
{ ... },
|
||||
...
|
||||
]
|
||||
|
||||
Specifically, there is an initial block of name/value pairs, which is a copy of
|
||||
the complete current configuration data. It has the form:
|
||||
|
||||
<name>: <value>
|
||||
|
||||
This configuration block includes the Timewarrior version, so that multiple
|
||||
releases maybe supported by the extension. Additionally, other data is included
|
||||
with the 'temp.' prefix, indicating that it is not part of the configuration
|
||||
data, but may be of use to the extension. For example:
|
||||
|
||||
temp.db: /home/user/.timewarrior
|
||||
temp.report.end: 20160401T000000Z
|
||||
temp.report.start: 20160430T235959Z
|
||||
temp.report.tags: "This is a multi-word tag",ProjectA,tag123
|
||||
|
||||
After the configuration block, there is a single blank line to separate it from
|
||||
the JSON data.
|
||||
|
||||
The JSON data is a single JSON array, containing zero or more Interval objects
|
||||
that look like this (line breaks for clarity):
|
||||
|
||||
{"start":"20160405T162205Z",\
|
||||
"end":"20160405T162211Z",\
|
||||
"tags":["This is a multi-word tag","ProjectA","tag123"]},
|
||||
|
||||
Here the presence of the "end" data means this interval is closed, i.e. not
|
||||
actively being tracked. There is one JSON object per line. The timestamps are
|
||||
ISO format UTC.
|
||||
|
||||
|
||||
Guidelines
|
||||
----------
|
||||
A well-behaved extension is one that follows these guidelines, and conforms to
|
||||
the general pattern of behavior exhibited by Timewarrior. The guidelines are:
|
||||
|
||||
- Obey the 'verbose' setting, and if the value is neither on/1/yes/y/true, then
|
||||
consider it 'off', and generate minimal output, which may be no output at all.
|
||||
|
||||
- Obey the 'debug' setting, and if the value is either one/1/yes/y/true, then
|
||||
emit helpful feedback, but only that which can be useful for debugging a
|
||||
problem, which may be no output at all.
|
||||
|
||||
- Obey the 'confirmation' setting, and if the value is either one/1/yes/y/true,
|
||||
then obtain user permission interactively before proceeding with any data
|
||||
modification. Do not rely on, or implement a 'force'-like feature.
|
||||
|
||||
|
||||
--- Raw Notes ---
|
||||
|
|
@ -40,6 +40,24 @@ Non-Goals
|
|||
- No features without a compelling use case.
|
||||
|
||||
|
||||
Reports
|
||||
-------
|
||||
Anticipating all reporting needs is impossible, therefore custom reports are
|
||||
required. Rather than copy the Taskwarrior design where flexibility is provided
|
||||
via configurable options for fixed-format reports, Timewarrior will use a more
|
||||
flexible approach of providing configuration and data via an extension API.
|
||||
This will not limit the kind of reports or supported formats that can be added.
|
||||
|
||||
Timewarrior will ship with several reports, which serve as example extensions
|
||||
for users to modify and improve, perhaps contribute back to the project.
|
||||
|
||||
Purely as an example of what might be implemented, here are some report mockups:
|
||||
|
||||
./report.week.txt
|
||||
./report.day.1.txt
|
||||
./report.exc.week.txt
|
||||
|
||||
|
||||
Tags
|
||||
----
|
||||
Tags represent tracking categories. Tags are arbitrary UTF8 strings. A tag may
|
||||
|
@ -130,3 +148,14 @@ data.
|
|||
command, instead of "stop" use "forgot" or directly "edit". Then I would
|
||||
like to express either "stopped 30min ago" or "it lasted only 1hour”.
|
||||
|
||||
- Need a JSON --> CSV converter, for spreadsheet folks. Therefore csv.py could
|
||||
be an extension that converts the format.
|
||||
|
||||
- Use display granularity/resolution to see more or less details. This would
|
||||
combine nicely with a tag hierarchy. (Tomas Babej)
|
||||
|
||||
- Need reports to help users doing fixed-rate work - finding the longest task
|
||||
for example.
|
||||
|
||||
- If an interval has more than one tag with a defined color, and is being
|
||||
rendered, then use the first tag color. It doesn't really matter which.
|
||||
|
|
|
@ -1,96 +0,0 @@
|
|||
Reporting
|
||||
=========
|
||||
Anticipating all reporting needs is impossible, therefore custom reports are
|
||||
required. Rather than copy the Taskwarrior design where flexibility is provided
|
||||
via configurable options for fixed-format reports, Timewarrior will use a more
|
||||
flexible approach of providing configuration and data via an API. This will not
|
||||
limit the kind of reports or supported formats that can be added.
|
||||
|
||||
|
||||
Requirements
|
||||
------------
|
||||
Timewarrior will ship with several reports, which serve as example extensions
|
||||
for users to modify and improve.
|
||||
|
||||
Timewarrior will handle the command line options for reports, then pass off a
|
||||
standardized set of parameters to the report extension. These parameters will
|
||||
include:
|
||||
|
||||
- Date range. Although Timewarrior might support "last month" as a reporting
|
||||
range, the extensions themselves would be passed precise values, therefore
|
||||
reducing the complexity of the extensions.
|
||||
|
||||
- Data will be filtered by Timewarrior, so that extensions will not need to
|
||||
reimplement this.
|
||||
|
||||
- Reports will be sized according to need, not according to available terminal
|
||||
width. If a report does not fit in a window, it is not an error.
|
||||
|
||||
There will be a default report, which is configurable so that one of the reports
|
||||
or commands can be the default.
|
||||
|
||||
|
||||
Report Mockups
|
||||
--------------
|
||||
Purely as an example of what might be implemented, here are some report mockups:
|
||||
|
||||
./report.week.txt
|
||||
./report.day.1.txt
|
||||
./report.exc.week.txt
|
||||
|
||||
TBD (calendar like "task calendar" with table below)
|
||||
TBD (timeline, l-r)
|
||||
TBD (table with subtotals)
|
||||
|
||||
|
||||
Example Commands
|
||||
----------------
|
||||
Here are some provisional examples of report commands:
|
||||
|
||||
$ timew report day [monday] [±<tag> ...]
|
||||
$ timew report week [±<tag> ...]
|
||||
$ timew report month|quarter|year
|
||||
|
||||
|
||||
Report API
|
||||
----------
|
||||
The report API is simple - it invokes a program and feeds it input. All output
|
||||
is generated by the program. When running this command:
|
||||
|
||||
$ timew report x ...
|
||||
|
||||
Timewarrior then runs this:
|
||||
|
||||
$ ~/.timewarrior/extensions/x.*
|
||||
|
||||
With standard input consisting of:
|
||||
|
||||
filter: ...
|
||||
name1: value1
|
||||
|
||||
[
|
||||
{ ... },
|
||||
{ ... },
|
||||
...
|
||||
]
|
||||
|
||||
That is, the input is line-oriented, with first a header block of name/value
|
||||
pairs, then a blank line, then the JSON filtered data. The header block has all
|
||||
configuration names flattened, i.e. no hierarchy.
|
||||
|
||||
|
||||
--- Raw Notes ---
|
||||
|
||||
- Need a JSON --> CSV converter, for spreadsheet folks.
|
||||
|
||||
- Use display granularity/resolution to see more or less details. This would
|
||||
combine nicely with a tag hierarchy. (Tomas Babej)
|
||||
|
||||
- Need reports to help users doing fixed-rate work - finding the longest task
|
||||
for example.
|
||||
|
||||
- If an interval has more than one tag with a defined color, and is being
|
||||
rendered, then use the first tag color. It doesn't really matter which.
|
||||
|
||||
- Need a formal API description, for extension authors.
|
||||
|
Loading…
Add table
Add a link
Reference in a new issue