[TOOLSLIBS-564] Adds Tag List endpoints (#201)

* adds deps to mypy pre-commit

* adds tag_lists url

* adds TagList class to inits

* rm unused imports

* adds tag list class

* mv payload render to property

* adds mock stubs

* fixes test init

* adds docs strings, renames args

* rm delete method, rename list method

* adds tests

* docstrings

Author: aschuman0

.pre-commit-config.yaml

@@ -19,3 +19,4 @@ repos:
   rev: v0.931
   hooks:
     - id: mypy
+      additional_dependencies: [types-requests, types-six, types-urllib3, types-mock]

tests/data/tag_list.csv

@@ -0,0 +1,5 @@
+channel_id
+c543f3a3-bc1d-4830-8dee-7532c6a23b9a
+6ba360a0-1f73-4ee7-861e-95f6c1ed6410
+15410d17-687c-46fa-bbd9-f255741a1523
+c2c64ef7-8f5c-470e-915f-f5e3da04e1df

tests/devices/test_tags_lists.py

@@ -0,0 +1,80 @@
+import unittest
+import json
+import mock
+
+import requests
+
+import urbanairship as ua
+from tests import TEST_KEY, TEST_SECRET
+
+
+class TestTagLists(unittest.TestCase):
+    def setUp(self):
+        self.airship = ua.Airship(key=TEST_KEY, secret=TEST_SECRET)
+        self.list_name = "test_tag_list"
+        self.description = "a list of some tags"
+        self.extra = {"key": "value"}
+        self.file_path = "tests/data/tag_list.csv"
+        self.tag_dict = {"group_name": ["tag1", "tag2"]}
+        self.tag_list = ua.TagList(
+            airship=self.airship,
+            list_name=self.list_name,
+            description=self.description,
+            extra=self.extra,
+            add_tags=self.tag_dict,
+            remove_tags=self.tag_dict,
+            set_tags=self.tag_dict,
+        )
+
+    def test_create(self):
+        with mock.patch.object(ua.Airship, "_request") as mock_request:
+            response = requests.Response()
+            response._content = json.dumps({"ok": True}).encode("UTF-8")
+            mock_request.return_value = response
+
+            result = self.tag_list.create()
+
+            self.assertEqual(result.json(), {"ok": True})
+
+    def test_create_payload_property(self):
+        self.assertEqual(
+            self.tag_list._create_payload,
+            {
+                "name": self.list_name,
+                "description": self.description,
+                "extra": self.extra,
+                "add": self.tag_dict,
+                "remove": self.tag_dict,
+                "set": self.tag_dict,
+            },
+        )
+
+    def test_upload(self):
+        with mock.patch.object(ua.Airship, "_request") as mock_request:
+            response = requests.Response()
+            response._content = json.dumps({"ok": True}).encode("UTF-8")
+            mock_request.return_value = response
+
+            result = self.tag_list.upload(file_path=self.file_path)
+
+            self.assertEqual(result.json(), {"ok": True})
+
+    def test_get_errors(self):
+        with mock.patch.object(ua.Airship, "_request") as mock_request:
+            response = requests.Response()
+            response._content = json.dumps({"ok": True}).encode("UTF-8")
+            mock_request.return_value = response
+
+            result = self.tag_list.get_errors()
+
+            self.assertEqual(result.json(), {"ok": True})
+
+    def test_list(self):
+        with mock.patch.object(ua.Airship, "_request") as mock_request:
+            response = requests.Response()
+            response._content = json.dumps({"ok": True}).encode("UTF-8")
+            mock_request.return_value = response
+
+            result = ua.TagList.list(airship=self.airship)
+
+            self.assertEqual(result.json(), {"ok": True})

urbanairship/__init__.py

@@ -34,6 +34,7 @@
     StaticList,
     StaticLists,
     SubscriptionList,
+    TagList,
 )
 from .experiments import ABTest, Experiment, Variant
 from .push import (
@@ -214,6 +215,11 @@
     KeywordInteraction,
     SubscriptionList,
     CustomEvent,
+    SmsCustomResponse,
+    TagList,
+    ABTest,
+    Experiment,
+    Variant,
 ]
 
 

urbanairship/core.py

@@ -59,6 +59,7 @@ def __init__(self, location: Optional[str] = None) -> None:
         self.experiments_validate = self.experiments_url + "validate/"
         self.attachment_url = self.base_url + "attachments/"
         self.custom_events_url = self.base_url + "custom-events/"
+        self.tag_lists_url = self.base_url + "tag-lists/"
 
     def get(self, endpoint: str) -> str:
         url: str = getattr(self, endpoint)

