Added Deprecation for Client.add_raw_header() + replacement implementation

sudorandom · sudorandom · commit 85bf04acd47a · 2013-01-21T14:34:09.000-06:00
diff --git a/README.md b/README.md
@@ -157,61 +157,70 @@ service = client['Account']
 service.getObject()
 ```
 
-**Adding Additional Headers**
+**Setting Object Mask**
 ```python
 # Old
-# These headers are persisted accross API calls
-client.add_header('header', 'value')
+client.set_object_mask({'updates' : None})
 
 # New
-# These headers are NOT persisted accross API calls
-client['Account'].getObject(headers={'header': 'value'})
+client['Account'].getObject(mask={'updates' : None})
 ```
 
-**Removing Additional Headers**
+**Using Init Parameter**
 ```python
 # Old
-client.remove_header('header')
+client.set_init_parameter(1234)
 
 # New
-client['Account'].getObject()
+client['Account'].getObject(id=1234)
 ```
 
-**Changing Authentication Credentials**
+**Setting Result Limit and Offset**
 ```python
 # Old
-client.set_authentication('username', 'api_key')
+client.set_result_limit(10, offset=10)
 
 # New
-client.username = 'username'
-client.api_key = 'api_key'
+client['Account'].getObject(limit=10, offset=10)
 ```
 
-**Using Init Parameter**
+**Adding Additional Headers**
 ```python
 # Old
-client.set_init_parameter(1234)
+# These headers are persisted accross API calls
+client.add_header('header', 'value')
 
 # New
-client['Account'].getObject(id=1234)
+# These headers are NOT persisted accross API calls
+client['Account'].getObject(headers={'header': 'value'})
 ```
 
-**Setting Object Mask**
+**Removing Additional Headers**
 ```python
 # Old
-client.set_object_mask({'updates' : None})
+client.remove_header('header')
 
 # New
-client['Account'].getObject(mask={'updates' : None})
+client['Account'].getObject()
 ```
 
-**Setting Result Limit and Offset**
+**Adding Additional HTTP Headers**
 ```python
 # Old
-client.set_result_limit(10, offset=10)
+client.add_raw_header('header', 'value')
 
 # New
