A rich CLI to track hours worked towards monthly targets with toggl
Project description
Toggl Tally
Toggl tally is a rich Python command line interface for tracking progress against your monthly project targets and calculating the daily hours you need to work to hit your goals. Toggl tally connects to the Toggl Track API, and supports:
- Filtering by workspaces, clients or projects
- Configurable invoicing day of month
- Configurable weekly working days
- Excluding (and reporting upcoming) public holidays in your configured country
Installation
Install using pip
:
pip install toggl-tally
Setup
Toggl API token
Toggl tally handles connection to the Toggl Track API; all you need to do is make your Toggl API token available as an environment variable. Get your Toggl API token from the Toggl profile page and set it as the TOGGL_API_TOKEN
environment variable.
Configuration
Toggl tally needs to be configured with your monthly goals and projects. This configuration can be passed either via a YAML file or via command line arguments and options. YAML file configuration is the most streamlined and DRY for daily use.
The path to the YAML config file can either be passed as a command-line argument (toggl-tally -c /path/to/config.yaml
) or can be detected automatically from the environment variable TOGGL_TALLY_CONFIG
.
The configurable keys are as below, and a full example yaml config is provided with this repo.
hours_per_month: 160
invoice_day: 18
workspaces:
clients:
- MegaCorp
projects:
- Widget Building
skip_today: false
timezone: Africa/Johannesburg
working_days:
- MO
- TU
- WE
- TH
- FR
country: ZA
exclude_public_holidays: true
Alternatively, all configuration can be passed with command-line arguments to the hours
command. See the CLI help for detailed information about each argument and option.
Toggl data model and filtering
erDiagram
WORKSPACE ||--o{ CLIENT : has
WORKSPACE ||--o{ PROJECT : has
WORKSPACE ||--o{ TIME_ENTRY : has
CLIENT |o--|{ PROJECT : has
PROJECT |o--o{ TIME_ENTRY : has
toggl_tally
enables filtering by multiple workspace, client or project names. The UNION across all of these entities is taken to determine the final set of time entries. For example, for the filter criteria:
workspaces:
clients:
- MegaCorp
- HyperCorp
projects:
- Widget Building
- Baz refactoring
A time entry will be included if it:
- Belongs to a project linked to the MegaCorp client OR
- Belongs to a project linked to the HyperCorp client OR
- Belongs to the Widget Building project OR
- Belongs to the Baz refactoring project
Hours command
The hours
command is the core command for Toggl tally. It reports:
- Working days to go before next invoice date
- Daily hours needed to hit monthly target by next invoice date
- Hours worked on relevant projects since last invoice
- A monthly progress bar
The hours
command has a --verbose
(-v
) flag, which if enabled also reports:
- Active workspace, project and client filters
- Upcoming public holidays in the working period
Development
To install toggl_tally
for development, run:
pip install -e '.[dev]'
Code for this repository is checked using pre-commit. After cloning this repository please run the following steps to initialise pre-commit:
pre-commit install --install-hooks
The following hooks are automatically run when new commits are made:
- From pre-commit hooks:
- end-of-file-fixer
- trailing-whitespace
- check-yaml
- check-added-large-files (max. 500kb)
- black Python code format checking
- flake8 Python code linting
- isort Python code import ordering
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for toggl_tally-0.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e37dab0f7ead463a0b7079d115d5a3f328deab4ca4c9e0b389ace8bb7576de7c |
|
MD5 | baf627ef5104459e1151ff65993a9ed5 |
|
BLAKE2b-256 | 6839b1d4d81dcb8b9d59d3be6ce02de89fd2b54e2f782bb307682811ade98a7a |