Toggl Reports Client

class toggl2pl.TogglReportsClient(api_token, user_agent)

Bases: toggl2pl.TogglAPIClient

Initialize a new instance of class object to communicate with Toggl.

Parameters

  • api_token (str) – The unique authentication token to use instead of username and password.

  • user_agent (str) – The required user agent identifier used to gather application usage statistic.

details(wid, **kwargs)

Fetch detailed information about tasks related to the specified Toggl workspace.

Parameters

  • wid (int) – The Toggl workspace ID to query information about tasks.

  • kwargs – Parameters to query Toggl Reports API (please see official Toggl Reports API for details).

Returns

Dictionary object with detailed information about recorded tasks.

Return type

dict

static fmt(description, width=80)

Modify provided description text to make it readable and ensure all posts use the same canonical format.

Parameters

  • description (str) – Toggl post description text to format.

  • width (int) – Optional argument to set the maximum length of wrapped lines.

Returns

Description text rewritten in canonical format.

Return type

str

get(endpoint, url='https://toggl.com/reports/api/v2', **kwargs)

Send provided keyword arguments to the combination of Toggl Reports API URL and endpoint using HTTP GET request.

Parameters

  • endpoint (str) – The Toggl Reports API endpoint to send data using HTTP GET request.

  • url (str) – The Toggl Reports API URL to send HTTP GET requests.

  • kwargs – Request parameters specific to each endpoint (please see the official Toggl API reference).

Returns

Dictionary object with Toggl Reports API endpoint response content.

Return type

dict

list_clients(wid)

List clients corresponding to the particular Toggl workspace.

Parameters

wid (int) – The unique Toggl workspace ID to list clients.

Returns

List of dictionaries with clients descriptions.

Return type

list

me()

Fetch information about the currently authenticated user account.

Returns

Dictionary object with information about the currently authenticated user account.

Return type

dict

posts(since, until, wid)

High-level wrapper for tasks() method to aggregate Toggl tasks by projects, format descriptions and round total amount of minutes per project.

Parameters

  • since (str) – The start date in ISO 8601 (YYYY-MM-DD) format to query Toggl Reports API for tasks.

  • until (str) – The end date in ISO 8601 (YYYY-MM-DD) format to query Toggl Reports API for tasks.

  • wid (int) – The unique Toggl workspace ID to list tasks.

Returns

Normalized list of Toggl tasks aggregated by projects.

Return type

list

projects(wid)

Fetch list of the particular workspace projects and rewrite it into dictionary with machine-readable structure.

Parameters

wid (int) – The unique Toggl workspace ID to list projects.

Returns

Dictionary object with machine-readable information about projects in the specified workspace.

Return type

dict

tasks(since, until, wid)

Combine clients, projects and tasks information into single object with machine-readable format.

Parameters

  • since (str) – The start date in ISO 8601 (YYYY-MM-DD) format to query Toggl Reports API for tasks.

  • until (str) – The end date in ISO 8601 (YYYY-MM-DD) format to query Toggl Reports API for tasks.

  • wid (int) – The unique Toggl workspace ID to list tasks.

Returns

Dictionary object with machine-readable information about Toggl tasks during specified range of dates.

Return type

dict