-client['Account'].getObject(limit=10, offset=10)
+client['Account'].getObject(raw_headers={'header': 'value'})
+```
+
+**Changing Authentication Credentials**
+```python
+# Old
+client.set_authentication('username', 'api_key')
+
+# New
+client.username = 'username'
+client.api_key = 'api_key'
 ```
 
 
diff --git a/SoftLayer/API.py b/SoftLayer/API.py
@@ -48,8 +48,6 @@ class SoftLayerError(Exception):
 
 class Client(object):
     """A SoftLayer API client
-    Clients are intended to be declared once per service and used for all calls
-    made to that service.
 
     :param service_name: The name of the SoftLayer API service to query.
     :param id: An optional object if if you're instantiating a particular
@@ -107,10 +105,14 @@ def __init__(self, service_name=None, id=None, username=None, api_key=None,
         self.timeout = timeout
 
     def add_raw_header(self, name, value):
+        """ Set HTTP headers for API calls
+        ..  deprecated:: 2.0.0
+        """
         self.transport.set_raw_header(name, value)
 
     def add_header(self, name, value):
-        """ Set a SoftLayer API call header; deprecated
+        """ Set a SoftLayer API call header
+        ..  deprecated:: 2.0.0
 
         :param name: The name of the header to add
         :param value: The header to add.
@@ -123,7 +125,8 @@ def add_header(self, name, value):
         self._headers[name] = value
 
     def remove_header(self, name):
-        """ Remove a SoftLayer API call header; deprecated
+        """ Remove a SoftLayer API call header
+        ..  deprecated:: 2.0.0
 
         :param name: The name of the header to remove.
         """
@@ -133,6 +136,7 @@ def remove_header(self, name):
 
     def set_authentication(self, username, api_key):
         """ Set user and key to authenticate a SoftLayer API call
+        ..  deprecated:: 2.0.0
 
         Use this method if you wish to bypass the API_USER and API_KEY class
         constants and set custom authentication per API call.
@@ -150,7 +154,8 @@ def set_authentication(self, username, api_key):
         })
 
     def set_init_parameter(self, id):
-        """ Set an initialization parameter header; deprecated
+        """ Set an initialization parameter header
+        ..  deprecated:: 2.0.0
 
         Initialization parameters instantiate a SoftLayer API service object to
         act upon during your API method call. For instance, if your account has
@@ -169,7 +174,8 @@ def set_init_parameter(self, id):
         })
 
     def set_object_mask(self, mask):
-        """ Set an object mask to a SoftLayer API call; deprecated
+        """ Set an object mask to a SoftLayer API call
+        ..  deprecated:: 2.0.0
 
         Use an object mask to retrieve data related your API call's result.
         Object masks are skeleton objects, or strings that define nested
@@ -189,7 +195,8 @@ def set_object_mask(self, mask):
         self.add_header(header, {'mask': mask})
 
     def set_result_limit(self, limit, offset=0):
-        """ Set a result limit on a SoftLayer API call; deprecated
+        """ Set a result limit on a SoftLayer API call
+        ..  deprecated:: 2.0.0
 
         Many SoftLayer API methods return a group of results. These methods
         support a way to limit the number of results retrieved from the
@@ -229,6 +236,7 @@ def __call__(self, service, method, *args, **kwargs):
         objectmask = kwargs.get('mask')
         objectfilter = kwargs.get('filter')
         headers = kwargs.get('headers')
+        raw_headers = kwargs.get('raw_headers')
         limit = kwargs.get('limit')
         offset = kwargs.get('offset', 0)
 
@@ -239,6 +247,10 @@ def __call__(self, service, method, *args, **kwargs):
                     'apiKey': self.api_key,
                 }}
 
+        if raw_headers:
+            for name, value in raw_headers.items():
+                self.transport.set_raw_header(name, value)
+
         if objectid is not None:
             headers[service + 'InitParameters'] = {'id': int(objectid)}
 
@@ -272,6 +284,7 @@ def __call__(self, service, method, *args, **kwargs):
 
     def __getattribute__(self, name):
         """ Attempt a SoftLayer API call
+        ..  deprecated:: 2.0.0
 
         Use this as a catch-all so users can call SoftLayer API methods
         directly against their client object. If the property or method
diff --git a/SoftLayer/tests/basic_tests.py b/SoftLayer/tests/basic_tests.py
@@ -77,7 +77,9 @@ def test_non_secure_endpoint(self):
         self.assertIsInstance(client.transport, 
             SoftLayer.API.ProxyTransport)
 
-    def test_set_raw_header(self):
+
+class ClientMethods(unittest.TestCase):
+    def test_set_raw_header_old(self):
         client = SoftLayer.Client(
                 username='doesnotexist',
                 api_key='issurelywrong'
@@ -191,11 +193,15 @@ def test_complex(self, m):
         client = SoftLayer.Client(username='doesnotexist',
             api_key='issurelywrong')
 
+        client.transport = MagicMock()
+
         return_value = client['SERVICE'].METHOD(1234,
             id=5678,
             mask={'object': {'attribute': ''}},
+            raw_headers={'RAW': 'HEADER'},
             filter={'TYPE': {'obj': {'attribute': '^= prefix'}}},
             limit=9, offset=10)
+
         m.return_value.METHOD.assert_called_with({
             'headers': {
                 'SoftLayer_SERVICEObjectMask': {
@@ -209,6 +215,7 @@ def test_complex(self, m):
                 'resultLimit': {'limit': 9, 'offset': 10}}}, 1234)
 
         self.assertEquals(m.return_value.METHOD(), return_value)
+        client.transport.set_raw_header.assert_called_with("RAW", "HEADER")
 
 
 class UnauthedUser(unittest.TestCase):
