Improve "Organization preferences"

- Add model-based conversation, using `UserOrganizationPreferences`.
- Add `organization_preferences_patch`.
- Deprecate `organization_preference_get` and
  `organization_preference_update` in favor of
  `organization_preferences_get` and
  `organization_preferences_update` (singular vs. plural).

Author: amotl

grafana_client/elements/organization.py

@@ -1,3 +1,6 @@
+import warnings
+
+from ..model import UserOrganizationPreferences
 from .base import Base
 
 
@@ -180,25 +183,68 @@ def organization_preference_get(self):
         """
         :return:
         """
-        update_preference = "/org/preferences"
-        r = self.client.GET(update_preference)
-        return r
+        warnings.warn("Deprecated, please use `organization_preferences_get`", DeprecationWarning)
+        return self.organization_preferences_get()
 
     def organization_preference_update(self, theme="", home_dashboard_id=0, timezone="utc"):
         """
 
         :param theme:
         :param home_dashboard_id:
         :param timezone:
+        :return:
+        """
+        warnings.warn("Deprecated, please use `organization_preferences_update`", DeprecationWarning)
+        preferences = UserOrganizationPreferences(theme=theme, homeDashboardId=home_dashboard_id, timezone=timezone)
+        return self.organization_preferences_update(preferences)
+
+    def organization_preferences_get(self):
+        """
+        Retrieve preferences of current organization.
+
         :return:
         """
         update_preference = "/org/preferences"
+        r = self.client.GET(update_preference)
+        return r
+
+    def organization_preferences_update(self, preferences: UserOrganizationPreferences):
+        """
+        Update preferences of current organization as a whole.
+
+        From the `preferences` instance, only attributes with values `not None` will be submitted.
+        However, Grafana will reset all undefined attributes to its internal defaults.
+
+        If you want to update specific preference attributes, without touching the others,
+        please use the `organization_preferences_patch` method.
+
+        :param preferences:
+        :return:
+        """
+        update_preference = "/org/preferences"
+        data = preferences.asdict(filter_none=True)
+
         r = self.client.PUT(
             update_preference,
-            json={
-                "theme": theme,
-                "homeDashboardId": home_dashboard_id,
-                "timezone": timezone,
-            },
+            json=data,
+        )
+        return r
+
+    def organization_preferences_patch(self, preferences: UserOrganizationPreferences):
+        """
+        Update specific preferences of current organization.
+
+        From the `preferences` instance, only attributes with values `not None` will be submitted
+        and updated.
+
+        :param preferences:
+        :return:
+        """
+        update_preference = "/org/preferences"
+        data = preferences.asdict(filter_none=True)
+
+        r = self.client.PATCH(
+            update_preference,
+            json=data,
         )
         return r

grafana_client/model.py

@@ -67,3 +67,32 @@ def asdict_compact(self):
         data = self.asdict()
         del data["response"]
         return data
+
+
+@dataclasses.dataclass
+class UserOrganizationPreferences:
+    """
+    Request/response model for user- and organization-preferences.
+
+    https://grafana.com/docs/grafana/latest/developers/http_api/preferences/
+    """
+
+    homeDashboardId: Optional[int] = None
+    homeDashboardUID: Optional[str] = None
+    locale: Optional[str] = None
+    theme: Optional[str] = None
+    timezone: Optional[str] = None
+    weekStart: Optional[str] = None
+
+    def asdict(self, filter_none=False):
+        if filter_none:
+            return dataclasses.asdict(self, dict_factory=self.dict_factory_filter_none)
+        else:
+            return dataclasses.asdict(self)
+
+    @staticmethod
+    def dict_factory_filter_none(seq=None, **kwargs):
+        seq = [item for item in seq if item[1] is not None]
+        data = dict(seq)
+        data.update(kwargs)
+        return data

test/elements/test_organization.py

@@ -3,6 +3,7 @@
 import requests_mock
 
 from grafana_client import GrafanaApi
+from grafana_client.model import UserOrganizationPreferences
 
 
 class OrganizationTestCase(unittest.TestCase):
@@ -30,6 +31,29 @@ def test_organization_preference_update(self, m):
         )
         self.assertEqual(preference["message"], "Preferences updated")
 
+    @requests_mock.Mocker()
+    def test_organization_preferences_get(self, m):
+        m.get("http://localhost/api/org/preferences", json={"theme": "", "homeDashboardId": 0, "timezone": ""})
+
+        result = self.grafana.organizations.organization_preferences_get()
+        self.assertEqual(result["homeDashboardId"], 0)
+
+    @requests_mock.Mocker()
+    def test_organization_preferences_update(self, m):
+        m.put("http://localhost/api/org/preferences", json={"message": "Preferences updated"})
+        preference = self.grafana.organizations.organization_preferences_update(
+            UserOrganizationPreferences(theme="", homeDashboardId=999, timezone="utc")
+        )
+        self.assertEqual(preference["message"], "Preferences updated")
+
+    @requests_mock.Mocker()
+    def test_organization_preferences_patch(self, m):
+        m.patch("http://localhost/api/org/preferences", json={"message": "Preferences updated"})
+        preference = self.grafana.organizations.organization_preferences_patch(
+            UserOrganizationPreferences(homeDashboardUID="zgjG8dKVz")
+        )
+        self.assertEqual(preference["message"], "Preferences updated")
+
     @requests_mock.Mocker()
     def test_organization_user_update(self, m):
         m.patch("http://localhost/api/orgs/1/users/2", json={"message": "Organization user updated"})