ibm-cloud-sdk-core 3.16.0__py3-none-any.whl → 3.21.0__py3-none-any.whl

ibm_cloud_sdk_core/__init__.py

@@ -43,6 +43,7 @@ from .token_managers.jwt_token_manager import JWTTokenManager
 from .token_managers.cp4d_token_manager import CP4DTokenManager
 from .token_managers.container_token_manager import ContainerTokenManager
 from .token_managers.vpc_instance_token_manager import VPCInstanceTokenManager
+from .token_managers.mcsp_token_manager import MCSPTokenManager
 from .api_exception import ApiException
 from .utils import datetime_to_string, string_to_datetime, read_external_sources
 from .utils import datetime_to_string_list, string_to_datetime_list

ibm_cloud_sdk_core/api_exception.py

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import warnings
 from http import HTTPStatus
 from typing import Optional
 
@@ -39,24 +40,37 @@ class ApiException(Exception):
         # Call the base class constructor with the parameters it needs
         super().__init__(message)
         self.message = message
-        self.code = code
+        self.status_code = code
         self.http_response = http_response
         self.global_transaction_id = None
         if http_response is not None:
             self.global_transaction_id = http_response.headers.get('X-Global-Transaction-ID')
             self.message = self.message if self.message else self._get_error_message(http_response)
 
+    # pylint: disable=fixme
+    # TODO: delete this by the end of 2024.
+    @property
+    def code(self):
+        """The old `code` property with a deprecation warning."""
+
+        warnings.warn(
+            'Using the `code` attribute on the `ApiException` is deprecated and '
+            'will be removed in the future. Use `status_code` instead.',
+            DeprecationWarning,
+        )
+        return self.status_code
+
     def __str__(self) -> str:
-        msg = 'Error: ' + str(self.message) + ', Code: ' + str(self.code)
+        msg = 'Error: ' + str(self.message) + ', Status code: ' + str(self.status_code)
         if self.global_transaction_id is not None:
             msg += ' , X-global-transaction-id: ' + str(self.global_transaction_id)
-        return  msg
+        return msg
 
     @staticmethod
     def _get_error_message(response: Response) -> str:
         error_message = 'Unknown error'
         try:
-            error_json = response.json()
+            error_json = response.json(strict=False)
             if 'errors' in error_json:
                 if isinstance(error_json['errors'], list):
                     err = error_json['errors'][0]

ibm_cloud_sdk_core/authenticators/__init__.py

@@ -41,3 +41,4 @@ from .cp4d_authenticator import CloudPakForDataAuthenticator
 from .iam_authenticator import IAMAuthenticator
 from .vpc_instance_authenticator import VPCInstanceAuthenticator
 from .no_auth_authenticator import NoAuthAuthenticator
+from .mcsp_authenticator import MCSPAuthenticator

ibm_cloud_sdk_core/authenticators/authenticator.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2023 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.
@@ -28,6 +28,7 @@ class Authenticator(ABC):
     AUTHTYPE_CP4D = 'cp4d'
     AUTHTYPE_VPC = 'vpc'
     AUTHTYPE_NOAUTH = 'noAuth'
+    AUTHTYPE_MCSP = 'mcsp'
     AUTHTYPE_UNKNOWN = 'unknown'
 
     @abstractmethod

ibm_cloud_sdk_core/authenticators/basic_authenticator.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -15,11 +15,15 @@
 # limitations under the License.
 
 import base64
+
 from requests import Request
 
+from ibm_cloud_sdk_core.logger import get_logger
 from .authenticator import Authenticator
 from ..utils import has_bad_first_or_last_char
 
+logger = get_logger()
+
 
 class BasicAuthenticator(Authenticator):
     """The BasicAuthenticator is used to add basic authentication information to requests.
@@ -41,6 +45,7 @@ class BasicAuthenticator(Authenticator):
         self.password = password
         self.validate()
         self.authorization_header = self.__construct_basic_auth_header()
+        logger.debug('Created new BasicAuthenticator instance!')
 
     def authentication_type(self) -> str:
         """Returns this authenticator's type ('basic')."""
@@ -57,16 +62,15 @@ class BasicAuthenticator(Authenticator):
         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):
