Metadata-Version: 2.4
Name: taxi_tipee
Version: 1.0.11
Summary: tipee backend for Taxi
Author-email: Alexandre Blin <alexandre@blin.fr>
License-Expression: WTFPL
Project-URL: Homepage, https://github.com/alexandreblin/taxi-tipee
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: taxi>=6.0
Requires-Dist: requests>=2.3.0
Dynamic: license-file

tipee backend for Taxi
======================

This is the [Taxi](https://github.com/sephii/taxi) backend for [tipee](https://tipee.ch). It
exposes the `tipee` protocol to push entries as timechecks.

Installation
------------

```shell
taxi plugin install tipee
```

Configuration
-------------

Run `taxi config` and use the `tipee` protocol for your backend :

```ini
[backends]
my_tipee_backend = tipee://[app_name]:[app_private_key]@[instance].tipee.net/api/?person=[person_id]

[taxi]
regroup_entries = false
```

* `[app_name]` and `[app_private_key]` can be found in tipee's PHP configuration files, like
`$_CONFIG['PrivateKey']['timbreuse'] = 'fK19psLpm17u660fCiJ5s569bfeij2s800y';` for example, so here you would use 
`timbreuse:fK19psLpm17u660fCiJ5s569bfeij2s800y`
* `[instance]` is tipee's instance name
* `[person_id]` is the ID of your
user, which can be found in the URL when editing your profile, like `https://[instance].tipee.net/person/#/169`

> There is an extra `scheme=http` query string argument that can be useful when developing (using `localhost:port` as the hostname).

Usage
-----

You can now add timesheet entries like :

```
19/05/2020 # Tuesday
tipee    08:00-09:00    Monitoring server
tipee         -10:30    Fixing bug
tipee         -?        Work in progress...
```

Things you should know
----------------------

### Duration as hours is not supported

As stated in [Taxi's documentation](https://taxi-timesheets.readthedocs.io/en/master/userguide.html#timesheet-syntax) :

> duration can either be a time range or a duration in hours. If it’s a time range, it should be in the format start-end, where start can be left blank if the previous entry also used a time range and had a time defined, and end can be ? if the end time is not known yet, leading to the entry being ignored. Each part of the range should have the format HH:mm, or HHmm. If duration is a duration, it should just be a number, eg. 2 for 2 hours, or 1.75 for 1 hour and 45 minutes.

However, tipee requires timechecks to have specific time start and end, so a proper error will be thrown if you do not provide a time range.

### Regrouping entries is not supported

By default, [Taxi](https://taxi-timesheets.readthedocs.io/en/master/userguide.html#regroup-entries) regroups entries to commit them. So if you have 3 different entries on a day with the same alias and description, it will push only one entry with the cumulated times. In tipee, this leads to timesheets overlapping each others, which are explicitly prohibited. So you need to set the option to `false` :

```
[taxi]
regroup_entries = false
```

Releasing
---------

Publish a [GitHub release](https://github.com/alexandreblin/taxi-tipee/releases/new) with a new tag
named after the version (like `1.0.11`), from the web interface or with:

```shell
gh release create 1.0.11 --generate-notes
```

The `release` GitHub Actions workflow builds the package (the version comes from the tag, through
[setuptools-scm](https://setuptools-scm.readthedocs.io)), publishes it to PyPI as a
[trusted publisher](https://docs.pypi.org/trusted-publishers/), so no API token is needed, and attaches
the files to the release.

To build locally, `nix develop` (or direnv) provides Python and the tools: `python -m build --no-isolation`.
