# grafana-client
[](https://github.com/panodata/grafana-client/actions?query=workflow%3ATest)
[](https://codecov.io/gh/panodata/grafana-client/)
[](https://github.com/panodata/grafana-client/blob/main/LICENSE)
[](https://pypi.org/project/grafana-client/)
[](https://github.com/grafana/grafana)
[](https://pypi.org/project/grafana-client/)
[](https://pypi.org/project/grafana-client/)
[](https://pypi.org/project/grafana-client/)
<!-- [](https://anaconda.org/panodata/grafana-client) -->
## About
A client library for accessing the Grafana HTTP API, written in Python.
## Setup
Install the package from PyPI.
```
pip install grafana-client --upgrade
```
## Usage
### API overview
This section gives you an idea about how to use the API on behalf of a few
samples.
```python
from grafana_client import GrafanaApi
# Connect to Grafana API endpoint using the `GrafanaApi` class
grafana = GrafanaApi.from_url(
"https://username:password@daq.example.org/grafana/")
# Create user
user = grafana.admin.create_user({
"name": "User",
"email": "user@example.org",
"login": "user",
"password": "userpassword",
"OrgId": 1,
})
# Change user password
user = grafana.admin.change_user_password(2, "newpassword")
# Search dashboards based on tag
grafana.search.search_dashboards(tag="applications")
# Find a user by email
user = grafana.users.find_user("test@example.org")
# Add user to team 2
grafana.teams.add_team_member(2, user["id"])
# Create or update a dashboard
grafana.dashboard.update_dashboard(
dashboard={"dashboard": {...}, "folderId": 0, "overwrite": True})
# Delete a dashboard by UID
grafana.dashboard.delete_dashboard(dashboard_uid="foobar")
# Create organization
grafana.organization.create_organization(
organization={"name": "new_organization"})
```
Or using asynchronous code... the interfaces are identical except for the fact that you will handle coroutines (async/await).
```python
from grafana_client import AsyncGrafanaApi
import asyncio
async def main():
# Connect to Grafana API endpoint using the `GrafanaApi` class
grafana = AsyncGrafanaApi.from_url("https://username:password@daq.example.org/grafana/")
# Create user
user = await grafana.admin.create_user({
"name": "User",
"email": "user@example.org",
"login": "user",
"password": "userpassword",
"OrgId": 1,
})
# Change user password
user = await grafana.admin.change_user_password(2, "newpassword")
asyncio.run(main())
```
### Example programs
There are complete example programs to get you started within the [examples
folder] of this repository.
Feel free to use them as blueprints for your own programs. If you think your
exercises could be useful for others, don't hesitate to share them back.
## Authentication
There are several ways to authenticate to the Grafana HTTP API.
1. Anonymous access
2. Grafana API token
3. HTTP Basic Authentication
4. HTTP Header Authentication
The [Grafana Admin API] is a subset of the Grafana API. For accessing those API
resources, you will need to use HTTP Basic Authentication.
```python
from grafana_client import GrafanaApi, HeaderAuth, TokenAuth
# 1. Anonymous access
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
)
# 2. Use Grafana API token.
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
credential=TokenAuth(token="eyJrIjoiWHg...dGJpZCI6MX0="),
)
# 3. Use HTTP basic authentication.
grafana = GrafanaApi.from_url(
url="https://username:password@daq.example.org/grafana/",
)
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
credential=("username", "password")
)
# 4. Use HTTP Header authentication.
grafana = GrafanaApi.from_url(
url="https://daq.example.org/grafana/",
credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"),
)
# Optionally turn off TLS certificate verification.
grafana = GrafanaApi.from_url(
url="https://username:password@daq.example.org/grafana/?verify=false",
)
# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.
grafana = GrafanaApi.from_env()
```
Please note that, on top of the specific examples above, the object obtained by
`credential` can be an arbitrary `niquests.auth.AuthBase` instance.
## Selecting Organizations
If the Grafana API is authenticated as a user (for example, with HTTP Basic Authentication),
it will use the user's current organization context.
That context can be changed with the `GrafanaApi.user.switch_actual_user_organisation` function.
```python
grafana.user.switch_actual_user_organisation(1)
```
An instance of `GrafanaApi` can also be bound to a single organization with the `organization_id` parameter,
ensuring that all requests will be made to that organization.
This parameter will cause `GrafanaClient` to use the [X-Grafana-Org-Id header].
```python
grafana = GrafanaApi(..., organization_id=1)
```
API Tokens are bound to a single organization, so the `organization_id` parameter does not need to be specified.
## Timeout settings
The default timeout value is five seconds, used for both connect and read timeout.
The constructors of `GrafanaApi` and `GrafanaClient`, as well as the factory methods
`from_url` and `from_env` accept the `timeout` argument, which can be obtained as a
scalar `float` value, or as a tuple of `(<read timeout>, <connect timeout>)`.
## Proxy
The underlying `niquests` library honors the `HTTP_PROXY` and `HTTPS_PROXY`
environment variables. Setting them before invoking an application using
`grafana-client` has been confirmed to work. For example:
```
export HTTP_PROXY=10.10.1.10:3128
export HTTPS_PROXY=10.10.1.11:1080
```
## DNS Resolver
`niquests` support using a custom DNS resolver, like but not limited, DNS-over-HTTPS, and DNS-over-QUIC.
You will have to set `NIQUESTS_DNS_URL` environment variable. For example:
```
export NIQUESTS_DNS_URL="doh+cloudflare://"
```
See the [documentation](https://niquests.readthedocs.io/en/latest/user/quickstart.html#set-dns-via-environment) to learn
more about accepted URL parameters and protocols.
## Details
This section of the documentation outlines which parts of the Grafana HTTP API
are supported, and to which degree. See also [Grafana HTTP API reference].
### Compatibility
`grafana-client` is largely compatible with Grafana 5.x-10.x. However, earlier
versions of Grafana might not support certain features or subsystems.
### Overview
| API | Status |
|---|---|
| Admin | + |
| Alerting | +- |
| Alerting Notification Channels | + |
| Alerting Provisioning | + |
| Annotations | + |
| Authentication | +- |
| Dashboard | + |
| Dashboard Versions | + |
| Dashboard Permissions | + |
| Data Source | + |
| Data Source Permissions | + |
| External Group Sync | + |
| Folder | + |
| Folder Permissions | + |
| Folder/Dashboard Search | +- |
| Health | + |
| Library Elements | + |
| Organisation | + |
| Other | + |
| Plugin | + |
| Preferences | + |
| Rbac | +- |
| Snapshot | + |
| Teams | + |
| User | + |
### Data source health check
#### Introduction
For checking whether a Grafana data source is healthy, Grafana 9 and newer has
a server-side data source health check API. For earlier versions, a client-side
implementation is provided.
This implementation works in the same manner as the "Save & test" button works,
when creating a data source in the user interface.
The feature can be explored through corresponding client programs in the
[examples folder] of this repository.
#### Compatibility
The minimum required version for data source health checks is Grafana 7.
Prometheus only works on Grafana 8 and newer.
#### Data source coverage
Health checks are supported for these Grafana data source types.
- CrateDB
- Elasticsearch
- Graphite
- InfluxDB
- Jaeger
- Loki
- Microsoft SQL Server
- OpenTSDB
- PostgreSQL
- Prometheus
- Tempo
- Testdata
- Zipkin
We are humbly asking the community to contribute adapters for other data
source types, popular or not.
## Applications
A list of applications based on `grafana-client`.
- [grafana-import-tool](https://github.com/peekjef72/grafana-import-tool)
- [grafana-ldap-sync-script](https://github.com/NovatecConsulting/grafana-ldap-sync-script)
- [grafana-snapshots-tool](https://github.com/peekjef72/grafana-snapshots-tool)
- [grafana-wtf](https://github.com/panodata/grafana-wtf)
- [nixops-grafana](https://github.com/tewfik-ghariani/nixops-grafana)
## Project information
### History
The library was originally conceived by [Andrew Prokhorenkov] and contributors
as [grafana_api]. Thank you very much for your efforts!
At [future maintenance of `grafana_api`], we discussed the need for a fork
because the repository stopped receiving updates since more than a year.
While forking it, we renamed the package to `grafana-client` and slightly
trimmed the module namespace.
### Acknowledgements
Thanks to the original authors and all [contributors] who helped to co-create
and conceive this software in one way or another. You know who you are.
### Contributing
Any kind of contribution and feedback are very much welcome! Just create an
issue or submit a patch if you think we should include a new feature, or to
report or fix a bug.
The issue tracker URL is: https://github.com/panodata/grafana-client/issues
### Development
In order to set up a development environment for `grafana-client`, please
follow the [development documentation].
### License
`grafana-client` is licensed under the terms of the MIT License, see [LICENSE] file.
[Andrew Prokhorenkov]: https://github.com/m0nhawk/grafana_api
[contributors]: https://github.com/panodata/grafana-client/graphs/contributors
[development documentation]: https://github.com/panodata/grafana-client/blob/main/docs/development.md
[examples folder]: https://github.com/panodata/grafana-client/tree/main/examples
[future maintenance of `grafana_api`]: https://github.com/m0nhawk/grafana_api/issues/88
[grafana_api]: https://github.com/m0nhawk/grafana_api
[Grafana Admin API]: https://grafana.com/docs/grafana/latest/http_api/admin/
[X-Grafana-Org-Id header]: https://grafana.com/docs/grafana/latest/developers/http_api/auth/#x-grafana-org-id-header
[Grafana HTTP API reference]: https://grafana.com/docs/grafana/latest/http_api/
[LICENSE]: https://github.com/panodata/grafana-client/blob/main/LICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/panodata/grafana-client",
"name": "grafana-client",
"maintainer": "Andreas Motl",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "andreas.motl@panodata.org",
"keywords": "grafana http api grafana-client grafana-api http-client grafana-utils grafana-automation grafana-toolbox",
"author": "Andrew Prokhorenkov",
"author_email": "andrew.prokhorenkov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/fc/390e9867456269474c93ed0b2a7e5f95de9a1fbac50af6c7f53cdb914317/grafana_client-4.2.0.tar.gz",
"platform": null,
"description": "# grafana-client\n\n[](https://github.com/panodata/grafana-client/actions?query=workflow%3ATest)\n[](https://codecov.io/gh/panodata/grafana-client/)\n[](https://github.com/panodata/grafana-client/blob/main/LICENSE) \n\n[](https://pypi.org/project/grafana-client/)\n[](https://github.com/grafana/grafana)\n\n[](https://pypi.org/project/grafana-client/)\n[](https://pypi.org/project/grafana-client/)\n[](https://pypi.org/project/grafana-client/)\n<!-- [](https://anaconda.org/panodata/grafana-client) -->\n\n\n## About\n\nA client library for accessing the Grafana HTTP API, written in Python.\n\n\n## Setup\n\nInstall the package from PyPI.\n```\npip install grafana-client --upgrade\n```\n\n\n## Usage\n\n### API overview\n\nThis section gives you an idea about how to use the API on behalf of a few\nsamples.\n\n```python\nfrom grafana_client import GrafanaApi\n\n# Connect to Grafana API endpoint using the `GrafanaApi` class\ngrafana = GrafanaApi.from_url(\n \"https://username:password@daq.example.org/grafana/\")\n\n# Create user\nuser = grafana.admin.create_user({\n \"name\": \"User\", \n \"email\": \"user@example.org\", \n \"login\": \"user\", \n \"password\": \"userpassword\", \n \"OrgId\": 1,\n})\n\n# Change user password\nuser = grafana.admin.change_user_password(2, \"newpassword\")\n\n# Search dashboards based on tag\ngrafana.search.search_dashboards(tag=\"applications\")\n\n# Find a user by email\nuser = grafana.users.find_user(\"test@example.org\")\n\n# Add user to team 2\ngrafana.teams.add_team_member(2, user[\"id\"])\n\n# Create or update a dashboard\ngrafana.dashboard.update_dashboard(\n dashboard={\"dashboard\": {...}, \"folderId\": 0, \"overwrite\": True})\n\n# Delete a dashboard by UID\ngrafana.dashboard.delete_dashboard(dashboard_uid=\"foobar\")\n\n# Create organization\ngrafana.organization.create_organization(\n organization={\"name\": \"new_organization\"})\n```\n\nOr using asynchronous code... the interfaces are identical except for the fact that you will handle coroutines (async/await).\n\n```python\nfrom grafana_client import AsyncGrafanaApi\nimport asyncio\n\nasync def main():\n # Connect to Grafana API endpoint using the `GrafanaApi` class\n grafana = AsyncGrafanaApi.from_url(\"https://username:password@daq.example.org/grafana/\")\n \n # Create user\n user = await grafana.admin.create_user({\n \"name\": \"User\", \n \"email\": \"user@example.org\", \n \"login\": \"user\", \n \"password\": \"userpassword\", \n \"OrgId\": 1,\n })\n \n # Change user password\n user = await grafana.admin.change_user_password(2, \"newpassword\")\n\nasyncio.run(main())\n```\n\n### Example programs\n\nThere are complete example programs to get you started within the [examples\nfolder] of this repository.\n\nFeel free to use them as blueprints for your own programs. If you think your\nexercises could be useful for others, don't hesitate to share them back.\n\n\n## Authentication\n\nThere are several ways to authenticate to the Grafana HTTP API.\n\n1. Anonymous access\n2. Grafana API token\n3. HTTP Basic Authentication\n4. HTTP Header Authentication\n\nThe [Grafana Admin API] is a subset of the Grafana API. For accessing those API\nresources, you will need to use HTTP Basic Authentication.\n\n```python\nfrom grafana_client import GrafanaApi, HeaderAuth, TokenAuth\n\n# 1. Anonymous access\ngrafana = GrafanaApi.from_url(\n url=\"https://daq.example.org/grafana/\",\n)\n\n# 2. Use Grafana API token.\ngrafana = GrafanaApi.from_url(\n url=\"https://daq.example.org/grafana/\",\n credential=TokenAuth(token=\"eyJrIjoiWHg...dGJpZCI6MX0=\"),\n)\n\n# 3. Use HTTP basic authentication.\ngrafana = GrafanaApi.from_url(\n url=\"https://username:password@daq.example.org/grafana/\",\n)\ngrafana = GrafanaApi.from_url(\n url=\"https://daq.example.org/grafana/\",\n credential=(\"username\", \"password\")\n)\n\n# 4. Use HTTP Header authentication.\ngrafana = GrafanaApi.from_url(\n url=\"https://daq.example.org/grafana/\",\n credential=HeaderAuth(name=\"X-WEBAUTH-USER\", value=\"foobar\"),\n)\n\n# Optionally turn off TLS certificate verification.\ngrafana = GrafanaApi.from_url(\n url=\"https://username:password@daq.example.org/grafana/?verify=false\",\n)\n\n# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.\ngrafana = GrafanaApi.from_env()\n```\n\nPlease note that, on top of the specific examples above, the object obtained by\n`credential` can be an arbitrary `niquests.auth.AuthBase` instance.\n\n## Selecting Organizations\n\nIf the Grafana API is authenticated as a user (for example, with HTTP Basic Authentication),\nit will use the user's current organization context.\nThat context can be changed with the `GrafanaApi.user.switch_actual_user_organisation` function.\n\n```python\ngrafana.user.switch_actual_user_organisation(1)\n```\n\nAn instance of `GrafanaApi` can also be bound to a single organization with the `organization_id` parameter,\nensuring that all requests will be made to that organization.\nThis parameter will cause `GrafanaClient` to use the [X-Grafana-Org-Id header].\n\n```python\ngrafana = GrafanaApi(..., organization_id=1)\n```\n\nAPI Tokens are bound to a single organization, so the `organization_id` parameter does not need to be specified.\n\n## Timeout settings\n\nThe default timeout value is five seconds, used for both connect and read timeout.\n\nThe constructors of `GrafanaApi` and `GrafanaClient`, as well as the factory methods\n`from_url` and `from_env` accept the `timeout` argument, which can be obtained as a\nscalar `float` value, or as a tuple of `(<read timeout>, <connect timeout>)`.\n\n\n## Proxy\n\nThe underlying `niquests` library honors the `HTTP_PROXY` and `HTTPS_PROXY`\nenvironment variables. Setting them before invoking an application using\n`grafana-client` has been confirmed to work. For example:\n```\nexport HTTP_PROXY=10.10.1.10:3128\nexport HTTPS_PROXY=10.10.1.11:1080\n```\n\n## DNS Resolver\n\n`niquests` support using a custom DNS resolver, like but not limited, DNS-over-HTTPS, and DNS-over-QUIC.\nYou will have to set `NIQUESTS_DNS_URL` environment variable. For example:\n```\nexport NIQUESTS_DNS_URL=\"doh+cloudflare://\"\n```\n\nSee the [documentation](https://niquests.readthedocs.io/en/latest/user/quickstart.html#set-dns-via-environment) to learn\nmore about accepted URL parameters and protocols.\n\n## Details\n\nThis section of the documentation outlines which parts of the Grafana HTTP API\nare supported, and to which degree. See also [Grafana HTTP API reference].\n\n### Compatibility\n\n`grafana-client` is largely compatible with Grafana 5.x-10.x. However, earlier\nversions of Grafana might not support certain features or subsystems.\n\n### Overview\n\n| API | Status |\n|---|---|\n| Admin | + |\n| Alerting | +- |\n| Alerting Notification Channels | + |\n| Alerting Provisioning | + |\n| Annotations | + |\n| Authentication | +- |\n| Dashboard | + |\n| Dashboard Versions | + |\n| Dashboard Permissions | + |\n| Data Source | + |\n| Data Source Permissions | + |\n| External Group Sync | + |\n| Folder | + |\n| Folder Permissions | + |\n| Folder/Dashboard Search | +- |\n| Health | + |\n| Library Elements | + |\n| Organisation | + |\n| Other | + |\n| Plugin | + |\n| Preferences | + |\n| Rbac | +- |\n| Snapshot | + |\n| Teams | + |\n| User | + |\n\n\n### Data source health check\n\n#### Introduction\n\nFor checking whether a Grafana data source is healthy, Grafana 9 and newer has\na server-side data source health check API. For earlier versions, a client-side\nimplementation is provided.\n\nThis implementation works in the same manner as the \"Save & test\" button works,\nwhen creating a data source in the user interface.\n\nThe feature can be explored through corresponding client programs in the\n[examples folder] of this repository.\n\n#### Compatibility\n\nThe minimum required version for data source health checks is Grafana 7.\nPrometheus only works on Grafana 8 and newer.\n\n#### Data source coverage\n\nHealth checks are supported for these Grafana data source types.\n\n- CrateDB\n- Elasticsearch\n- Graphite\n- InfluxDB\n- Jaeger\n- Loki\n- Microsoft SQL Server\n- OpenTSDB\n- PostgreSQL\n- Prometheus\n- Tempo\n- Testdata\n- Zipkin\n\nWe are humbly asking the community to contribute adapters for other data\nsource types, popular or not.\n\n\n## Applications\n\nA list of applications based on `grafana-client`.\n\n- [grafana-import-tool](https://github.com/peekjef72/grafana-import-tool)\n- [grafana-ldap-sync-script](https://github.com/NovatecConsulting/grafana-ldap-sync-script)\n- [grafana-snapshots-tool](https://github.com/peekjef72/grafana-snapshots-tool)\n- [grafana-wtf](https://github.com/panodata/grafana-wtf)\n- [nixops-grafana](https://github.com/tewfik-ghariani/nixops-grafana)\n\n\n## Project information\n\n### History\n\nThe library was originally conceived by [Andrew Prokhorenkov] and contributors\nas [grafana_api]. Thank you very much for your efforts!\n\nAt [future maintenance of `grafana_api`], we discussed the need for a fork\nbecause the repository stopped receiving updates since more than a year.\nWhile forking it, we renamed the package to `grafana-client` and slightly\ntrimmed the module namespace.\n\n\n### Acknowledgements\n\nThanks to the original authors and all [contributors] who helped to co-create\nand conceive this software in one way or another. You know who you are.\n\n\n### Contributing\n\nAny kind of contribution and feedback are very much welcome! Just create an\nissue or submit a patch if you think we should include a new feature, or to \nreport or fix a bug.\n\nThe issue tracker URL is: https://github.com/panodata/grafana-client/issues\n\n\n### Development\n\nIn order to set up a development environment for `grafana-client`, please\nfollow the [development documentation].\n\n\n### License\n\n`grafana-client` is licensed under the terms of the MIT License, see [LICENSE] file.\n\n\n[Andrew Prokhorenkov]: https://github.com/m0nhawk/grafana_api\n[contributors]: https://github.com/panodata/grafana-client/graphs/contributors\n[development documentation]: https://github.com/panodata/grafana-client/blob/main/docs/development.md\n[examples folder]: https://github.com/panodata/grafana-client/tree/main/examples\n[future maintenance of `grafana_api`]: https://github.com/m0nhawk/grafana_api/issues/88\n[grafana_api]: https://github.com/m0nhawk/grafana_api\n[Grafana Admin API]: https://grafana.com/docs/grafana/latest/http_api/admin/\n[X-Grafana-Org-Id header]: https://grafana.com/docs/grafana/latest/developers/http_api/auth/#x-grafana-org-id-header\n[Grafana HTTP API reference]: https://grafana.com/docs/grafana/latest/http_api/\n[LICENSE]: https://github.com/panodata/grafana-client/blob/main/LICENSE\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A client library for accessing the Grafana HTTP API, written in Python",
"version": "4.2.0",
"project_urls": {
"Homepage": "https://github.com/panodata/grafana-client",
"Source": "https://github.com/panodata/grafana-client",
"Tracker": "https://github.com/panodata/grafana-client/issues"
},
"split_keywords": [
"grafana",
"http",
"api",
"grafana-client",
"grafana-api",
"http-client",
"grafana-utils",
"grafana-automation",
"grafana-toolbox"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e608db64171f990579131d27ef774599fde5e85d15ad478f1494500b1e7151cc",
"md5": "9876644f31945ce9d14322fca8a35247",
"sha256": "fe505e7c22116785cec8c3d4af3debf2151da69ecf4f61d704797845cf4fde47"
},
"downloads": -1,
"filename": "grafana_client-4.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9876644f31945ce9d14322fca8a35247",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 103300,
"upload_time": "2024-10-18T15:30:53",
"upload_time_iso_8601": "2024-10-18T15:30:53.837116Z",
"url": "https://files.pythonhosted.org/packages/e6/08/db64171f990579131d27ef774599fde5e85d15ad478f1494500b1e7151cc/grafana_client-4.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0ffc390e9867456269474c93ed0b2a7e5f95de9a1fbac50af6c7f53cdb914317",
"md5": "09cb5dd3bc3cf8b35a40931f4814fb96",
"sha256": "3d7fb1f5abd4eddab2003855cc59326e836501102cfd4754ad6f4f1b4dff753a"
},
"downloads": -1,
"filename": "grafana_client-4.2.0.tar.gz",
"has_sig": false,
"md5_digest": "09cb5dd3bc3cf8b35a40931f4814fb96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 106217,
"upload_time": "2024-10-18T15:30:55",
"upload_time_iso_8601": "2024-10-18T15:30:55.762922Z",
"url": "https://files.pythonhosted.org/packages/0f/fc/390e9867456269474c93ed0b2a7e5f95de9a1fbac50af6c7f53cdb914317/grafana_client-4.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 15:30:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "panodata",
"github_project": "grafana-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "grafana-client"
}
JSON
