Merge pull request #34 from IBM/major-release

release v1.0.0

Author: ehdsouza

.travis.yml

@@ -1,8 +1,6 @@
 language: python
 matrix:
   include:
-    - python: 2.7
-    - python: 3.4
     - python: 3.5
     - python: 3.6
     - python: 3.7

README.md

@@ -25,23 +25,87 @@ easy_install --upgrade ibm-cloud-sdk-core
 ```
 
 ## Authentication Types
-There are several flavors of authentication supported in this package. To specify the intended authentication pattern to use, the user can pass in the parameter `authentication_type`. This parameter is optional, but it may become required in a future major release. The options for this parameter are `basic`, `iam`, and `icp4d`.
+There are several flavors of authentication supported in this package. To specify the intended authentication pattern to use, simply instantiate the `Authenticator` of your choice.
 
-### basic
+### Basic
 This indicates Basic Auth is to be used. Users will pass in a `username` and `password` and the SDK will generate a Basic Auth header to send with requests to the service.
 
-### iam
-This indicates that IAM token authentication is to be used. Users can pass in an `iam_apikey` or an `iam_access_token`. If an API key is used, the SDK will manage the token for the user. In either case, the SDK will generate a Bearer Auth header to send with requests to the service.
+```py
+from ibm_cloud_sdk_core.authenticators import BasicAuthenticator
 
