Toggl

class togglwrapper.Toggl(api_token, base_url='https://www.toggl.com/api', version='v8')[source]

Class to collect all Toggl objects in one place.

Ensures easy authentication, since API credentials only need to be provided upon instantiation.

delete(uri)[source]

DELETEs to the given URI.

get(uri, params=None)[source]

GETs to the given URI.

Args:

uri (str): The URI/path to append to the full API URL. params (dict, optional): Extra parameters/querystrings to accompany the GET request.

post(uri, data=None)[source]

POSTs to the given URI.

Args:

uri (str): The URI/path to append to the full API URL. data (optional): dict, bytes, or file-like object to POST.

put(uri, data)[source]

PUTs to the given URI with a data.

Args:

uri (str): The URI/path to append to the full API URL. data: dict, bytes, or file-like object to PUT.

reset_token()[source]

Deletes the current API Token and returns a new token.

signups(data)[source]

Creates a new user.

Args:

data (dict): Contains required and optional fields and values.

Toggl Classes

These can all be accessed from an instantiated Toggl client. For example:

>>> toggl = Toggl('api_token')
>>> toggl.Clients.get()
...
>>> toggl.Dashboard.get(3542)
...
>>> toggl.Workspaces.get()
...
class togglwrapper.api.Clients(toggl)[source]

The Clients object.

Groups all actions relating to Clients together.

create(data, child_uri=None)

Creates a new instance of the object type.

Args:

data (dict): The dict of information needed to create a new object. child_uri (str, optional): The URI of the child Object or subpath.

Defaults to None.

delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

get(id=None, child_uri=None, params=None)

Gets the array of objects, or a specific instance by ID.

Args:
id (int, optional): The ID of a specific instance of the Object.

If none provided, the array of all available instances is retrieved, provided that an endpoint exists for it. Defaults to None.

child_uri (str, optional): The URI of the child Object or subpath.

e.g. If we wanted the Clients of a Workspace, where the Workspace is the parent object, the child URI is ‘/clients’. Defaults to None.

params (dict, optional): The dictionary of additional params to

include in as the querystring, appended to the URL. Keys with values of None will be ignored. Defaults to None.

get_projects(client_id, active=True)[source]

Gets the projects associated with the Client with the given ID.

Args:

client_id (int): The ID of the client. active (bool or string, optional): Must be either True, False, or the string ‘both’. Defaults to True.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.Dashboard(toggl)[source]
get(workspace_id)[source]

Gets the Dashboard for the Workspace with the given ID.

class togglwrapper.api.Projects(toggl)[source]
create(data, child_uri=None)

Creates a new instance of the object type.

Args:

data (dict): The dict of information needed to create a new object. child_uri (str, optional): The URI of the child Object or subpath.

Defaults to None.

delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

get(project_id)[source]

Gets the Project with the given ID.

get_project_users(project_id)[source]

Gets the ProjectUsers for the Project with the given ID.

get_tasks(project_id)[source]

Gets the Tasks for the Project with the given ID.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.ProjectUsers(toggl)[source]
create(data, child_uri=None)

Creates a new instance of the object type.

Args:

data (dict): The dict of information needed to create a new object. child_uri (str, optional): The URI of the child Object or subpath.

Defaults to None.

delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

get_for_project(project_id)[source]

Gets the ProjectUsers for the Project with the given ID.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.Tags(toggl)[source]
create(data, child_uri=None)

Creates a new instance of the object type.

Args:

data (dict): The dict of information needed to create a new object. child_uri (str, optional): The URI of the child Object or subpath.

Defaults to None.

delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.Tasks(toggl)[source]
create(data, child_uri=None)

Creates a new instance of the object type.

Args:

data (dict): The dict of information needed to create a new object. child_uri (str, optional): The URI of the child Object or subpath.

Defaults to None.

delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

get(tag_id)[source]

Gets the Task instance with the given ID.

get_for_project(project_id)[source]

