# TONalytica-API-Client
[](https://pypi.org/project/tonalytica-client/)
[](https://pypi.python.org/pypi/tonalytica-client/)
[](https://pypi.python.org/pypi/tonalytica-client/)
The official API client and utilities to manage a TONalytica instance written in Python.
- [INSTALLATION](#installation)
- [EXAMPLE SCRIPTS](#example-scripts)
## Installation
To install it you will need Python 3.6 or above. We recommend that you use a [virtual environment].
```bash
pip install --upgrade tonalytica-client
```
This command will update `tonalytica-client` if you have already installed it.
[virtual environment]: https://pythonbasics.org/virtualenv/
## API Authentication
All the API calls support authentication with an API key. TONalytica has two types of API keys:
- **User API Key:** has the same permissions as the user who owns it. Can be found on a user profile page.
- **Query API Key:** has access only to the query and its results. Can be found on the query page.
- Whenever possible we recommend using a Query API key
## Getting Started
```python
from tonalytica_client import TonalyticaAPIClient
# Create API client instance
"""
:args:
API_KEY
TONALYTICA_HOST (optional): `https://tonalytica.redoubt.online/` by default
"""
tonalytica = TonalyticaAPIClient(API_KEY)
```
## API REFERENCE
### Common Endpoints
Below is an incomplete list of TONalytica's API endpoints as of V9. These may change in future versions of TONalytica.
Each endpoint is appended to your TONalytica base URL. For example:
- `https://tonalytica.redoubt.online/<slug>`
### Queries
`/queries`
+ GET: Returns a paginated array of query objects.
- Includes the most recent `query_result_id` for non-parameterized queries.
```python
tonalytica.queries()
```
+ POST: Create a new query object
`/queries/<id>`
+ GET: Returns an individual query object
```python
tonalytica.get_query(query_id="")
```
+ POST: Edit an existing query object.
+ DELETE: Archive this query.
`/queries/<id>/results`
+ GET: Get a cached result for this query ID.
- Only works for non parameterized queries. If you attempt to GET results
for a parameterized query you'll receive the error: `no cached result found
for this query`. See POST instructions for this endpoint to get results for
parameterized queries.
+ POST: Initiates a new query execution or returns a cached result.
- The API prefers to return a cached result. If a cached result is not
available then a new execution job begins and the job object is returned. To
bypass a stale cache, include a `max_age` key which is an integer number of
seconds. If the cached result is older than `max_age`, the cache is ignored
and a new execution begins. If you set `max_age` to `0` this guarantees a new
execution.
- If passing parameters, they must be included in the JSON request body as
a `parameters` object.
Here's an example JSON object including different parameter types:
```
{
"parameters": {
"number_param": 100,
"date_param": "2020-01-01",
"date_range_param": {
"start": "2020-01-01",
"end": "2020-12-31"
}
},
"max_age": 1800
}
}
```
### Jobs
`/jobs/<job_id>`
+ GET: Returns a query task result (job)
+ Possible statuses:
- 1 == PENDING (waiting to be executed)
- 2 == STARTED (executing)
- 3 == SUCCESS
- 4 == FAILURE
- 5 == CANCELLED
+ When status is success, the job will include a `query_result_id`
### Query Results
`/query_results/<query_result_id>`
+ GET: Returns a query result
- Appending a filetype of `.csv` or `.json` to this request will return a downloadable file. If you append your `api_key` in the query string, this link will work for non-logged-in users.
### Dashboards
`/dashboards`
+ GET: Returns a paginated array of dashboard objects.
```python
tonalytica.dashboards()
```
+ POST: Create a new dashboard object
`/dashboards/<dashboard_slug>`
+ GET: Returns an individual dashboard object.
```python
tonalytica.get_dashboard(id="")
```
+ DELETE: Archive this dashboard
`/dashboards/<dashboard_id>`
+ POST: Edit an existing dashboard object.
## Example scripts
With `tonalytica-client` installed you will have access to several example CLI scripts within your terminal.
```text
gdpr-scrub Search for a string term in your TONalytica queries
and query results. The script returns a list of
URLs in your instance that contain references to
the search term you provide
find-tables Search the text of queries against a data source
to see which table names are used in queries of
that source. This script relies on regex that is
tested against ANSI SQL.
clone-dashboard-and-queries Completely duplicate a dashboard by copying all
its queries and visualizations.
export-queries Export all the queries of your TONalytica instance
as text files.
```
## Documentation
[TONalytica API at GitBook](https://docs.tonalytica.redoubt.online/api-reference#api-authentication)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://tonalytica.redoubt.online/",
"name": "tonalytica-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "TONalytica,redoubt,API",
"author": "maksymds",
"author_email": "redoubt@devnull.ae",
"download_url": "https://files.pythonhosted.org/packages/a9/5f/0d8e52b6dc47433e202805b15f62e1fec3a185892b46cf247db4412893e9/tonalytica-client-0.1.0.tar.gz",
"platform": null,
"description": "# TONalytica-API-Client\n\n[](https://pypi.org/project/tonalytica-client/)\n[](https://pypi.python.org/pypi/tonalytica-client/)\n[](https://pypi.python.org/pypi/tonalytica-client/)\n\n\nThe official API client and utilities to manage a TONalytica instance written in Python.\n\n- [INSTALLATION](#installation)\n- [EXAMPLE SCRIPTS](#example-scripts)\n\n\n## Installation\n\nTo install it you will need Python 3.6 or above. We recommend that you use a [virtual environment].\n\n\n```bash\npip install --upgrade tonalytica-client\n```\n\nThis command will update `tonalytica-client` if you have already installed it.\n\n[virtual environment]: https://pythonbasics.org/virtualenv/\n\n## API Authentication\nAll the API calls support authentication with an API key. TONalytica has two types of API keys:\n\n - **User API Key:** has the same permissions as the user who owns it. Can be found on a user profile page.\n - **Query API Key:** has access only to the query and its results. Can be found on the query page.\n\n - Whenever possible we recommend using a Query API key\n\n## Getting Started\n\n```python\nfrom tonalytica_client import TonalyticaAPIClient\n\n# Create API client instance\n\"\"\"\n :args:\n API_KEY\n TONALYTICA_HOST (optional): `https://tonalytica.redoubt.online/` by default\n\"\"\"\ntonalytica = TonalyticaAPIClient(API_KEY)\n```\n\n## API REFERENCE\n\n### Common Endpoints\n\nBelow is an incomplete list of TONalytica's API endpoints as of V9. These may change in future versions of TONalytica.\n\nEach endpoint is appended to your TONalytica base URL. For example:\n\n- `https://tonalytica.redoubt.online/<slug>`\n\n### Queries\n\n`/queries`\n+ GET: Returns a paginated array of query objects.\n\t- Includes the most recent `query_result_id` for non-parameterized queries.\n \n \t```python \n tonalytica.queries()\n ```\n\n+ POST: Create a new query object\n\n`/queries/<id>`\n+ GET: Returns an individual query object\n \t\n ```python \n tonalytica.get_query(query_id=\"\")\n ```\n \n+ POST: Edit an existing query object.\n+ DELETE: Archive this query. \n\n\n`/queries/<id>/results`\n\n\n+ GET: Get a cached result for this query ID.\n - Only works for non parameterized queries. If you attempt to GET results\nfor a parameterized query you'll receive the error: `no cached result found\nfor this query`. See POST instructions for this endpoint to get results for\nparameterized queries.\n\n+ POST: Initiates a new query execution or returns a cached result.\n - The API prefers to return a cached result. If a cached result is not\navailable then a new execution job begins and the job object is returned. To\nbypass a stale cache, include a `max_age` key which is an integer number of\nseconds. If the cached result is older than `max_age`, the cache is ignored\nand a new execution begins. If you set `max_age` to `0` this guarantees a new\nexecution.\n - If passing parameters, they must be included in the JSON request body as\na `parameters` object.\n\n\nHere's an example JSON object including different parameter types:\n\n```\n{ \n \"parameters\": {\n \t\"number_param\": 100,\n \t\"date_param\": \"2020-01-01\",\n \t\"date_range_param\": {\n \t\t\"start\": \"2020-01-01\",\n \t\t\"end\": \"2020-12-31\"\n \t\t}\n \t},\n \"max_age\": 1800\n }\n}\n```\n\n\n### Jobs\n\n`/jobs/<job_id>`\n+ GET: Returns a query task result (job)\n\t+ Possible statuses:\n\t\t- 1 == PENDING (waiting to be executed)\n\t\t- 2 == STARTED (executing)\n\t\t- 3 == SUCCESS\n\t\t- 4 == FAILURE\n\t\t- 5 == CANCELLED\n\t+ When status is success, the job will include a `query_result_id`\n\n### Query Results\n\n`/query_results/<query_result_id>`\n+ GET: Returns a query result\n\t- Appending a filetype of `.csv` or `.json` to this request will return a downloadable file. If you append your `api_key` in the query string, this link will work for non-logged-in users.\n\n### Dashboards\n\n`/dashboards`\n+ GET: Returns a paginated array of dashboard objects.\n\n\t```python \n tonalytica.dashboards()\n ```\n \n+ POST: Create a new dashboard object\n\n`/dashboards/<dashboard_slug>`\n+ GET: Returns an individual dashboard object.\n\n\t```python \n tonalytica.get_dashboard(id=\"\")\n ```\n \n+ DELETE: Archive this dashboard\n\n`/dashboards/<dashboard_id>`\n+ POST: Edit an existing dashboard object.\n\n\n## Example scripts\n\nWith `tonalytica-client` installed you will have access to several example CLI scripts within your terminal.\n\n```text\n\ngdpr-scrub Search for a string term in your TONalytica queries\n and query results. The script returns a list of\n URLs in your instance that contain references to\n the search term you provide\nfind-tables Search the text of queries against a data source\n to see which table names are used in queries of\n that source. This script relies on regex that is\n tested against ANSI SQL.\nclone-dashboard-and-queries Completely duplicate a dashboard by copying all \n its queries and visualizations.\nexport-queries Export all the queries of your TONalytica instance\n as text files.\n```\n\n## Documentation\n\n[TONalytica API at GitBook](https://docs.tonalytica.redoubt.online/api-reference#api-authentication)\n\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "TONalytica API Client",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://docs.tonalytica.redoubt.online/",
"Github": "https://github.com/re-doubt/tonalytica-api-client",
"Homepage": "https://tonalytica.redoubt.online/"
},
"split_keywords": [
"tonalytica",
"redoubt",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f6b4630a966e8d25c0fb1cba8a5e1244daee79ed1ecbeea3e52d7932acdd23c4",
"md5": "9ed2a03f729b8fa5df18d620cb19b9f8",
"sha256": "0f95936b6fe7ff7a78818df844654361842870ccbe3cbe7484b7f2907c8ea6df"
},
"downloads": -1,
"filename": "tonalytica_client-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ed2a03f729b8fa5df18d620cb19b9f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10205,
"upload_time": "2023-06-09T10:43:28",
"upload_time_iso_8601": "2023-06-09T10:43:28.174121Z",
"url": "https://files.pythonhosted.org/packages/f6/b4/630a966e8d25c0fb1cba8a5e1244daee79ed1ecbeea3e52d7932acdd23c4/tonalytica_client-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a95f0d8e52b6dc47433e202805b15f62e1fec3a185892b46cf247db4412893e9",
"md5": "08f031b8a8421bdf7723905ef401f14d",
"sha256": "381d287543a574444d19a6b3c893040f9801f14d48049e886af3965d1ef590d7"
},
"downloads": -1,
"filename": "tonalytica-client-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "08f031b8a8421bdf7723905ef401f14d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 12253,
"upload_time": "2023-06-09T10:43:30",
"upload_time_iso_8601": "2023-06-09T10:43:30.192755Z",
"url": "https://files.pythonhosted.org/packages/a9/5f/0d8e52b6dc47433e202805b15f62e1fec3a185892b46cf247db4412893e9/tonalytica-client-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-09 10:43:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "re-doubt",
"github_project": "tonalytica-api-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tonalytica-client"
}
JSON
