From d30b98a36498c5b343f5ae6f2aab15c2e10eda27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Tue, 29 Aug 2023 23:19:34 +0100 Subject: [PATCH 1/9] Add missing options, functionality to DashboardLink Includes the ability to create direct links or a list of dashboard links, extra options like includeVars and targetBlank. --- grafanalib/core.py | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index 4192806b..9c87ae57 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -5,13 +5,14 @@ encourage it by way of some defaults. Rather, they are ways of building arbitrary Grafana JSON. """ - +from __future__ import annotations import itertools import math import string import warnings from numbers import Number +from typing import Literal, Optional import attr from attr.validators import in_, instance_of @@ -74,7 +75,7 @@ def to_json_data(self): FLOT = 'flot' ABSOLUTE_TYPE = 'absolute' -DASHBOARD_TYPE = 'dashboard' +DASHBOARD_TYPE = Literal['dashboards', 'link'] ROW_TYPE = 'row' GRAPH_TYPE = 'graph' DISCRETE_TYPE = 'natel-discrete-panel' @@ -300,6 +301,9 @@ def to_json_data(self): DEFAULT_AUTO_COUNT = 30 DEFAULT_MIN_AUTO_INTERVAL = '10s' +DASHBOARD_LINK_ICON = Literal['bolt', 'cloud', 'dashboard', 'doc', + 'external link', 'info', 'question'] + @attr.s class Mapping(object): @@ -875,24 +879,36 @@ def to_json_data(self): @attr.s class DashboardLink(object): + as_dropdown = attr.ib(default=False, validator=instance_of(bool)) dashboard = attr.ib() - uri = attr.ib() + icon = attr.ib(default='external link', type=DASHBOARD_LINK_ICON, + validator=in_(DASHBOARD_LINK_ICON.__args__)) + include_vars = attr.ib(default=False, validator=instance_of(bool)) keepTime = attr.ib( default=True, validator=instance_of(bool), ) - title = attr.ib(default=None) - type = attr.ib(default=DASHBOARD_TYPE) + tags = attr.ib(factory=list, type=list[str]) + target_blank = attr.ib(default=False, validator=instance_of(bool)) + title = attr.ib(default=None, type=Optional[str]) + tooltip = attr.ib(default="", type=str, validator=instance_of(str)) + type = attr.ib(default='dashboard', type=DASHBOARD_TYPE, + validator=in_(DASHBOARD_TYPE.__args__)) + uri = attr.ib(default="", validator=instance_of(str)) def to_json_data(self): title = self.dashboard if self.title is None else self.title return { - 'dashUri': self.uri, - 'dashboard': self.dashboard, + 'asDropdown': self.as_dropdown, + 'icon': self.icon, + 'includeVars': self.include_vars, 'keepTime': self.keepTime, + 'tags': self.tags, + 'targetBlank': self.target_blank, 'title': title, + 'tooltip': self.tooltip, 'type': self.type, - 'url': self.uri, + 'uri': self.uri } From 88a6e4bfa5d3d18ab82f38ebfce59809b5c758c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Wed, 30 Aug 2023 09:18:00 +0100 Subject: [PATCH 2/9] Add docstring to DashboardLink, remove the unused `dashboard` param Removing this parameter is a breaking change... It didn't actually impact the generated link, other than acting as an alias to 'title' in some cases. If preferred, I can restore it to retain that alias behaviour, and perhaps add a warning log message? --- grafanalib/core.py | 51 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index 9c87ae57..794e9298 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -12,7 +12,7 @@ import string import warnings from numbers import Number -from typing import Literal, Optional +from typing import Literal import attr from attr.validators import in_, instance_of @@ -879,33 +879,62 @@ def to_json_data(self): @attr.s class DashboardLink(object): - as_dropdown = attr.ib(default=False, validator=instance_of(bool)) - dashboard = attr.ib() + """Create a link to other dashboards, or external resources. + + Dashboard Links come in two flavours; a list of dashboards, or a direct + link to an arbitrary URL. These are controlled by the ``type`` parameter. + A dashboard list targets a given set of tags, whereas for a link you must + also provide the URL. + + See `the documentation ` + for more information. + + :param asDropdown: Controls if the list appears in a dropdown rather than + tiling across the dashboard. Affects dashboard_list type only. Defaults + to False + :param icon: Set the icon, from a predefined list. See + ``grafanalib.core.DASHBOARD_LINK_ICON`` for allowed values. Affects + the 'link' type only. Defaults to 'external link' + :param includeVars: Controls if data variables from the current dashboard + are passed as query parameters to the linked target. Defaults to False + :param keepTime: Controls if the current time range is passed as query + parameters to the linked target. Defaults to False + :param tags: A list of tags used to select dashboards for the link. + Affects the 'dashboard_list' type only. Defaults to an empty list + :param targetBlank: Controls if the link opens in a new tab. Defaults + to False + :param tooltip: Tooltip text that appears when hovering over the link. + Affects the 'link' type only. Defaults to an empty string + :param type: Controls the type of DashboardLink generated. Must be + one of 'dashboard_list' or 'link'. + :param uri: The url target of the external link. Affects the 'link' + type only. + """ + asDropdown = attr.ib(default=False, validator=instance_of(bool)) icon = attr.ib(default='external link', type=DASHBOARD_LINK_ICON, validator=in_(DASHBOARD_LINK_ICON.__args__)) - include_vars = attr.ib(default=False, validator=instance_of(bool)) + includeVars = attr.ib(default=False, validator=instance_of(bool)) keepTime = attr.ib( default=True, validator=instance_of(bool), ) tags = attr.ib(factory=list, type=list[str]) - target_blank = attr.ib(default=False, validator=instance_of(bool)) - title = attr.ib(default=None, type=Optional[str]) + targetBlank = attr.ib(default=False, validator=instance_of(bool)) + title = attr.ib(default="", type=str) tooltip = attr.ib(default="", type=str, validator=instance_of(str)) type = attr.ib(default='dashboard', type=DASHBOARD_TYPE, validator=in_(DASHBOARD_TYPE.__args__)) uri = attr.ib(default="", validator=instance_of(str)) def to_json_data(self): - title = self.dashboard if self.title is None else self.title return { - 'asDropdown': self.as_dropdown, + 'asDropdown': self.asDropdown, 'icon': self.icon, - 'includeVars': self.include_vars, + 'includeVars': self.includeVars, 'keepTime': self.keepTime, 'tags': self.tags, - 'targetBlank': self.target_blank, - 'title': title, + 'targetBlank': self.targetBlank, + 'title': self.title, 'tooltip': self.tooltip, 'type': self.type, 'uri': self.uri From bc8fe56b9a0082bad17b3b4d819270a26ea4f79c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Wed, 30 Aug 2023 09:19:31 +0100 Subject: [PATCH 3/9] Update changelog --- CHANGELOG.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index cf0c30de..b9c80561 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -5,6 +5,10 @@ Changelog 0.x.x (?) ================== +* Extended DashboardLink to support links to dashboards and urls, as per the docs_ + +.. _`docs`: https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/manage-dashboard-links/#dashboard-links + * Added ... * Added Minimum option for Timeseries * Added Maximum option for Timeseries From 412d8dbc6e780884ef51f0b419e91c478ae36a71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Wed, 30 Aug 2023 09:27:48 +0100 Subject: [PATCH 4/9] Fix the DashboardLink type param in docstrings --- grafanalib/core.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index 794e9298..da6b375c 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -890,7 +890,7 @@ class DashboardLink(object): for more information. :param asDropdown: Controls if the list appears in a dropdown rather than - tiling across the dashboard. Affects dashboard_list type only. Defaults + tiling across the dashboard. Affects 'dashboards' type only. Defaults to False :param icon: Set the icon, from a predefined list. See ``grafanalib.core.DASHBOARD_LINK_ICON`` for allowed values. Affects @@ -900,13 +900,13 @@ class DashboardLink(object): :param keepTime: Controls if the current time range is passed as query parameters to the linked target. Defaults to False :param tags: A list of tags used to select dashboards for the link. - Affects the 'dashboard_list' type only. Defaults to an empty list + Affects the 'dashboards' type only. Defaults to an empty list :param targetBlank: Controls if the link opens in a new tab. Defaults to False :param tooltip: Tooltip text that appears when hovering over the link. Affects the 'link' type only. Defaults to an empty string :param type: Controls the type of DashboardLink generated. Must be - one of 'dashboard_list' or 'link'. + one of 'dashboards' or 'link'. :param uri: The url target of the external link. Affects the 'link' type only. """ From cdda04ede261ca449fb09353e0a26a7f7f4b57b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Tue, 5 Sep 2023 10:40:38 +0100 Subject: [PATCH 5/9] Fix the field name for URL in DashboardLinks --- grafanalib/core.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index da6b375c..ef30edcf 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -937,7 +937,7 @@ def to_json_data(self): 'title': self.title, 'tooltip': self.tooltip, 'type': self.type, - 'uri': self.uri + 'url': self.uri } From c949a8b4dee535b9aa49aa362bcf2345dea63121 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Thu, 7 Sep 2023 15:19:11 +0100 Subject: [PATCH 6/9] Correct type annotations for py37, py38 --- grafanalib/core.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index ef30edcf..c96822e0 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -910,21 +910,21 @@ class DashboardLink(object): :param uri: The url target of the external link. Affects the 'link' type only. """ - asDropdown = attr.ib(default=False, validator=instance_of(bool)) - icon = attr.ib(default='external link', type=DASHBOARD_LINK_ICON, - validator=in_(DASHBOARD_LINK_ICON.__args__)) - includeVars = attr.ib(default=False, validator=instance_of(bool)) - keepTime = attr.ib( + asDropdown: bool = attr.ib(default=False, validator=instance_of(bool)) + icon: DASHBOARD_LINK_ICON = attr.ib(default='external link', + validator=in_(DASHBOARD_LINK_ICON.__args__)) + includeVars: bool = attr.ib(default=False, validator=instance_of(bool)) + keepTime: bool = attr.ib( default=True, validator=instance_of(bool), ) - tags = attr.ib(factory=list, type=list[str]) - targetBlank = attr.ib(default=False, validator=instance_of(bool)) - title = attr.ib(default="", type=str) - tooltip = attr.ib(default="", type=str, validator=instance_of(str)) - type = attr.ib(default='dashboard', type=DASHBOARD_TYPE, - validator=in_(DASHBOARD_TYPE.__args__)) - uri = attr.ib(default="", validator=instance_of(str)) + tags: list[str] = attr.ib(factory=list) + targetBlank: bool = attr.ib(default=False, validator=instance_of(bool)) + title: str = attr.ib(default="") + tooltip: str = attr.ib(default="", validator=instance_of(str)) + type: DASHBOARD_TYPE = attr.ib(default='dashboard', + validator=in_(DASHBOARD_TYPE.__args__)) + uri: str = attr.ib(default="", validator=instance_of(str)) def to_json_data(self): return { From 4424611e78a14633b00f95a47d71a0928b18722a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Thu, 7 Sep 2023 15:21:22 +0100 Subject: [PATCH 7/9] Fix flake8 warnigns in docstring for DashboardLink --- grafanalib/core.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index c96822e0..946f5e13 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -881,9 +881,9 @@ def to_json_data(self): class DashboardLink(object): """Create a link to other dashboards, or external resources. - Dashboard Links come in two flavours; a list of dashboards, or a direct - link to an arbitrary URL. These are controlled by the ``type`` parameter. - A dashboard list targets a given set of tags, whereas for a link you must + Dashboard Links come in two flavours; a list of dashboards, or a direct + link to an arbitrary URL. These are controlled by the ``type`` parameter. + A dashboard list targets a given set of tags, whereas for a link you must also provide the URL. See `the documentation ` From d13d4bbb7d9470965dbe8a20ac34b9142766d36f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Mon, 11 Sep 2023 16:27:57 +0100 Subject: [PATCH 8/9] Add tests for DashboardLink --- grafanalib/core.py | 4 ++-- grafanalib/tests/test_core.py | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/grafanalib/core.py b/grafanalib/core.py index 946f5e13..f9c3409e 100644 --- a/grafanalib/core.py +++ b/grafanalib/core.py @@ -918,11 +918,11 @@ class DashboardLink(object): default=True, validator=instance_of(bool), ) - tags: list[str] = attr.ib(factory=list) + tags: list[str] = attr.ib(factory=list, validator=instance_of(list)) targetBlank: bool = attr.ib(default=False, validator=instance_of(bool)) title: str = attr.ib(default="") tooltip: str = attr.ib(default="", validator=instance_of(str)) - type: DASHBOARD_TYPE = attr.ib(default='dashboard', + type: DASHBOARD_TYPE = attr.ib(default='dashboards', validator=in_(DASHBOARD_TYPE.__args__)) uri: str = attr.ib(default="", validator=instance_of(str)) diff --git a/grafanalib/tests/test_core.py b/grafanalib/tests/test_core.py index 2b03610b..1a96aea1 100644 --- a/grafanalib/tests/test_core.py +++ b/grafanalib/tests/test_core.py @@ -1190,3 +1190,36 @@ def test_sql_target_with_source_files(): assert t.to_json_data()["targets"][0].rawQuery is True assert t.to_json_data()["targets"][0].rawSql == "SELECT example\nFROM test\nWHERE example='example' AND example_date BETWEEN '1970-01-01' AND '1971-01-01';\n" print(t.to_json_data()["targets"][0]) + +class TestDashboardLink(): + + def test_validators(self): + with pytest.raises(ValueError): + G.DashboardLink( + type='dashboard', + ) + with pytest.raises(ValueError): + G.DashboardLink( + icon='not an icon' + ) + + def test_initialisation(self): + dl = G.DashboardLink().to_json_data() + assert dl['asDropdown'] is False + assert dl['icon'] == 'external link' + assert dl['includeVars'] is False + assert dl['keepTime'] is True + assert not dl['tags'] + assert dl['targetBlank'] is False + assert dl['title'] == "" + assert dl['tooltip'] == "" + assert dl['type'] == 'dashboards' + assert dl['url'] == "" + + url = 'https://grafana.com' + dl = G.DashboardLink( + uri=url, + type='link' + ).to_json_data() + assert dl['url'] == url + assert dl['type'] == 'link' From fb44dd69ffce8bf24d5e5bccaef08a0cde1b4cbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draic=20Calpin?= Date: Tue, 12 Sep 2023 15:18:27 +0100 Subject: [PATCH 9/9] Fix flake8 complaints in tests/test_core.py --- grafanalib/tests/test_core.py | 1 + 1 file changed, 1 insertion(+) diff --git a/grafanalib/tests/test_core.py b/grafanalib/tests/test_core.py index 1a96aea1..02885796 100644 --- a/grafanalib/tests/test_core.py +++ b/grafanalib/tests/test_core.py @@ -1191,6 +1191,7 @@ def test_sql_target_with_source_files(): assert t.to_json_data()["targets"][0].rawSql == "SELECT example\nFROM test\nWHERE example='example' AND example_date BETWEEN '1970-01-01' AND '1971-01-01';\n" print(t.to_json_data()["targets"][0]) + class TestDashboardLink(): def test_validators(self):