-### icp4d
-This indicates that the service is an instance of ICP4D, which has its own version of token authentication. Users can pass in a `username` and `password`, or an `icp4d_access_token`. If a username and password is given, the SDK will manage the token for the user.
-A `icp4d_url` is **required** for this type. In order to use an SDK-managed token with ICP4D authentication, this option **must** be passed in.
+authenticator = BasicAuthenticator(<your_username>, <your_password>)
+```
+
+### IAM
+This indicates that IAM token authentication is to be used. Users can pass in a `apikey` and the SDK will generate a Bearer Auth header to send with requests to the service.
+
+```py
+from ibm_cloud_sdk_core.authenticators import IAMAuthenticator
+
+authenticator = IAMAuthenticator(<your_apikey>)
+```
+
+### Cloud Pak for Data
+This indicates that the service is an instance of CP4D, which has its own version of token authentication. Users can pass in a `username`, `password` and `url`, and the SDK will generate a Bearer Auth header to send with requests to the service.
+
+```py
+from ibm_cloud_sdk_core.authenticators import CloudPakForDataAuthenticator
+
+authenticator = CloudPakForDataAuthenticator(<your_username>, <your_password>, <your_url>)
+```
+
+### Bearer Token
+This indicates bearer token authentication is to be used. The system would prepend the `bearer` name to your token and add it to the authorization header.
+
+```py
+from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
+
+authenticator = BearerTokenAuthenticator(<your_bearer_token>)
+```
+
+### No Authentication
+This indicates that no authentication is needed when sending requests to the service
+
+```py
+from ibm_cloud_sdk_core.authenticators import NoAuthAuthenticator
+
+authenticator = NoAuthAuthenticator()
+```
 
 ## Issues
 
 If you encounter an issue with this project, you are welcome to submit a [bug report](https://github.com/IBM/python-sdk-core/issues).
 Before opening a new issue, please search for similar issues. It's possible that someone has already reported it.
 
+## Logging
+
+### Enable logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+This would show output of the form:
+```
+DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): iam.cloud.ibm.com:443
+DEBUG:urllib3.connectionpool:https://iam.cloud.ibm.com:443 "POST /identity/token HTTP/1.1" 200 1809
+DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): gateway.watsonplatform.net:443
+DEBUG:urllib3.connectionpool:https://gateway.watsonplatform.net:443 "POST /assistant/api/v1/workspaces?version=2018-07-10 HTTP/1.1" 201 None
+DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): gateway.watsonplatform.net:443
+DEBUG:urllib3.connectionpool:https://gateway.watsonplatform.net:443 "GET /assistant/api/v1/workspaces/883a2a44-eb5f-4b1a-96b0-32a90b475ea8?version=2018-07-10&export=true HTTP/1.1" 200 None
+DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): gateway.watsonplatform.net:443
+DEBUG:urllib3.connectionpool:https://gateway.watsonplatform.net:443 "DELETE /assistant/api/v1/workspaces/883a2a44-eb5f-4b1a-96b0-32a90b475ea8?version=2018-07-10 HTTP/1.1" 200 28
+```
+
+### Low level request and response dump
+To get low level information of the requests/ responses:
+
+```python
+from http.client import HTTPConnection
+HTTPConnection.debuglevel = 1
+```
+
 ## Open source @ IBM
 
 Find more open source projects on the [IBM Github Page](http://github.com/IBM)

ibm_cloud_sdk_core/__init__.py

@@ -17,6 +17,6 @@
 from .detailed_response import DetailedResponse
 from .iam_token_manager import IAMTokenManager
 from .jwt_token_manager import JWTTokenManager
-from .icp4d_token_manager import ICP4DTokenManager
+from .cp4d_token_manager import CP4DTokenManager
 from .api_exception import ApiException
-from .utils import datetime_to_string, string_to_datetime
+from .utils import datetime_to_string, string_to_datetime, get_authenticator_from_environment, read_external_sources

ibm_cloud_sdk_core/authenticators/__init__.py

@@ -0,0 +1,22 @@
+# coding: utf-8
+
+# Copyright 2019 IBM All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .authenticator import Authenticator
+from .basic_authenticator import BasicAuthenticator
+from .bearer_token_authenticator import BearerTokenAuthenticator
+from .cp4d_authenticator import CloudPakForDataAuthenticator
+from .iam_authenticator import IAMAuthenticator
+from .no_auth_authenticator import NoAuthAuthenticator

ibm_cloud_sdk_core/authenticators/authenticator.py

@@ -0,0 +1,32 @@
+# coding: utf-8
+
+# Copyright 2019 IBM All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from abc import ABC, abstractmethod
+
+class Authenticator(ABC):
+    @abstractmethod
+    def authenticate(self, req):
+        """
+        Adds the Authorization header, if applicable
+        """
+        pass
+
+    @abstractmethod
+    def validate(self):
+        """
+        Checks if all the inputs needed are present
+        """
+        pass

ibm_cloud_sdk_core/authenticators/basic_authenticator.py

@@ -0,0 +1,55 @@
+# coding: utf-8
+
+# Copyright 2019 IBM All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .authenticator import Authenticator
+from ..utils import has_bad_first_or_last_char
+import base64
+
+
+class BasicAuthenticator(Authenticator):
+    authentication_type = 'basic'
+
+    def __init__(self, username, password):
+        """
+        :attr str username: The username
+        :attr str password: The password
+        """
+        self.username = username
+        self.password = password
+        self.validate()
+
+    def validate(self):
+        """
+        Performs validation on input params
+        """
+        if self.username is None or self.password is None:
+            raise ValueError('The username and password shouldn\'t be None.')
+
+        if has_bad_first_or_last_char(
+                self.username) or has_bad_first_or_last_char(self.password):
+            raise ValueError(
+                'The username and password shouldn\'t start or end with curly brackets or quotes. '
+                'Please remove any surrounding {, }, or \" characters.')
+
+    def authenticate(self, req):
+        """
+        Adds the Authorization header, if applicable
+        """
+        authstring = "{0}:{1}".format(self.username, self.password)
+        base64_authorization = base64.b64encode(authstring.encode('utf-8')).decode('utf-8')
+
+        headers = req.get('headers')
+        headers['Authorization'] = 'Basic {0}'.format(base64_authorization)

ibm_cloud_sdk_core/authenticators/bearer_token_authenticator.py

@@ -0,0 +1,48 @@
+# coding: utf-8
+
+# Copyright 2019 IBM All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .authenticator import Authenticator
+
+
+class BearerTokenAuthenticator(Authenticator):
+    authentication_type = 'bearerToken'
+
+    def __init__(self, bearer_token):
+        """
+        :attr str bearer_token: User managed bearer token
+        """
+        self.bearer_token = bearer_token
+        self.validate()
+
+    def validate(self):
+        """
+        Performs validation on input params
+        """
+        if self.bearer_token is None:
+            raise ValueError('The bearer token shouldn\'t be None.')
+
+    def authenticate(self, req):
+        """
+        Adds the Authorization header, if applicable
+        """
+        headers = req.get('headers')
+        headers['Authorization'] = 'Bearer {0}'.format(self.bearer_token)
+
+    def set_bearer_token(self, bearer_token):
+        """
+        Sets the bearer token
+        """
+        self.bearer_token = bearer_token

ibm_cloud_sdk_core/authenticators/cp4d_authenticator.py

@@ -0,0 +1,89 @@
+# coding: utf-8
+
+# Copyright 2019 IBM All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .authenticator import Authenticator
+from ..cp4d_token_manager import CP4DTokenManager
+from ..utils import has_bad_first_or_last_char
+
+
+class CloudPakForDataAuthenticator(Authenticator):
+    authentication_type = 'cp4d'
+
+    def __init__(self,
+                 username,
+                 password,
+                 url,
+                 disable_ssl_verification=False,
+                 headers=None,
+                 proxies=None):
+        """
+        :attr str username: The username
+        :attr str password: The password
+        :attr str url: The url for authentication
+        :attr bool disable_ssl_verification: enables/ disabled ssl verification
+        :attr dict headers: user-defined headers
+        :attr dict proxies: user-defined proxies
+        """
+        self.token_manager = CP4DTokenManager(
+            username, password, url, disable_ssl_verification, headers, proxies)
+        self.validate()
+
+    def validate(self):
+        """
+        Performs validation on input params
+        """
+        if self.token_manager.username is None or self.token_manager.password is None:
+            raise ValueError('The username and password shouldn\'t be None.')
+
+        if self.token_manager.url is None:
+            raise ValueError('The url shouldn\'t be None.')
+
+        if has_bad_first_or_last_char(
+                self.token_manager.username) or has_bad_first_or_last_char(self.token_manager.password):
+            raise ValueError(
+                'The username and password shouldn\'t start or end with curly brackets or quotes. '
+                'Please remove any surrounding {, }, or \" characters.')
+
+        if has_bad_first_or_last_char(self.token_manager.url):
+            raise ValueError(
+                'The url shouldn\'t start or end with curly brackets or quotes. '
+                'Please remove any surrounding {, }, or \" characters.')
+
+    def authenticate(self, req):
+        """
+        Adds the Authorization header, if applicable
+        """
+        headers = req.get('headers')
+        bearer_token = self.token_manager.get_token()
+        headers['Authorization'] = 'Bearer {0}'.format(bearer_token)
+
+    def set_disable_ssl_verification(self, status=False):
+        """
+        Sets the ssl verification to enabled or disabled
+        """
+        self.token_manager.set_disable_ssl_verification(status)
+
+    def set_headers(self, headers):
+        """
+        Sets user-defined headers
+        """
+        self.token_manager.set_headers(headers)
+
+    def set_proxies(self, proxies):
+        """
+        Sets the proxies
+        """
+        self.token_manager.set_proxies(proxies)