feat: Add type annotations to parameters and return values

BREAKING CHANGE: Type annotations new in Python3

Author: rmkeezer

ibm_cloud_sdk_core/api_exception.py

@@ -33,7 +33,7 @@ class ApiException(Exception):
         global_transaction_id (str, optional): Globally unique id the service endpoint has given a transaction.
     """
 
-    def __init__(self, code: int, *, message: Optional[str] = None, http_response: Optional[Response] = None):
+    def __init__(self, code: int, *, message: Optional[str] = None, http_response: Optional[Response] = None) -> None:
         # Call the base class constructor with the parameters it needs
         super().__init__(message)
         self.message = message
@@ -44,14 +44,14 @@ def __init__(self, code: int, *, message: Optional[str] = None, http_response: O
             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)
 
-    def __str__(self):
+    def __str__(self) -> str:
         msg = 'Error: ' + str(self.message) + ', Code: ' + str(self.code)
         if self.global_transaction_id is not None:
             msg += ' , X-global-transaction-id: ' + str(self.global_transaction_id)
         return  msg
 
     @staticmethod
-    def _get_error_message(response: Response):
+    def _get_error_message(response: Response) -> str:
         error_message = 'Unknown error'
         try:
             error_json = response.json()

ibm_cloud_sdk_core/authenticators/authenticator.py

@@ -19,17 +19,23 @@
 class Authenticator(ABC):
     """This interface defines the common methods and constants associated with an Authenticator implementation."""
     @abstractmethod
-    def authenticate(self, req: dict):
+    def authenticate(self, req: dict) -> None:
         """Perform the necessary authentication steps for the specified request.
 
+        Attributes:
+            req (dict): Will be modified to contain the appropriate authentication information.
+
         To be implemented by subclasses.
         """
         pass
 
     @abstractmethod
-    def validate(self):
+    def validate(self) -> None:
         """Validates the current set of configuration information in the Authenticator.
 
+        Raises:
+            ValueError: The configuration information is not valid for service operations.
+
         To be implemented by subclasses.
         """
         pass

ibm_cloud_sdk_core/authenticators/basic_authenticator.py

@@ -37,14 +37,14 @@ class BasicAuthenticator(Authenticator):
     """
     authentication_type = 'basic'
 
-    def __init__(self, username: str, password: str):
+    def __init__(self, username: str, password: str) -> None:
         self.username = username
         self.password = password
         self.validate()
         self.authorization_header = self.__construct_basic_auth_header()
 
 
-    def validate(self):
+    def validate(self) -> None:
         """Validate username and password.
 
         Ensure the username and password are valid for service operations.
@@ -62,13 +62,13 @@ def validate(self):
                 'Please remove any surrounding {, }, or \" characters.')
 
 
-    def __construct_basic_auth_header(self):
+    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')
         return 'Basic {0}'.format(base64_authorization)
 
 
-    def authenticate(self, req: Request):
+    def authenticate(self, req: Request) -> None:
         """Add basic authentication information to a request.
 
         Basic Authorization will be added to the request's headers in the form:

ibm_cloud_sdk_core/authenticators/bearer_token_authenticator.py

@@ -34,11 +34,11 @@ class BearerTokenAuthenticator(Authenticator):
     """
     authentication_type = 'bearerToken'
 
-    def __init__(self, bearer_token: str):
+    def __init__(self, bearer_token: str) -> None:
         self.bearer_token = bearer_token
         self.validate()
 
-    def validate(self):
+    def validate(self) -> None:
         """Validate the bearer token.
 
         Ensures the bearer token is valid for service operations.
@@ -49,7 +49,7 @@ def validate(self):
         if self.bearer_token is None:
             raise ValueError('The bearer token shouldn\'t be None.')
 
-    def authenticate(self, req: Request):
+    def authenticate(self, req: Request) -> None:
         """Adds bearer authentication information to the request.
 
         The bearer token will be added to the request's headers in the form:
@@ -63,7 +63,7 @@ def authenticate(self, req: Request):
         headers = req.get('headers')
         headers['Authorization'] = 'Bearer {0}'.format(self.bearer_token)
 
-    def set_bearer_token(self, bearer_token: str):
+    def set_bearer_token(self, bearer_token: str) -> None:
         """Set a new bearer token to be sent in subsequent service operations.
 
         Args:

ibm_cloud_sdk_core/authenticators/cp4d_authenticator.py

@@ -59,13 +59,13 @@ def __init__(self,
                  *,
                  disable_ssl_verification: bool = False,
                  headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None):
+                 proxies: Optional[Dict[str, str]] = None) -> None:
         self.token_manager = CP4DTokenManager(
             username, password, url, disable_ssl_verification=disable_ssl_verification,
             headers=headers, proxies=proxies)
         self.validate()
 
-    def validate(self):
+    def validate(self) -> None:
         """Validate username, password, and url for token requests.
 
         Ensures the username, password, and url are not None. Additionally, ensures they do not contain invalid
@@ -91,7 +91,7 @@ def validate(self):
                 'The url shouldn\'t start or end with curly brackets or quotes. '
                 'Please remove any surrounding {, }, or \" characters.')
 
-    def authenticate(self, req: Request):
+    def authenticate(self, req: Request) -> None:
         """Adds CP4D authentication information to the request.
 
         The CP4D bearer token will be added to the request's headers in the form:
