Typed Toggl API Python wrapper with pre-validation to avoid extra network usage.
- Based on Toggl API
- Documentation
Migration to API V9 is currently in progress. Many methods are not implemented yet. Feel free to open an issue to escalate their development.
pip install toggl-python
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 monthspoetry is required during local setup.
- Install minimal supported
Pythonversion usingpyenv-pyenv install 3.8 - Activate it for current project -
pyenv local 3.8 - Create virtual environment -
python -m venv .venv. IfPython version is not minimalthen IDE suggestions will be incorrect andpre-commithooks will not be working.
Run poetry install --no-root to setup local environment. pre-commit install is also advisable.
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"
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
This package follows evrone-python-guidelines and uses configs from evrone-django-template.