+        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.')
+                'Please remove any surrounding {, }, or \" characters.'
+            )
 
     def __construct_basic_auth_header(self) -> str:
         authstring = "{0}:{1}".format(self.username, self.password)
-        base64_authorization = base64.b64encode(
-            authstring.encode('utf-8')).decode('utf-8')
+        base64_authorization = base64.b64encode(authstring.encode('utf-8')).decode('utf-8')
         return 'Basic {0}'.format(base64_authorization)
 
     def authenticate(self, req: Request) -> None:
@@ -77,8 +81,9 @@ class BasicAuthenticator(Authenticator):
             Authorization: Basic <encoded username and password>
 
         Args:
-            req: The request to add basic auth information too. Must contain a key to a dictionary
+            req: The request to add basic auth information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')
         headers['Authorization'] = self.authorization_header
+        logger.debug('Authenticated outbound request (type=%s)', self.authentication_type())

ibm_cloud_sdk_core/authenticators/bearer_token_authenticator.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -16,8 +16,11 @@
 
 from requests import Request
 
+from ibm_cloud_sdk_core.logger import get_logger
 from .authenticator import Authenticator
 
+logger = get_logger()
+
 
 class BearerTokenAuthenticator(Authenticator):
     """The BearerTokenAuthenticator will add a user-supplied bearer token
@@ -37,6 +40,7 @@ class BearerTokenAuthenticator(Authenticator):
     def __init__(self, bearer_token: str) -> None:
         self.bearer_token = bearer_token
         self.validate()
+        logger.debug('Created BearerTokenAuthenticator instance!')
 
     def authentication_type(self) -> str:
         """Returns this authenticator's type ('bearertoken')."""
@@ -61,11 +65,12 @@ class BearerTokenAuthenticator(Authenticator):
             Authorization: Bearer <bearer-token>
 
         Args:
-            req: The request to add bearer authentication information too. Must contain a key to a dictionary
+            req: The request to add bearer authentication information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')
         headers['Authorization'] = 'Bearer {0}'.format(self.bearer_token)
+        logger.debug('Authenticated outbound request (type=%s)', self.authentication_type())
 
     def set_bearer_token(self, bearer_token: str) -> None:
         """Set a new bearer token to be sent in subsequent service operations.

ibm_cloud_sdk_core/authenticators/container_authenticator.py

@@ -64,25 +64,35 @@ class ContainerAuthenticator(IAMRequestBasedAuthenticator):
             or client_id, and/or client_secret are not valid for IAM token requests.
     """
 
-    def __init__(self,
-                 cr_token_filename: Optional[str] = None,
-                 iam_profile_name: Optional[str] = None,
-                 iam_profile_id: Optional[str] = None,
-                 url: Optional[str] = None,
-                 client_id: Optional[str] = None,
-                 client_secret: Optional[str] = None,
-                 disable_ssl_verification: bool = False,
-                 scope: Optional[str] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 headers: Optional[Dict[str, str]] = None) -> None:
+    def __init__(
+        self,
+        cr_token_filename: Optional[str] = None,
+        iam_profile_name: Optional[str] = None,
+        iam_profile_id: Optional[str] = None,
+        url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        disable_ssl_verification: bool = False,
+        scope: Optional[str] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
         # Check the type of `disable_ssl_verification`. Must be a bool.
         if not isinstance(disable_ssl_verification, bool):
             raise TypeError('disable_ssl_verification must be a bool')
 
         self.token_manager = ContainerTokenManager(
-            cr_token_filename=cr_token_filename, iam_profile_name=iam_profile_name, iam_profile_id=iam_profile_id,
-            url=url, client_id=client_id, client_secret=client_secret,
-            disable_ssl_verification=disable_ssl_verification, scope=scope, proxies=proxies, headers=headers)
+            cr_token_filename=cr_token_filename,
+            iam_profile_name=iam_profile_name,
+            iam_profile_id=iam_profile_id,
+            url=url,
+            client_id=client_id,
+            client_secret=client_secret,
+            disable_ssl_verification=disable_ssl_verification,
+            scope=scope,
+            proxies=proxies,
+            headers=headers,
+        )
 
         self.validate()
 
