Fix GitHub map user docstrings (#267)

* Fix policies docstring type hinting

* Add policy param type validation for map_user

* Add policy param type validation for map_team

* Remove stray line breaks

hvac/api/auth/github.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """Github methods module."""
+from hvac import exceptions
 from hvac.api.vault_api_base import VaultApiBase
 
 DEFAULT_MOUNT_POINT = 'github'
@@ -78,14 +79,22 @@ def map_team(self, team_name, policies=None, mount_point=DEFAULT_MOUNT_POINT):
         :param team_name: GitHub team name in "slugified" format
         :type team_name: str | unicode
         :param policies: Comma separated list of policies to assign
-        :type policies: list
+        :type policies: List[str]
         :param mount_point: The "path" the method/backend was mounted on.
         :type mount_point: str | unicode
         :return: The response of the map_github_teams request.
         :rtype: requests.Response
         """
+        # First, perform parameter validation.
         if policies is None:
             policies = []
+        if not isinstance(policies, list) or not all([isinstance(p, str) for p in policies]):
+            error_msg = 'unsupported policies argument provided "{arg}" ({arg_type}), required type: List[str]"'
+            raise exceptions.ParamValidationError(error_msg.format(
+                arg=policies,
+                arg_type=type(policies),
+            ))
+        # Then, perform request.
         params = {
             'value': ','.join(policies),
         }
@@ -129,14 +138,23 @@ def map_user(self, user_name, policies=None, mount_point=DEFAULT_MOUNT_POINT):
         :param user_name: GitHub user name
         :type user_name: str | unicode
         :param policies: Comma separated list of policies to assign
-        :type policies: str | unicode
+        :type policies: List[str]
         :param mount_point: The "path" the method/backend was mounted on.
         :type mount_point: str | unicode
         :return: The response of the map_github_users request.
         :rtype: requests.Response
         """
+        # First, perform parameter validation.
         if policies is None:
             policies = []
+        if not isinstance(policies, list) or not all([isinstance(p, str) for p in policies]):
+            error_msg = 'unsupported policies argument provided "{arg}" ({arg_type}), required type: List[str]"'
+            raise exceptions.ParamValidationError(error_msg.format(
+                arg=policies,
+                arg_type=type(policies),
+            ))
+
+        # Then, perform request.
         params = {
             'value': ','.join(policies),
         }

hvac/tests/integration_tests/api/auth/test_github.py

@@ -130,30 +130,43 @@ def test_read_team_mapping(self):
     @parameterized.expand([
         ("no policies", 204, 'hvac', None),
         ("with policy", 204, 'hvac', ['default']),
+        ("with policy incorrect type", 204, 'hvac', 'default, root', exceptions.ParamValidationError, "unsupported policies argument provided"),
         ("with policies", 204, 'hvac', ['default', 'root']),
     ])
-    def test_map_team_and_read_mapping(self, test_label, expected_status_code, team_name, policies):
-        response = self.client.github.map_team(
-            team_name=team_name,
-            policies=policies,
-        )
-        self.assertEqual(
-            first=expected_status_code,
-            second=response.status_code
-        )
+    def test_map_team_and_read_mapping(self, test_label, expected_status_code, team_name, policies, raises=False, exception_msg=''):
 
-        response = self.client.github.read_team_mapping(
-            team_name=team_name,
-        )
-        if policies is None:
-            expected_policies = ''
+        if raises:
+            with self.assertRaises(raises) as cm:
+                self.client.github.map_team(
+                    team_name=team_name,
+                    policies=policies,
+                )
+            self.assertIn(
+                member=exception_msg,
+                container=str(cm.exception),
+            )
         else:
-            expected_policies = ','.join(policies)
+            response = self.client.github.map_team(
+                team_name=team_name,
+                policies=policies,
+            )
+            self.assertEqual(
+                first=expected_status_code,
+                second=response.status_code
+            )
 
-        self.assertDictEqual(
-            d1=dict(key=team_name, value=expected_policies),
-            d2=response['data'],
-        )
+            response = self.client.github.read_team_mapping(
+                team_name=team_name,
+            )
+            if policies is None:
+                expected_policies = ''
+            else:
+                expected_policies = ','.join(policies)
+
+            self.assertDictEqual(
+                d1=dict(key=team_name, value=expected_policies),
+                d2=response['data'],
+            )
 
     @parameterized.expand([
         ("no policies", 204, 'hvac-user', None),
@@ -181,30 +194,43 @@ def test_read_user_mapping(self):
     @parameterized.expand([
         ("no policies", 204, 'hvac', None),
         ("with policy", 204, 'hvac', ['default']),
+        ("with policy incorrect type", 204, 'hvac', 'default, root', exceptions.ParamValidationError, "unsupported policies argument provided"),
         ("with policies", 204, 'hvac', ['default', 'root']),
     ])
-    def test_map_user_and_read_mapping(self, test_label, expected_status_code, user_name, policies):
-        response = self.client.github.map_user(
-            user_name=user_name,
-            policies=policies,
-        )
-        self.assertEqual(
-            first=expected_status_code,
-            second=response.status_code
-        )
+    def test_map_user_and_read_mapping(self, test_label, expected_status_code, user_name, policies, raises=False, exception_msg=''):
 
-        response = self.client.github.read_user_mapping(
-            user_name=user_name,
-        )
-        if policies is None:
-            expected_policies = ''
+        if raises:
+            with self.assertRaises(raises) as cm:
+                self.client.github.map_user(
+                    user_name=user_name,
+                    policies=policies,
+                )
+            self.assertIn(
+                member=exception_msg,
+                container=str(cm.exception),
+            )
         else:
-            expected_policies = ','.join(policies)
+            response = self.client.github.map_user(
+                user_name=user_name,
+                policies=policies,
+            )
+            self.assertEqual(
+                first=expected_status_code,
+                second=response.status_code
+            )
 
-        self.assertDictEqual(
-            d1=dict(key=user_name, value=expected_policies),
-            d2=response['data'],
-        )
+            response = self.client.github.read_user_mapping(
+                user_name=user_name,
+            )
+            if policies is None:
+                expected_policies = ''
+            else:
+                expected_policies = ','.join(policies)
+
+            self.assertDictEqual(
+                d1=dict(key=user_name, value=expected_policies),
+                d2=response['data'],
+            )
 
     @parameterized.expand([
         ("valid token", 'valid-token', None, None),