toggl-python

Typed Toggl API Python wrapper with pre-validation to avoid extra network usage.

• Based on Toggl API
• Documentation

Important Note

Migration to API V9 is currently in progress. Many methods are not implemented yet. Feel free to open an issue to escalate their development.

Install

pip install toggl-python

Usage

Fetch information about current user via TokenAuth (TOGGL_TOKEN is required):

from toggl_python.auth import TokenAuth
from toggl_python.entities.user import CurrentUser


if __name__ == "__main__":
    auth = TokenAuth(token="TOGGL_TOKEN")
    CurrentUser(auth=auth).me()

Basic Auth is also supported:

from toggl_python.auth import BasicAuth
from toggl_python.entities.user import CurrentUser


if __name__ == "__main__":
    auth = BasicAuth(username="username", password="password")
    CurrentUser(auth=auth).me()

Package supports different input formats for datetime arguments:

• str:

from toggl_python.auth import TokenAuth
from toggl_python.entities.user import CurrentUser


if __name__ == "__main__":
    auth = TokenAuth(token="TOGGL_TOKEN")
    CurrentUser(auth=auth).get_time_entries(
        start_date="2024-01-01",
        end_date="2024-02-01T15:00:00-02:00",
    )

• datetime:

from datetime import datetime, timezone

from toggl_python.auth import TokenAuth
from toggl_python.entities.user import CurrentUser


if __name__ == "__main__":
    auth = TokenAuth(token="TOGGL_TOKEN")
    CurrentUser(auth=auth).get_time_entries(
        start_date=datetime(2024, 1, 1, tzinfo=timezone.utc),
        end_date=datetime(2024, 2, 1, 15, tzinfo=timezone.utc),
    )

Query params are available as well:

from toggl_python.auth import TokenAuth
from toggl_python.entities.workspace import Workspace


if __name__ == "__main__":
    auth = TokenAuth(token="TOGGL_TOKEN")
    workspace_id = "WORKSPACE_ID"
    Workspace(auth=auth).get_projects(active=True)

Pre-validation to avoid extra network usage:

from datetime import datetime, timezone

from toggl_python.auth import TokenAuth
from toggl_python.entities.workspace import Workspace


if __name__ == "__main__":
    auth = TokenAuth(token="TOGGL_TOKEN")
    workspace_id = "WORKSPACE_ID"
    since = datetime(2024, 1, 20, tzinfo=timezone.utc)
    # Assume that datetime.now is 2024-05-01
    Workspace(auth=auth).list(since=since)

    # ValidationError: Since cannot be older than 3 months

Development

poetry is required during local setup.

• Install minimal supported Python version using pyenv - pyenv install 3.8
• Activate it for current project - pyenv local 3.8
• Create virtual environment - python -m venv .venv. If Python version is not minimal then IDE suggestions will be incorrect and pre-commit hooks will not be working.

Run poetry install --no-root to setup local environment. pre-commit install is also advisable.

Unit Testing

In order to run tests using different Python versions, please follow these steps:

• Install pyenv
• Install all supported Python versions - pyenv install 3.8.* 3.9.* ...
• Run pyenv local 3.8.* 3.9.* ...
• Run poetry run nox

To run classic unit tests, execute pytest -m "not integration"

Integration Testing

Pre-defined Workspace and Project are required to have in Toggl system.

Command TOGGL_TOKEN=... WORKSPACE_ID=... PROJECT_ID=... USER_ID=... TOGGL_PASSWORD=... pytest -m integration

Credits

This package follows evrone-python-guidelines and uses configs from evrone-django-template.