# TogglPy
> **Forked**: The [original project](https://github.com/matthewdowney/TogglPy) was archived, this is fork partially patched for [Toggl API](https://engineering.toggl.com/docs/) v9.
> For fully patched project check out [other forks](https://github.com/matthewdowney/TogglPy/forks).
[](https://pypi.org/project/TogglPy/)
TogglPy is a python library for interacting with the [Toggl API](https://github.com/toggl/toggl_api_docs).
# Features
* Make requests against any (Toggl) API endpoint with request data as a dictionary
* Generate and save PDFs of summary, weekly, or detailed reports
* Fetch reports as JSON
* Get all workspaces or all clients
* Get a specific workspace or client, by ID or name
* Query projects, by client, or by a single name
* Add custom time entries
# Setup
+ Install the project with pip:
```shell
pip install -U TogglPy
```
+ Import the content:
```python
from toggl.TogglPy import Toggl
```
+ Create a Toggl object:
```python
toggl = Toggl()
```
+ Authenticate either by Toggl credentials OR using [your personal API token](https://toggl.com/app/profile):
+ If trying to access any of the [Reports API](https://github.com/matthewdowney/TogglPy#generating-pdf-reports) endpoints, [you need to use](https://github.com/toggl/toggl_api_docs/blob/master/reports.md#authentication) your personal API token
```python
toggl.setAuthCredentials('<EMAIL>', '<PASSWORD>')
```
OR:
```python
toggl.setAPIKey('<API-TOKEN>')
```
# I learn best by examples:
### Manual GET requests against any Toggl endpoint:
```python
from toggl.TogglPy import Toggl
# create a Toggl object and set our API key
toggl = Toggl()
toggl.setAPIKey("mytogglapikey")
response = toggl.request("https://api.track.toggl.com/api/v8/clients")
# print the client name and ID for each client in the response
# list of returned values can be found in the Toggl docs:
# https://github.com/toggl/toggl_api_docs/blob/master/chapters/clients.md
for client in response:
print("Client name: %s Client ID: %s" % (client['name'], client['id']))
```
Or, if you want to add some data to your request:
```python
data = {
'id': 42,
'some_key': 'some_value',
'user_agent': 'TogglPy_test',
}
response = toggl.request("https://api.track.toggl.com/api/v8/some/endpoint", parameters=data)
```
### Making a POST request to any Toggl endpoint:
```python
data = {
"project":
{
"name": "some project",
"wid":777,
"template_id":10237,
"is_private":true,
"cid":123397
}
}
response = toggl.postRequest("https://api.track.toggl.com/api/v8/projects", parameters=data)
```
### Generating PDF reports:
**Must** authenticate with your personal API token to use these endpoints.
```python
# specify that we want reports from this week
data = {
'workspace_id': 0000, # see the next example for getting a workspace ID
'since': '2015-04-27',
'until': '2015-05-03',
}
# download one of each type of report for this time period
toggl.getWeeklyReportPDF(data, "weekly-report.pdf")
toggl.getDetailedReportPDF(data, "detailed-report.pdf")
toggl.getSummaryReportPDF(data, "summary-report.pdf")
```
### Finding workspaces and clients
This will print some raw data that will give you all the info you need to identify clients and workspaces quickly:
```python
print(toggl.getWorkspaces())
print(toggl.getClients())
```
If you want to clean it up a little replace those print statements with
```python
for workspace in toggl.getWorkspaces():
print("Workspace name: %s\tWorkspace ID:%s" % (workspace['name'], workspace['id']))
for client in toggl.getClients():
print("Client name: %s\tClient ID:%s" % (client['name'], client['id']))
```
If you want to find a specific client or workspace:
```python
john_doe = toggl.getClient(name="John Doe")
personal = toggl.getWorkspace(name="Personal")
print("John's client ID is %s" % john_doe['id'])
print("The workspace ID for 'Personal' is %s" % personal['id'])
```
The reverse can also be done; use `.getClient(id=0000)` or `.getWorkspace(id=000)` to find items by ID.
### Starting New Timer
```python
# You can get your project PID in toggl.com->Projects->(select your project)
# and copying the last number of the url
myprojectpid = 10959693
toggl.startTimeEntry("my description", myprojectpid)
```
### Stopping Current Timer
```python
currentTimer = currentRunningTimeEntry()
stopTimeEntry(currentTimer['data']['id'])
```
### Creating a custom time entry
```python
# Create a custom entry for today, of a 9 hour duration, starting at 10 AM:
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', hour=10)
# Or speed up the query process and provide the client's name:
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', hour=10)
# Provide *month* and/or *day* too for specific dates:
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', month=1, day=31, hour=10)
# Automate missing time entries!
for day in (29, 30, 31):
toggl.createTimeEntry(hourduration=9, projectname='someproject', day=day, hour=10)
```
### Automate daily records
```python
# toggle_entry.py
import datetime
if datetime.datetime.today().weekday() not in (4, 5):
toggl.createTimeEntry(hourduration=9, projectname='someproject', hour=10)
```
#### Add your daily records as a cron job:
```shell
(crontab -l ; echo "0 22 * * * toggl_entry.py")| crontab -
```
Raw data
{
"_id": null,
"home_page": "https://github.com/skip-pay/TogglPy",
"name": "skip-TogglPy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "api toggl",
"author": "Skip Pay",
"author_email": "developers@skippay.cz",
"download_url": "https://files.pythonhosted.org/packages/c9/0f/6ce56be0e65b8ea0d1c12d501a7918782f44ca1c6ca82520873ff637de46/skip_togglpy-0.2.0.tar.gz",
"platform": null,
"description": "# TogglPy\n\n> **Forked**: The [original project](https://github.com/matthewdowney/TogglPy) was archived, this is fork partially patched for [Toggl API](https://engineering.toggl.com/docs/) v9.\n> For fully patched project check out [other forks](https://github.com/matthewdowney/TogglPy/forks). \n\n[](https://pypi.org/project/TogglPy/)\n\nTogglPy is a python library for interacting with the [Toggl API](https://github.com/toggl/toggl_api_docs).\n\n# Features\n* Make requests against any (Toggl) API endpoint with request data as a dictionary\n* Generate and save PDFs of summary, weekly, or detailed reports\n* Fetch reports as JSON\n* Get all workspaces or all clients\n* Get a specific workspace or client, by ID or name\n* Query projects, by client, or by a single name\n* Add custom time entries\n\n# Setup\n+ Install the project with pip:\n```shell\npip install -U TogglPy\n```\n+ Import the content: \n```python\nfrom toggl.TogglPy import Toggl\n```\n+ Create a Toggl object: \n```python\ntoggl = Toggl()\n```\n+ Authenticate either by Toggl credentials OR using [your personal API token](https://toggl.com/app/profile):\n\t+ If trying to access any of the [Reports API](https://github.com/matthewdowney/TogglPy#generating-pdf-reports) endpoints, [you need to use](https://github.com/toggl/toggl_api_docs/blob/master/reports.md#authentication) your personal API token\n```python\ntoggl.setAuthCredentials('<EMAIL>', '<PASSWORD>') \n```\nOR:\n```python\ntoggl.setAPIKey('<API-TOKEN>') \n```\n\n\n# I learn best by examples:\n### Manual GET requests against any Toggl endpoint:\n```python\nfrom toggl.TogglPy import Toggl\n\n# create a Toggl object and set our API key \ntoggl = Toggl()\ntoggl.setAPIKey(\"mytogglapikey\")\n\nresponse = toggl.request(\"https://api.track.toggl.com/api/v8/clients\")\n\n# print the client name and ID for each client in the response\n# list of returned values can be found in the Toggl docs:\n# https://github.com/toggl/toggl_api_docs/blob/master/chapters/clients.md\nfor client in response:\n print(\"Client name: %s Client ID: %s\" % (client['name'], client['id']))\n```\nOr, if you want to add some data to your request:\n```python\ndata = {\n 'id': 42,\n 'some_key': 'some_value',\n 'user_agent': 'TogglPy_test',\n} \nresponse = toggl.request(\"https://api.track.toggl.com/api/v8/some/endpoint\", parameters=data)\n```\n\n### Making a POST request to any Toggl endpoint:\n```python\n\ndata = { \n \"project\": \n { \n \"name\": \"some project\", \n \"wid\":777, \n \"template_id\":10237, \n \"is_private\":true, \n \"cid\":123397 \n }\n }\n\nresponse = toggl.postRequest(\"https://api.track.toggl.com/api/v8/projects\", parameters=data)\n\n```\n\n\n### Generating PDF reports:\n**Must** authenticate with your personal API token to use these endpoints.\n```python\n# specify that we want reports from this week\ndata = {\n 'workspace_id': 0000, # see the next example for getting a workspace ID\n 'since': '2015-04-27',\n 'until': '2015-05-03',\n}\n\n# download one of each type of report for this time period\ntoggl.getWeeklyReportPDF(data, \"weekly-report.pdf\")\ntoggl.getDetailedReportPDF(data, \"detailed-report.pdf\")\ntoggl.getSummaryReportPDF(data, \"summary-report.pdf\")\n```\n\n### Finding workspaces and clients\nThis will print some raw data that will give you all the info you need to identify clients and workspaces quickly:\n```python\nprint(toggl.getWorkspaces())\nprint(toggl.getClients())\n```\nIf you want to clean it up a little replace those print statements with\n```python\nfor workspace in toggl.getWorkspaces():\n print(\"Workspace name: %s\\tWorkspace ID:%s\" % (workspace['name'], workspace['id']))\nfor client in toggl.getClients():\n print(\"Client name: %s\\tClient ID:%s\" % (client['name'], client['id']))\n```\nIf you want to find a specific client or workspace:\n```python\njohn_doe = toggl.getClient(name=\"John Doe\")\npersonal = toggl.getWorkspace(name=\"Personal\")\n\nprint(\"John's client ID is %s\" % john_doe['id'])\nprint(\"The workspace ID for 'Personal' is %s\" % personal['id'])\n```\nThe reverse can also be done; use `.getClient(id=0000)` or `.getWorkspace(id=000)` to find items by ID.\n\n### Starting New Timer\n\n```python\n# You can get your project PID in toggl.com->Projects->(select your project)\n# and copying the last number of the url\nmyprojectpid = 10959693\ntoggl.startTimeEntry(\"my description\", myprojectpid)\n```\n\n### Stopping Current Timer\n\n```python\ncurrentTimer = currentRunningTimeEntry()\nstopTimeEntry(currentTimer['data']['id'])\n```\n\n### Creating a custom time entry\n\n```python\n# Create a custom entry for today, of a 9 hour duration, starting at 10 AM:\ntoggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', hour=10)\n\n# Or speed up the query process and provide the client's name:\ntoggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', hour=10)\n\n# Provide *month* and/or *day* too for specific dates:\ntoggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', month=1, day=31, hour=10)\n\n# Automate missing time entries!\nfor day in (29, 30, 31):\n\ttoggl.createTimeEntry(hourduration=9, projectname='someproject', day=day, hour=10)\n```\n\t\n### Automate daily records\n```python\n# toggle_entry.py\nimport datetime\nif datetime.datetime.today().weekday() not in (4, 5):\n\ttoggl.createTimeEntry(hourduration=9, projectname='someproject', hour=10)\n```\n#### Add your daily records as a cron job:\n```shell\n(crontab -l ; echo \"0 22 * * * toggl_entry.py\")| crontab -\n```\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Python library for interacting with the Toggl API.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/skip-pay/TogglPy"
},
"split_keywords": [
"api",
"toggl"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "09acdb0ba9e3499277cbc8b4ce0e5b70068e40fcdaff03a8b046912c79d741c1",
"md5": "78119dfe830272de63a072022b64da0e",
"sha256": "d261c010c398c03d31cad13ac8b2cfef61a108cc7095f69a298bd5c2335e4fa8"
},
"downloads": -1,
"filename": "skip_TogglPy-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "78119dfe830272de63a072022b64da0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11804,
"upload_time": "2024-06-28T18:01:27",
"upload_time_iso_8601": "2024-06-28T18:01:27.040281Z",
"url": "https://files.pythonhosted.org/packages/09/ac/db0ba9e3499277cbc8b4ce0e5b70068e40fcdaff03a8b046912c79d741c1/skip_TogglPy-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c90f6ce56be0e65b8ea0d1c12d501a7918782f44ca1c6ca82520873ff637de46",
"md5": "a30f67a55103ad42b4436c49d5986b0a",
"sha256": "fcd11e447fc62b8328716e790062850aad318ebcdd99d024c5d8c3fb6f8524b6"
},
"downloads": -1,
"filename": "skip_togglpy-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a30f67a55103ad42b4436c49d5986b0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11015,
"upload_time": "2024-06-28T18:01:28",
"upload_time_iso_8601": "2024-06-28T18:01:28.323629Z",
"url": "https://files.pythonhosted.org/packages/c9/0f/6ce56be0e65b8ea0d1c12d501a7918782f44ca1c6ca82520873ff637de46/skip_togglpy-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-28 18:01:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skip-pay",
"github_project": "TogglPy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "skip-togglpy"
}
JSON
