refactor DynamicField

pyotrs/lib.py

@@ -190,27 +190,33 @@ class Attachment(object):
 class DynamicField(object):
     """PyOTRS DynamicField class
 
+    Args:
+        name (unicode): Name of OTRS DynamicField
+        value (unicode): Value of OTRS DynamicField
+
     .. warning::
         DynamicField representation changed between OTRS 4 and OTRS 5.
         **PyOTRS only supports OTRS 5 style!**
     """
-    def __init__(self, name=None, value=None, dct=None):
-        if dct:
-            if name or value:
-                raise Exception("Please provide either \"dct\" or \"name and value\"")
-            self.name = dct["Name"]
-            self.value = dct["Value"]
-
-        else:
-            if name and value:
-                self.name = name
-                self.value = value
-            else:
-                raise Exception("Please provide either \"dct\" or \"name and value\"")
+    def __init__(self, name, value):
+        self.name = name
+        self.value = value
 
     def __repr__(self):
         return "<{0}: {1} --> {2} >".format(self.__class__.__name__, self.name, self.value)
 
+    @classmethod
+    def from_dct(cls, dct):
+        """create DynamicField from dct
+
+        Args:
+            dct (dict):
+
+        Returns:
+            DynamicField
+        """
+        return cls(name=dct["Name"], value=dct["Value"])
+
     def to_dct(self):
         """represent DynamicField as dict
 
@@ -234,7 +240,7 @@ class DynamicField(object):
         Returns:
             DynamicField
         """
-        return DynamicField(dct={'Name': 'lastname', 'Value': 'Doe'})
+        return DynamicField.from_dct({'Name': 'lastname', 'Value': 'Doe'})
 
 
 class Ticket(object):
@@ -595,10 +601,10 @@ class Client(object):
             SessionError if neither self.session_id nor session_id is not set
 
         Returns:
-            bool: True if valid, False otherwise.
+            bool: **True** if valid, otherwise **False**
 
         .. note::
-            Calls _ticket_get_json (GET)
+            **Calls _ticket_get_json (GET)**
         """
         if not session_id and not self.session_id_store.value:
             raise SessionError("No value set for session_id!")
@@ -618,7 +624,7 @@ class Client(object):
         """create new OTRS Session and store Session ID
 
         Returns:
-            bool: True if successful, False otherwise.
+            bool: **True** if successful, otherwise **False**
 
         .. note::
             Uses HTTP Method: POST
@@ -649,7 +655,7 @@ class Client(object):
             SessionIDFileError
 
         Returns:
-            bool: True if successful, False otherwise.
+            bool: **True** if successful, otherwise **False**
         """
         # try to read session_id from file
         self.session_id_store.value = self.session_id_store.read()
@@ -698,8 +704,8 @@ class Client(object):
             dynamic_field_list (list): *DynamicField* object
             **kwargs: any regular OTRS Fields (not for Dynamic Fields!)
 
-        .. todo::
-            2016-04-18 (RH): decide what ticket_create should return (bool or result content)
+        Returns:
+            bool: **True** if successful, otherwise **False**
         """
         url = ("{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/"
                "{0.webservicename}/Ticket".format(self))
@@ -740,7 +746,7 @@ class Client(object):
             ResponseJSONParseError
 
         Returns:
-            bool: True if successful, False otherwise.
+            bool: **True** if successful, otherwise **False**
         """
         self.operation = "TicketCreate"
         http_method = "POST"
@@ -755,6 +761,7 @@ class Client(object):
     GenericInterface::Operation::Ticket::TicketGet
         Methods (public):
         * ticket_get_by_id
+        * ticket_get_by_list
         * ticket_get_by_number
     """
 
@@ -769,22 +776,46 @@ class Client(object):
                 Articles (+default: False*)
 
         Returns:
-            dict: Ticket
+            bool: **True** if successful, otherwise **False**
 