@@ -103,8 +113,7 @@ class ContainerAuthenticator(IAMRequestBasedAuthenticator):
         super().validate()
 
         if not self.token_manager.iam_profile_name and not self.token_manager.iam_profile_id:
-            raise ValueError(
-                'At least one of iam_profile_name or iam_profile_id must be specified.')
+            raise ValueError('At least one of iam_profile_name or iam_profile_id must be specified.')
 
     def set_cr_token_filename(self, cr_token_filename: str) -> None:
         """Set the location of the compute resource token on the local filesystem.

ibm_cloud_sdk_core/authenticators/cp4d_authenticator.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -15,13 +15,15 @@
 # limitations under the License.
 
 from typing import Dict, Optional
-
 from requests import Request
 
+from ibm_cloud_sdk_core.logger import get_logger
 from .authenticator import Authenticator
 from ..token_managers.cp4d_token_manager import CP4DTokenManager
 from ..utils import has_bad_first_or_last_char
 
+logger = get_logger()
+
 
 class CloudPakForDataAuthenticator(Authenticator):
     """The CloudPakForDataAuthenticator utilizes a username and password pair to
@@ -52,23 +54,32 @@ class CloudPakForDataAuthenticator(Authenticator):
         ValueError: The username, password/apikey, and/or url are not valid for CP4D token requests.
     """
 
-    def __init__(self,
-                 username: str = None,
-                 password: str = None,
-                 url: str = None,
-                 *,
-                 apikey: str = None,
-                 disable_ssl_verification: bool = False,
-                 headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 verify: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        username: str = None,
+        password: str = None,
+        url: str = None,
+        *,
+        apikey: str = None,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        verify: Optional[str] = None,
+    ) -> None:
         # Check the type of `disable_ssl_verification`. Must be a bool.
         if not isinstance(disable_ssl_verification, bool):
             raise TypeError('disable_ssl_verification must be a bool')
 
         self.token_manager = CP4DTokenManager(
-            username=username, password=password, apikey=apikey, url=url,
-            disable_ssl_verification=disable_ssl_verification, headers=headers, proxies=proxies, verify=verify)
+            username=username,
+            password=password,
+            apikey=apikey,
+            url=url,
+            disable_ssl_verification=disable_ssl_verification,
+            headers=headers,
+            proxies=proxies,
+            verify=verify,
+        )
 
         self.validate()
 
@@ -88,24 +99,27 @@ class CloudPakForDataAuthenticator(Authenticator):
         if self.token_manager.username is None:
             raise ValueError('The username shouldn\'t be None.')
 
-        if ((self.token_manager.password is None and self.token_manager.apikey is None)
-                or (self.token_manager.password is not None and self.token_manager.apikey is not None)):
-            raise ValueError(
-                'Exactly one of `apikey` or `password` must be specified.')
+        if (self.token_manager.password is None and self.token_manager.apikey is None) or (
+            self.token_manager.password is not None and self.token_manager.apikey is not None
+        ):
+            raise ValueError('Exactly one of `apikey` or `password` must be specified.')
 
         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):
+        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.')
+                '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.')
+                'Please remove any surrounding {, }, or \" characters.'
+            )
 
     def authenticate(self, req: Request) -> None:
         """Adds CP4D authentication information to the request.
@@ -115,12 +129,13 @@ class CloudPakForDataAuthenticator(Authenticator):
             Authorization: Bearer <bearer-token>
 
         Args:
-            req:  The request to add CP4D authentication information too. Must contain a key to a dictionary
+            req:  The request to add CP4D authentication information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')
         bearer_token = self.token_manager.get_token()
         headers['Authorization'] = 'Bearer {0}'.format(bearer_token)
+        logger.debug('Authenticated outbound request (type=%s)', self.authentication_type())
 
     def set_disable_ssl_verification(self, status: bool = False) -> None:
         """Set the flag that indicates whether verification of the server's SSL certificate should be

ibm_cloud_sdk_core/authenticators/iam_authenticator.py

@@ -56,24 +56,32 @@ class IAMAuthenticator(IAMRequestBasedAuthenticator):
         ValueError: The apikey, client_id, and/or client_secret are not valid for IAM token requests.
     """
 
