lib-toggl is a Python library for interacting with the Toggl API. It exists because I figured it'd be easier to start fresh instead of update TogglPy to use the new v9 API and the other changes needed for better Home Assistant integration.

Seriously, the number of #TODO: comments in this code is ridiculous.

As this library is mostly meant for use with Home Assistant, it's written to be compatible with Python 3.11+ and is mostly async based with strong-ish typing. It is absolutely not meant to be a complete implementation of the Toggl API; it does just enough forha-toggl-track and that's about it.

• lib-toggl
  • Using
  • Dev
    • pre-commit
    • doctoc
  • TODO

More formal docs to be added. Tests are also needed!

For now, see the scripts directory for a quick example of how to use the library.

I use VSCode for development so there's a .vscode directory with some settings that I use. Most of the extensions and configuration directives there should be easy to port to your preferred editor / IDE as needed.

Pretty simple setup; it's all uv driven...

Create a virtual environment for the project.

❯ uv venv --python 3.13
Using CPython 3.13.0 interpreter at: /opt/homebrew/opt/python@3.13/bin/python3.13
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
❯ source .venv/bin/activate

Use autoenv to automatically activate the virtual environment when you enter the project directory.

❯ cd TogglPy
Switching virtualenv: .venv [🐍Python 3.11.6]
❯ which python
/home/karl/projects/ha-dev/TogglPy/.venv/bin/python

Don't forget to install pre-commit hooks.

Assuming you've installed the pre-commit tool, just run the following to install the git hooks:

❯ pre-commit install
pre-commit installed at .git/hooks/pre-commit

The table of contents in readme.md is updated with doctoc

❯ docker run --rm -v "$(pwd)":/app peterdavehello/npm-doctoc doctoc /app/README.md
<...>

• pre-commit hooks
• Tests
• CI/CD/GHA automation for testing and pypi release
• Devcontainers (for VSCode) so the dev environment is more portable / easier to set up