-        .. todo::
-            2016-04-18 (RH): decide what ticket_get_by_id should return (bool or result content)
         """
         url = ("{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/"
-               "{0.webservicename}/Ticket/{1}".format(self, ticket_id))
+               "{0.webservicename}/Ticket".format(self))
+
+        payload = {
+            "SessionID": self.session_id_store.value,
+            "TicketID": "{}".format(ticket_id),
+            "AllArticles": int(all_articles),
+            "DynamicFields": int(dynamic_fields)
+        }
+
+        return self._ticket_get_json(url, payload)
+
+    def ticket_get_by_list_of_ids(self, ticket_id_list, dynamic_fields=True, all_articles=False):
+        """ticket_get_by_list
+
+        Args:
+            ticket_id_list (list): List of Integer value
+            dynamic_fields (bool): will request OTRS to include all
+                Dynamic Fields (*default: True*)
+            all_articles (bool): will request OTRS to include all
+                Articles (*default: False*)
+
+        Returns:
+            bool: **True** if successful, otherwise **False**
+
+        """
+        url = ("{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/"
+               "{0.webservicename}/Ticket".format(self))
 
         payload = {
             "SessionID": self.session_id_store.value,
+            "TicketID": ','.join([str(item) for item in ticket_id_list]),
             "AllArticles": int(all_articles),
             "DynamicFields": int(dynamic_fields)
         }
 
         return self._ticket_get_json(url, payload)
-        # return self.response_json['Ticket'][0]
 
     def ticket_get_by_number(self, ticket_number, dynamic_fields=True, all_articles=False):
         """ticket_get_by_number
@@ -797,7 +828,7 @@ class Client(object):
                     Articles (*default: False*)
 
         Returns:
-            dict: Ticket
+            bool: **True** if successful, otherwise **False**
         """
         if isinstance(ticket_number, int):
             raise TicketError("Provide ticket_number as str/unicode. Got ticket_number as int.")
@@ -827,7 +858,7 @@ class Client(object):
             ResponseJSONParseError
 
         Returns:
-            bool: True if successful, False otherwise.
+            bool: **True** if successful, otherwise **False**
 
         .. note::
             Uses HTTP Method: GET
@@ -855,11 +886,14 @@ class Client(object):
             **kwargs: Arbitrary keyword arguments (Dynamic Field).
 
         Returns:
-            list: tickets that were found as list of **str**
+            bool: **True** if successful, otherwise **False**
 
         .. note::
             If value of kwargs is a datetime object then this object will be
             converted to the appropriate string format for REST API.
+
+        .. note::
+            tickets that were found as list of **str** stored self.ticket_search_result_list
         """
         url = ("{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/"
                "{0.webservicename}/Ticket".format(self))
@@ -878,7 +912,6 @@ class Client(object):
             raise TicketSearchNothingToLookFor("Nothing specified to look for!")
 
         return self._ticket_search_json(url, payload)
-        # return self.ticket_search_result_list
 
     def ticket_search_full_text(self, pattern):
         """Wrapper for search ticket for full text search
@@ -893,12 +926,6 @@ class Client(object):
             Following examples is a dummy doctest. In order for this to work on Python2 the
              whole docstring needs to be a (Python2) unicode string (prefixed u)
 
-        Examples:
-            >>> 2 + 2
-            4
-            >>> str('a') + str('b')
-            'ab'
-
         .. warning::
             Full Text is not really working yet.
 
@@ -926,7 +953,7 @@ class Client(object):
             ResponseJSONParseError
 
         Returns:
-            bool: True if search successful, False otherwise.
+            bool: **True** if successful, otherwise **False**
 
         .. note::
             Uses HTTP Method: GET
@@ -963,10 +990,7 @@ class Client(object):
             **kwargs: any regular OTRS Fields (not for Dynamic Fields!)
 
         Returns:
-            dict: Response from OTRS API if successful (if Article was added new Art. ID included)
-
-        .. todo::
-            2016-04-17 (RH): decide what ticket_update should return (bool or result content)
+            bool: **True** if successful, otherwise **False**
         """
         url = ("{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/"
                "{0.webservicename}/Ticket/{1}".format(self, ticket_id))