urbanairship/devices/__init__.py

@@ -9,3 +9,4 @@
 from .sms import Sms, KeywordInteraction, SmsCustomResponse
 from .static_lists import StaticList, StaticLists
 from .subscription_lists import SubscriptionList
+from .tag_lists import TagList

urbanairship/devices/static_lists.py

@@ -2,7 +2,7 @@
 import gzip
 import collections
 import datetime
-from typing import Dict, TypeVar, Optional, Type
+from typing import Dict, Optional
 from io import TextIOWrapper
 
 from requests import Response

urbanairship/devices/tag_lists.py

@@ -0,0 +1,123 @@
+import json
+from typing import Dict, Optional, Any, List
+from io import TextIOWrapper
+from unicodedata import name
+
+from requests import Response
+
+from urbanairship import Airship
+from urbanairship.devices.static_lists import GzipCompressReadStream
+
+
+class TagList:
+    """Create, Upload, Delete, and get information for a tag list.
+    Please see the Airship API documentation for more information
+    about CSV formatting, limits, and use of this feature.
+
+    ;param airship: Required. An urbanairship.Airship instance.
+    :param list_name: Required. A name for the list this instance represents.
+    :param description: Optional. A description of the list.
+    :param extra: Optional. A a dictionary of string mappings associated with the list.
+    :param add_tags: Optional. A dictionary consisting of a tag group string and list of tag
+    string to add to uploaded channels.
+    :param remove_tags: Optional. A dictionary consisting of a tag group string and list of
+    tag strings to remove from uploaded channels.
+    :param set_tags: Optional. A dictionary consisting of a tag group string and list of tag
+    strings to set on uploaded channels. Warning: This action is destructive and will
+    remove all existing tags associated with channels.
+    """
+
+    def __init__(
+        self,
+        airship: Airship,
+        list_name: str,
+        description: Optional[str] = None,
+        extra: Optional[Dict[str, str]] = None,
+        add_tags: Optional[Dict[str, List[str]]] = None,
+        remove_tags: Optional[Dict[str, List[str]]] = None,
+        set_tags: Optional[Dict[str, List[str]]] = None,
+    ) -> None:
+        self.airship = airship
+        self.list_name = list_name
+        self.description = description
+        self.extra = extra
+        self.add_tags = add_tags
+        self.remove_tags = remove_tags
+        self.set_tags = set_tags
+
+    @property
+    def _create_payload(self) -> Dict:
+        payload: Dict[str, Any] = {"name": self.list_name}
+
+        if self.description:
+            payload["description"] = self.description
+        if self.extra:
+            payload["extra"] = self.extra
+        if self.add_tags:
+            payload["add"] = self.add_tags
+        if self.remove_tags:
+            payload["remove"] = self.remove_tags
+        if self.set_tags:
+            payload["set"] = self.set_tags
+
+        return payload
+
+    def create(self) -> Response:
+        """Create a new tag list. Channels must be uploaded after creation using
+        the `upload` method.
+
+        :return: Response object
+        """
+        response = self.airship.request(
+            method="POST",
+            url=self.airship.urls.get("tag_lists_url"),
+            body=json.dumps(self._create_payload),
+            content_type="application/json",
+            version=3,
+        )
+
+        return response
+
+    def upload(self, file_path: str) -> Response:
+        """Upload a CSV file of channels. See the Airship API documentation
+        for information about CSV file formatting requirements and limits.
+
+        :param file_path: Path to the CSV file to upload.
+
+        :return: Response object
+        """
+        with open(file_path, "rb") as open_file:
+            response = self.airship.request(
+                method="PUT",
+                body=GzipCompressReadStream(open_file),
+                url=f"{self.airship.urls.get('tag_lists_url')}/{self.list_name}/csv",
+                content_type="text/csv",
+                version=3,
+                encoding="gzip",
+            )
+        return response
+
+    def get_errors(self) -> Response:
+        """Returns a csv of tag list processing errors.
+
+        :return: Response object
+        """
+        response = self.airship.request(
+            method="GET",
+            body={},
+            url=f"{self.airship.urls.get('tag_lists_url')}/{self.list_name}/errors",
+            version=3,
+        )
+        return response
+
+    @classmethod
+    def list(cls, airship: Airship) -> Response:
+        """Returns a json string with details on all tag lists associated with
+        an Airship instance / project.
+
+        :return: Response object
+        """
+        response = airship.request(
+            method="GET", body={}, url=airship.urls.get("tag_lists_url"), version=3
+        )
+        return response