Gets the Tasks for the Project with the given ID.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.TimeEntries(toggl)[source]
create(data, child_uri=None)

Creates a new instance of the object type.

Args:

data (dict): The dict of information needed to create a new object. child_uri (str, optional): The URI of the child Object or subpath.

Defaults to None.

delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

get(id=None, start_date=None, end_date=None)[source]

Gets a time entry, or time entires in a time range, or the latest ones.

If neither an ID or time range is given, returns the time entries started during the last 9 days. The limit of returned time entries is 1000. So only the first 1000 found time entries are returned.

Args:
id (int, optional): The ID of the specific instance to get.

Defaults to None.

start_date (str, optional): Must be ISO 8601 date and time strings.

e.g. ‘2013-03-10T15:42:46+02:00’. Defaults to None.

end_date (str, optional): Must be ISO 8601 date and time strings.

e.g. ‘2013-03-10T15:42:46+02:00’. Defaults to None.

get_current()[source]

Gets the current running time entry.

start(data)[source]

Starts a new time entry.

stop(time_entry_id)[source]

Stops the time entry with the given ID.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.User(toggl)[source]
get(related_data=False, since=None)[source]

Gets the User associated with the current API token.

Args:
related_data (bool): If True, gets all the workspaces, clients,

projects, tasks, time entries and tags which the user can see. Defaults to False.

since (str or int, optional): Get objects which have changed after

a certain time. The value should be a unix timestamp (e.g. 1362579886). Defaults to None.

update(data)[source]

Updates the user associated with the api token.

Args:

data (dict): The dict of information to update for the user.

class togglwrapper.api.Workspaces(toggl)[source]
get(id=None, child_uri=None, params=None)

Gets the array of objects, or a specific instance by ID.

Args:
id (int, optional): The ID of a specific instance of the Object.

If none provided, the array of all available instances is retrieved, provided that an endpoint exists for it. Defaults to None.

child_uri (str, optional): The URI of the child Object or subpath.

e.g. If we wanted the Clients of a Workspace, where the Workspace is the parent object, the child URI is ‘/clients’. Defaults to None.

params (dict, optional): The dictionary of additional params to

include in as the querystring, appended to the URL. Keys with values of None will be ignored. Defaults to None.

get_clients(workspace_id)[source]

Gets the Clients for the Workspace with the given ID.

get_projects(workspace_id)[source]

Gets the Projects for the Workspace with the given ID.

get_tags(workspace_id)[source]

Gets the Tags for the Workspace with the given ID.

get_tasks(workspace_id)[source]

Gets the Tasks for the Workspace with the given ID.

get_users(workspace_id)[source]

Gets the Users for the Workspace with the given ID.

get_workspace_users(workspace_id)[source]

Gets the WorkspaceUsers for the Workspace with the given ID.

invite(workspace_id, data)[source]

Adds users to the workspace. Sends an email invite to the users.

Args:

workspace_id (int): The ID of the workspace to invite the user to. data (dict): The information needed to invite the right user.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

class togglwrapper.api.WorkspaceUsers(toggl)[source]
delete(id=None, ids=None)

Deletes a specific instance by ID, or delete multiple instances.

Args:
id (int, optional): The ID of the instance to delete. Defaulta to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to delete. Not all objects allow for deleting multiple instances at once. See Toggl’s API Documentation to see where this is allowed. Defaults to None.

update(id=None, ids=None, child_uri=None, data=None)

Updates a specific instance by ID, or update multiple instances.

Args:
id (int, optional): The ID of the instance to update. Defaults to

None.

ids (iterable of ints, optional): An iterable of IDs of instances

to update. Not all objects allow multiple instances to be updated at once - see Toggl’s API Documentation to see where this is allowed. Defaults to None.

child_uri (str, optional): The URI/path to append to the object’s

URI, to update. Defaults to None.

data (dict, optional): The dict of information to update the

object(s). Defaults to None.

Exceptions

exception togglwrapper.exceptions.AuthError[source]

Raised when authentication fails.