@@ -106,7 +106,7 @@ def authenticate(self, req: Request):
         bearer_token = self.token_manager.get_token()
         headers['Authorization'] = 'Bearer {0}'.format(bearer_token)
 
-    def set_disable_ssl_verification(self, status: bool = False):
+    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.
 
@@ -115,15 +115,15 @@ def set_disable_ssl_verification(self, status: bool = False):
         """
         self.token_manager.set_disable_ssl_verification(status)
 
-    def set_headers(self, headers: Dict[str, str]):
+    def set_headers(self, headers: Dict[str, str]) -> None:
         """Default headers to be sent with every CP4D token request.
 
         Args:
             headers: The headers to be sent with every CP4D token request.
         """
         self.token_manager.set_headers(headers)
 
-    def set_proxies(self, proxies: Dict[str, str]):
+    def set_proxies(self, proxies: Dict[str, str]) -> None:
         """Sets the proxies the token manager will use to communicate with CP4D on behalf of the host.
 
         Args:

ibm_cloud_sdk_core/authenticators/iam_authenticator.py

@@ -60,16 +60,16 @@ def __init__(self,
                  url: Optional[str] = None,
                  client_id: Optional[str] = None,
                  client_secret: Optional[str] = None,
-                 disable_ssl_verification: Optional[bool] = False,
+                 disable_ssl_verification: bool = False,
                  headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None):
+                 proxies: Optional[Dict[str, str]] = None) -> None:
         self.token_manager = IAMTokenManager(
             apikey, url=url, client_id=client_id, client_secret=client_secret,
             disable_ssl_verification=disable_ssl_verification,
             headers=headers, proxies=proxies)
         self.validate()
 
-    def validate(self):
+    def validate(self) -> None:
         """Validates the apikey, client_id, and client_secret for IAM token requests.
 
         Ensure the apikey is not none, and has no bad characters. Additionally, ensure the
@@ -93,7 +93,7 @@ def validate(self):
             raise ValueError(
                 'Both client_id and client_secret should be initialized.')
 
-    def authenticate(self, req: Request):
+    def authenticate(self, req: Request) -> None:
         """Adds IAM authentication information to the request.
 
         The IAM bearer token will be added to the request's headers in the form:
@@ -108,7 +108,7 @@ def authenticate(self, req: Request):
         bearer_token = self.token_manager.get_token()
         headers['Authorization'] = 'Bearer {0}'.format(bearer_token)
 
-    def set_client_id_and_secret(self, client_id: str, client_secret: str):
+    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.
 
         Args:
@@ -121,7 +121,7 @@ def set_client_id_and_secret(self, client_id: str, client_secret: str):
         self.token_manager.set_client_id_and_secret(client_id, client_secret)
         self.validate()
 
-    def set_disable_ssl_verification(self, status: bool = False):
+    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.
 
@@ -130,15 +130,15 @@ def set_disable_ssl_verification(self, status: bool = False):
         """
         self.token_manager.set_disable_ssl_verification(status)
 
-    def set_headers(self, headers: Dict[str, str]):
+    def set_headers(self, headers: Dict[str, str]) -> None:
         """Headers to be sent with every IAM token request.
 
         Args:
             headers: Headers to be sent with every IAM token request.
         """
         self.token_manager.set_headers(headers)
 
-    def set_proxies(self, proxies: Dict[str, str]):
+    def set_proxies(self, proxies: Dict[str, str]) -> None:
         """Sets the proxies the token manager will use to communicate with IAM on behalf of the host.
 
         Args:

ibm_cloud_sdk_core/authenticators/no_auth_authenticator.py

@@ -20,8 +20,8 @@ class NoAuthAuthenticator(Authenticator):
     """Performs no authentication."""
     authentication_type = 'noAuth'
 
-    def validate(self):
+    def validate(self) -> None:
         pass
 
-    def authenticate(self, req):
+    def authenticate(self, req) -> None:
         pass

ibm_cloud_sdk_core/base_service.py

@@ -68,7 +68,7 @@ def __init__(self,
                  *,
                  service_url: str = None,
                  authenticator: Authenticator = None,
-                 disable_ssl_verification: bool = False):
+                 disable_ssl_verification: bool = False) -> None:
         self.service_url = service_url
         self.http_config = {}
         self.jar = CookieJar()
@@ -83,18 +83,18 @@ def __init__(self,
                 'authenticator should be of type Authenticator')
 
     @staticmethod
-    def _get_system_info():
+    def _get_system_info() -> str:
         return '{0} {1} {2}'.format(
             platform.system(),  # OS
             platform.release(),  # OS version
             platform.python_version()  # Python version
         )
 
-    def _build_user_agent(self):
+    def _build_user_agent(self) -> str:
         return '{0}-{1} {2}'.format(self.SDK_NAME, __version__,
                                     self._get_system_info())
 