-    def __init__(self,
-                 apikey: str,
-                 *,
-                 url: Optional[str] = None,
-                 client_id: Optional[str] = None,
-                 client_secret: Optional[str] = None,
-                 disable_ssl_verification: bool = False,
-                 headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None,
-                 scope: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        apikey: str,
+        *,
+        url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+        scope: Optional[str] = None,
+    ) -> None:
         # Check the type of `disable_ssl_verification`. Must be a bool.
         if not isinstance(disable_ssl_verification, bool):
             raise TypeError('disable_ssl_verification must be a bool')
 
         self.token_manager = IAMTokenManager(
-            apikey, url=url, client_id=client_id, client_secret=client_secret,
+            apikey,
+            url=url,
+            client_id=client_id,
+            client_secret=client_secret,
             disable_ssl_verification=disable_ssl_verification,
-            headers=headers, proxies=proxies, scope=scope)
+            headers=headers,
+            proxies=proxies,
+            scope=scope,
+        )
 
         self.validate()
 
@@ -98,4 +106,5 @@ class IAMAuthenticator(IAMRequestBasedAuthenticator):
         if has_bad_first_or_last_char(self.token_manager.apikey):
             raise ValueError(
                 'The apikey shouldn\'t start or end with curly brackets or quotes. '
-                'Please remove any surrounding {, }, or \" characters.')
+                'Please remove any surrounding {, }, or \" characters.'
+            )

ibm_cloud_sdk_core/authenticators/iam_request_based_authenticator.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-# Copyright 2019 IBM All Rights Reserved.
+# Copyright 2019, 2024 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.
@@ -18,8 +18,11 @@ from typing import Dict
 
 from requests import Request
 
+from ibm_cloud_sdk_core.logger import get_logger
 from .authenticator import Authenticator
 
+logger = get_logger()
+
 
 class IAMRequestBasedAuthenticator(Authenticator):
     """The IAMRequestBasedAuthenticator class contains code that is common to all authenticators
@@ -41,12 +44,10 @@ class IAMRequestBasedAuthenticator(Authenticator):
         Raises:
             ValueError: The client_id, and/or client_secret are not valid for IAM token requests.
         """
-        if (self.token_manager.client_id and
-                not self.token_manager.client_secret) or (
-                    not self.token_manager.client_id and
-                    self.token_manager.client_secret):
-            raise ValueError(
-                'Both client_id and client_secret should be initialized.')
+        if (self.token_manager.client_id and not self.token_manager.client_secret) or (
+            not self.token_manager.client_id and self.token_manager.client_secret
+        ):
+            raise ValueError('Both client_id and client_secret should be initialized.')
 
     def authenticate(self, req: Request) -> None:
         """Adds IAM authentication information to the request.
@@ -56,12 +57,13 @@ class IAMRequestBasedAuthenticator(Authenticator):
             Authorization: Bearer <bearer-token>
 
         Args:
-            req: The request to add IAM authentication information too. Must contain a key to a dictionary
+            req: The request to add IAM authentication information to. Must contain a key to a dictionary
             called headers.
         """
         headers = req.get('headers')
         bearer_token = self.token_manager.get_token()
         headers['Authorization'] = 'Bearer {0}'.format(bearer_token)
