Fork Notice: This is a fork of evrone/toggl-python maintained by man 8 consulting. We extend the library with additional entities (Clients, Tags, Tasks) and paid plan fields needed for our automation workflows. All additions maintain the same quality standards and will be contributed back upstream. See CONTRIBUTING.md for details.
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.
