python-timew

A Python API for Timewarrior, originally by Tjaart van der Walt @tjaartvdwalt, now maintained here. Archived original is on gitlab.

Installation

For this API to work, you need Timewarrior installed

Installation is easy from the Python Package Index

pip install timew

API Documentation

Documentation is generated by Sphinx apidocs, from embedded docstrings in napoleon format. We generate .rst files, which are checked into the repository and can be previewed online.

The timewarrior module contains the interesting docs, while the formal doctree are rendered to an index and a more concise modules file.

Examples

>>> from timew import TimeWarrior

>>> timew = TimeWarrior()

>>> timew.start(time=datetime(2018, 8, 15, 9, 0, 0), tags=['my tag'])
Tracking "my tag"
Started 2018-09-06T09:00:00
Current         07T13:20:45
Total              28:20:45

>>> timew.cancel()
Canceled active time tracking.

>>> timew.delete(1)
Deleted @1

>>> timew.join(1, 2)
Joined @1 and @2

>>> from timew import Duration
>>> from datetime import timedelta
>>> timew.lengthen(1, Duration(timedelta(minutes=30)))
Lengthened @1 by 0:30:00

>>> timew.move(1, datetime(2018, 8, 15, 9, 0, 0))
Moved @1 to 2018-09-05T09:00:00

>>> timew.shorten(1, Duration(timedelta(minutes=10)))
Shortened @1 by 0:10:00

>>> timew.split(1)
Split @1

>>> timew.start(tags=['my tag'])
Tracking "my tag"
Started 2018-09-07T13:37:00
Current               40:22
Total               0:03:22

>>> timew.stop()
Recorded "my tag"
Started 2018-09-07T13:37:00
Ended                 40:53
Total               0:03:53

>>> timew.track(start_time=datetime(2018, 9, 7, 11, 0, 0),
                end_time=datetime(2018, 9, 7, 12, 0, 0))
Tracking "from 20180907T110000 - 20180907T120000"
Started 2018-09-07T13:42:27
Current                  27
Total               0:00:00

Contributing

Report bugs, submit inquiries, or request features via issues.

Please submit a pull request for modifications. Make sure the dist, test and docs Makefile targets work. Docs need to be kept generated during development, because they are checked in assets.

The build environment and tools will contain themselves in a venv within the source tree, and should not pollute your system.

Commits

Use the following format for commit messages:

X subsystem: summary description of change

long description text paragraphs
...

where X is a single character from the following:

/	fix
^	removal
-	task/chore
+	feature/new
=	comment/code-equal

All text should [usually] be wrapped by 79 characters, especially the summary line.

For subsystem, use your best judgement, and look at previous commits with git log --oneline to get an idea and for consistency with previous changes. More than one level of subsystem can make sense.

Please use interactive rebase to make commits look nice and have one logical change each, with no merge commits.

Thanks.