@@ -988,7 +1012,6 @@ class Client(object):
             payload.update({"DynamicField": [df.to_dct() for df in dynamic_field_list]})
 
         return self._ticket_update_json(url, payload)
-        # return self.response_json
 
     def ticket_update_set_pending(self,
                                   ticket_id,
@@ -1004,10 +1027,7 @@ class Client(object):
             pending_hours (int): defaults to 0
 
         Returns:
-            bool: True if update successful, False otherwise.
-
-        .. todo::
-            2016-04-17 (RH): decide what ticket_update_set_pending should return
+            bool: **True** if successful, otherwise **False**
         """
         url = ("{0.baseurl}/otrs/nph-genericinterface.pl/Webservice/"
                "{0.webservicename}/Ticket/{1}".format(self, ticket_id))
@@ -1024,7 +1044,6 @@ class Client(object):
         }
 
         return self._ticket_update_json(url, payload)
-        # return "Set pending till {0} with state \"{1}\"".format(pending_till_str, new_state)
 
     def _ticket_update_json(self, url, payload):
         """_ticket_update_json
@@ -1037,7 +1056,7 @@ class Client(object):
             OTRSAPIError
 
         Returns:
-            bool: True if update successful, False otherwise.
+            bool: **True** if successful, otherwise **False**
 
         .. note::
             Uses HTTP Method: PATCH
@@ -1119,7 +1138,7 @@ class Client(object):
             OTRSAPIError
 
         Returns:
-            bool True
+            bool: **True** if successful
 
         """
 

tests/test_dynamic_field.py

@@ -22,16 +22,17 @@ from pyotrs import DynamicField  # noqa
 
 class DynamicFieldTests(unittest.TestCase):
     def test_init_blank(self):
-        self.assertRaisesRegex(Exception, "Please provide either.*", DynamicField)
+        self.assertRaisesRegex(TypeError, ".*takes exactly 3 arguments.*", DynamicField)
 
     def test_init_name_only(self):
-        self.assertRaisesRegex(Exception, "Please provide either.*", DynamicField, name="foo")
+        self.assertRaisesRegex(TypeError,
+                               ".*takes exactly 3 arguments.*",
+                               DynamicField, name="foo")
 
     def test_init_value_only(self):
-        self.assertRaisesRegex(Exception, "Please provide either.*", DynamicField, value="bar")
-
-    def test_init_dict_and_name(self):
-        self.assertRaisesRegex(Exception, "Please prov.*", DynamicField, dct={'f': 'b'}, value="c")
+        self.assertRaisesRegex(TypeError,
+                               ".*takes exactly 3 arguments.*",
+                               DynamicField, value="bar")
 
     def test_dummy1_static(self):
         dyn1 = DynamicField(name="firstname", value="Jane")
@@ -39,12 +40,12 @@ class DynamicFieldTests(unittest.TestCase):
         self.assertEqual(dyn1.__repr__(), '<DynamicField: firstname --> Jane >')
 
     def test_dummy2_static(self):
-        dyn2 = DynamicField(dct={'Name': 'lastname', 'Value': 'Doe'})
+        dyn2 = DynamicField.from_dct({'Name': 'lastname', 'Value': 'Doe'})
         self.assertIsInstance(dyn2, DynamicField)
         self.assertEqual(dyn2.__repr__(), '<DynamicField: lastname --> Doe >')
 
     def test_dummy1_static_to_dict(self):
-        dyn1 = DynamicField(name="firstname", value="Jane")
+        dyn1 = DynamicField("firstname", "Jane")
         self.assertIsInstance(dyn1, DynamicField)
         self.assertDictEqual(dyn1.to_dct(), {'Name': 'firstname', 'Value': 'Jane'})