+        logger.debug('Authenticated outbound request (type=%s)', self.authentication_type())
 
     def set_client_id_and_secret(self, client_id: str, client_secret: str) -> None:
         """Set the client_id and client_secret pair the token manager will use for IAM token requests.

ibm_cloud_sdk_core/authenticators/mcsp_authenticator.py

@@ -0,0 +1,134 @@
+# coding: utf-8
+
+# Copyright 2023, 2024 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 typing import Dict, Optional
+
+from requests import Request
+
+from ibm_cloud_sdk_core.logger import get_logger
+from .authenticator import Authenticator
+from ..token_managers.mcsp_token_manager import MCSPTokenManager
+
+logger = get_logger()
+
+
+class MCSPAuthenticator(Authenticator):
+    """The MCSPAuthenticator uses an apikey to obtain an access token from the MCSP token server.
+    When the access token expires, a new access token is obtained from the token server.
+    The access token will be added to outbound requests via the Authorization header
+    of the form:    "Authorization: Bearer <access-token>"
+
+    Keyword Args:
+        url: The base endpoint URL for the MCSP token service [required].
+        apikey: The API key used to obtain an access token [required].
+        disable_ssl_verification:  A flag that indicates whether verification of the server's SSL
+            certificate should be disabled or not. Defaults to False.
+        headers: Default headers to be sent with every MCSP token request. Defaults to None.
+        proxies: Dictionary for mapping request protocol to proxy URL.
+        proxies.http (optional): The proxy endpoint to use for HTTP requests.
+        proxies.https (optional): The proxy endpoint to use for HTTPS requests.
+
+    Attributes:
+        token_manager (MCSPTokenManager): Retrieves and manages MCSP tokens from the endpoint specified by the url.
+
+    Raises:
+        TypeError: The `disable_ssl_verification` is not a bool.
+        ValueError: The apikey and/or url are not valid for MCSP token exchange requests.
+    """
+
+    def __init__(
+        self,
+        apikey: str,
+        url: str,
+        *,
+        disable_ssl_verification: bool = False,
+        headers: Optional[Dict[str, str]] = None,
+        proxies: Optional[Dict[str, str]] = None,
+    ) -> None:
+        # Check the type of `disable_ssl_verification`. Must be a bool.
+        if not isinstance(disable_ssl_verification, bool):
+            raise TypeError('disable_ssl_verification must be a bool')
+
+        self.token_manager = MCSPTokenManager(
+            apikey=apikey,
+            url=url,
+            disable_ssl_verification=disable_ssl_verification,
+            headers=headers,
+            proxies=proxies,
+        )
+
+        self.validate()
+
+    def authentication_type(self) -> str:
+        """Returns this authenticator's type ('mcsp')."""
+        return Authenticator.AUTHTYPE_MCSP
+
+    def validate(self) -> None:
+        """Validate apikey and url for token requests.
+
+        Raises:
+            ValueError: The apikey and/or url are not valid for token requests.
+        """
+        if self.token_manager.apikey is None:
+            raise ValueError('The apikey shouldn\'t be None.')
+
+        if self.token_manager.url is None:
+            raise ValueError('The url shouldn\'t be None.')
+
+    def authenticate(self, req: Request) -> None:
+        """Adds MCSP authentication information to the request.
+
+        The MCSP bearer token will be added to the request's headers in the form:
+            Authorization: Bearer <bearer-token>
+
+        Args:
+            req:  The request to add MCSP authentication information to. Must contain a key to a dictionary
+            called headers.
+        """
+        headers = req.get('headers')
+        bearer_token = self.token_manager.get_token()
+        headers['Authorization'] = 'Bearer {0}'.format(bearer_token)
+        logger.debug('Authenticated outbound request (type=%s)', self.authentication_type())
+
+    def set_disable_ssl_verification(self, status: bool = False) -> None:
+        """Set the flag that indicates whether verification of the server's SSL certificate should be
+        disabled or not. Defaults to False.
+
+        Args:
+            status: Set to true in order to disable SSL certificate verification. Defaults to False.
+
+        Raises:
+            TypeError: The `status` is not a bool.
+        """
+        self.token_manager.set_disable_ssl_verification(status)
+
+    def set_headers(self, headers: Dict[str, str]) -> None:
+        """Default headers to be sent with every MCSP token request.
+
+        Args:
+            headers: The headers to be sent with every MCSP token request.
+        """
+        self.token_manager.set_headers(headers)
+
+    def set_proxies(self, proxies: Dict[str, str]) -> None:
+        """Sets the proxies the token manager will use to communicate with MCSP on behalf of the host.
+
+        Args:
+            proxies: Dictionary for mapping request protocol to proxy URL.
+            proxies.http (optional): The proxy endpoint to use for HTTP requests.
+            proxies.https (optional): The proxy endpoint to use for HTTPS requests.
+        """
+        self.token_manager.set_proxies(proxies)