-    def configure_service(self, service_name: str):
+    def configure_service(self, service_name: str) -> None:
         """Look for external configuration of a service. Set service properties.
 
         Try to get config from external sources, with the following priority:
@@ -119,10 +119,10 @@ def configure_service(self, service_name: str):
                 bool(config.get('DISABLE_SSL'))
             )
 
-    def _set_user_agent_header(self, user_agent_string=None):
+    def _set_user_agent_header(self, user_agent_string: str) -> None:
         self.user_agent_header = {'User-Agent': user_agent_string}
 
-    def set_http_config(self, http_config: dict):
+    def set_http_config(self, http_config: dict) -> None:
         """Sets the http config dictionary.
 
         The dictionary can contain values that control the timeout, proxies, and etc of HTTP requests.
@@ -141,7 +141,7 @@ def set_http_config(self, http_config: dict):
         else:
             raise TypeError("http_config parameter must be a dictionary")
 
-    def set_disable_ssl_verification(self, status: bool = False):
+    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.
 
@@ -150,7 +150,7 @@ def set_disable_ssl_verification(self, status: bool = False):
         """
         self.disable_ssl_verification = status
 
-    def set_service_url(self, service_url: str):
+    def set_service_url(self, service_url: str) -> None:
         """Set the url the service will make HTTP requests too.
 
         Arguments:
@@ -174,7 +174,7 @@ def get_authenticator(self) -> Authenticator:
         """
         return self.authenticator
 
-    def set_default_headers(self, headers: Dict[str, str]):
+    def set_default_headers(self, headers: Dict[str, str]) -> None:
         """Set http headers to be sent in every request.
 
         Arguments:
@@ -339,19 +339,19 @@ def encode_path_vars(*args: str) -> List[str]:
     # pylint: disable=protected-access
 
     @staticmethod
-    def _convert_model(val):
+    def _convert_model(val: str) -> None:
         if isinstance(val, str):
             val = json_import.loads(val)
         if hasattr(val, "_to_dict"):
             return val._to_dict()
         return val
 
     @staticmethod
-    def _convert_list(val):
+    def _convert_list(val: list) -> None:
         if isinstance(val, list):
             return ",".join(val)
         return val
 
     @staticmethod
-    def _encode_path_vars(*args):
+    def _encode_path_vars(*args) -> None:
         return (requests.utils.quote(x, safe='') for x in args)

ibm_cloud_sdk_core/cp4d_token_manager.py

@@ -55,7 +55,7 @@ def __init__(self,
                  *,
                  disable_ssl_verification: bool = False,
                  headers: Optional[Dict[str, str]] = None,
-                 proxies: Optional[Dict[str, str]] = None):
+                 proxies: Optional[Dict[str, str]] = None) -> None:
         self.username = username
         self.password = password
         if url and not self.VALIDATE_AUTH_PATH in url:
@@ -78,7 +78,7 @@ def request_token(self) -> dict:
             proxies=self.proxies)
         return response
 
-    def set_headers(self, headers: Dict[str, str]):
+    def set_headers(self, headers: Dict[str, str]) -> None:
         """Headers to be sent with every CP4D token request.
 
         Args:
@@ -89,7 +89,7 @@ def set_headers(self, headers: Dict[str, str]):
         else:
             raise TypeError('headers must be a dictionary')
 
-    def set_proxies(self, proxies: Dict[str, str]):
+    def set_proxies(self, proxies: Dict[str, str]) -> None:
         """Sets the proxies the token manager will use to communicate with CP4D on behalf of the host.
 
         Args:

ibm_cloud_sdk_core/detailed_response.py

@@ -37,7 +37,7 @@ def __init__(self,
                  *,
                  response: Optional[requests.Response] = None,
                  headers: Optional[Dict[str, str]] = None,
-                 status_code: Optional[int] = None):
+                 status_code: Optional[int] = None) -> None:
         self.result = response
         self.headers = headers
         self.status_code = status_code
@@ -66,7 +66,7 @@ def get_status_code(self) -> int:
         """
         return self.status_code
 
-    def _to_dict(self):
+    def _to_dict(self) -> dict:
         _dict = {}
         if hasattr(self, 'result') and self.result is not None:
             _dict['result'] = self.result if isinstance(self.result, (dict, list)) else 'HTTP response'
@@ -76,5 +76,5 @@ def _to_dict(self):
             _dict['status_code'] = self.status_code
         return _dict
 
-    def __str__(self):
+    def __str__(self) -> str:
         return json.dumps(self._to_dict(), indent=4, default=lambda o: o.__dict__)

ibm_cloud_sdk_core/get_authenticator.py

@@ -38,7 +38,7 @@ def get_authenticator_from_environment(service_name: str) -> Authenticator:
         authenticator = __construct_authenticator(config)
     return authenticator
 
-def __construct_authenticator(config):
+def __construct_authenticator(config: dict) -> Authenticator:
     auth_type = config.get('AUTH_TYPE').lower() if config.get('AUTH_TYPE') else 'iam'
     authenticator = None