timew 0.3.0
Python interface to your timewarrior database
Requires Python: >=3.9
Keywords: timewarrior

python-timew
==============================================================================

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

.. __: https://github.com/tjaartvdwalt/
.. __: https://gitlab.com/tjaart/python-timew


Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For this API to work, you need Timewarrior__ installed

Installation is easy from the `Python Package Index`__

.. code:: bash

 pip install timew

.. __: https://github.com/GothenburgBitFactory/timewarrior
.. __: https://pypi.org/project/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.

.. __: https://github.com/smemsh/python-timew/blob/master/docs/api/timew.timewarrior.rst
.. __: https://github.com/smemsh/python-timew/blob/master/docs/api/index.rst
.. __: https://github.com/smemsh/python-timew/blob/master/docs/api/modules.rst



Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: pycon

 >>> 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.

.. __: https://github.com/smemsh/python-timew/issues/
.. __: https://github.com/smemsh/python-timew/pulls/


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.