Implemented key validation and explained some API exceptions.

smiley · smiley · commit 444663534240 · 2016-12-31T22:04:42.000+02:00
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ Clone/[Download](/smiley/steamapi/archive/master.zip) (and extract) the reposito
 Then, you can use it like this:
 ```python
 >>> import steamapi
->>> steamapi.core.APIConnection(api_key="ABCDEFGHIJKLMNOPQRSTUVWXYZ")  # <-- Insert API key here
+>>> steamapi.core.APIConnection(api_key="ABCDEFGHIJKLMNOPQRSTUVWXYZ", validate_key=True)  # <-- Insert API key here
 >>> steamapi.user.SteamUser(userurl="smileybarry")  # For http://steamcommunity.com/id/smileybarry
 Or:
 >>> steamapi.user.SteamUser(76561197996416028)  # Using the 64-bit Steam user ID
diff --git a/steamapi/core.py b/steamapi/core.py
@@ -6,7 +6,7 @@
 
 from .consts import API_CALL_DOCSTRING_TEMPLATE, API_CALL_PARAMETER_TEMPLATE, IPYTHON_PEEVES, IPYTHON_MODE
 from .decorators import Singleton, cached_property, INFINITE
-from .errors import APIException
+from .errors import APIException, APIUnauthorized, APIKeyRequired, APIPrivate, APIConfigurationError
 from . import errors
 
 GET = "GET"
@@ -226,7 +226,8 @@ def __call__(self, method=GET, **kwargs):
 
 class APIInterface(object):
     def __init__(self, api_key=None, autopopulate=False, strict=False,
-                 api_domain="api.steampowered.com", api_protocol="http", settings=None):
+                 api_domain="api.steampowered.com", api_protocol="http", settings=None,
+                 validate_key=False):
         """
         Initialize a new APIInterface object. This object defines an API-interacting session, and is used to call
         any API functions from standard code.
@@ -285,6 +286,15 @@ def set_attribute(name, value):
                 self._autopopulate_interfaces()
             finally:
                 self.__dict__['_strict'] = original_strict_value
+        elif validate_key is True:
+            if api_key is None:
+                raise ValueError('"validate_key" is True, but no key was given.')
+            
+            # Call "GetSupportedAPIList", which is guaranteed to succeed with any valid key. (Or no key)
+            try:
+                self.ISteamWebAPIUtil.GetSupportedAPIList.v1(key=self._api_key)
+            except (APIUnauthorized, APIKeyRequired, APIPrivate):
+                raise APIConfigurationError("This API key is invalid.")
 
     def _autopopulate_interfaces(self):
         # Call the API which returns a list of API Services and Interfaces.
@@ -364,7 +374,7 @@ class APIConnection(object):
     # Use double curly-braces to tell Python that these variables shouldn't be expanded yet.
     QUERY_TEMPLATE = "{domain}/{{interface}}/{{command}}/{{version}}/".format(domain=QUERY_DOMAIN)
 
-    def __init__(self, api_key=None, settings={}):
+    def __init__(self, api_key=None, settings={}, validate_key=False):
         """
         NOTE: APIConnection will soon be made deprecated by APIInterface.
 
@@ -378,6 +388,7 @@ def __init__(self, api_key=None, settings={}):
                         a group of users, such as "friends", should precache player summaries,
                         like nicknames. Recommended if you plan to use nicknames right away, since
                         caching is done in groups and retrieving one-by-one takes a while.
+        :param validate_key: Perform a test call to the API with the given key to test its validity.
 
         """
         self.reset(api_key)
@@ -386,6 +397,16 @@ def __init__(self, api_key=None, settings={}):
 
         if 'precache' in settings and issubclass(type(settings['precache']), bool):
             self.precache = settings['precache']
+            
+        if validate_key:
+            if api_key is None:
+                raise ValueError('"validate_key" is True, but no key was given.')
+            
+            # Call "GetSupportedAPIList", which is guaranteed to succeed with any valid key. (Or no key)
+            try:
+                self.call("ISteamWebAPIUtil", "GetSupportedAPIList", "v1")
+            except (APIUnauthorized, APIKeyRequired, APIPrivate):
+                raise APIConfigurationError("This API key is invalid.")
 
     def reset(self, api_key):
         self._api_key = api_key
diff --git a/steamapi/errors.py b/steamapi/errors.py
@@ -87,7 +87,8 @@ class APIPrivate(APIFailure):
 
 class APIConfigurationError(APIFailure):
     """
-    There's either no APIConnection defined, or
+    There's either no APIConnection defined, or the parameters given to "APIConnection" or "APIInterface" are
+    invalid.
     """
     pass
 
@@ -98,19 +99,19 @@ def check(response):
     """
     if response.status_code // 100 == 4:
         if response.status_code == 404:
-            raise APINotFound()
+            raise APINotFound("The function or service you tried to call does not exist.")
         elif response.status_code == 401:
-            raise APIUnauthorized()
+            raise APIUnauthorized("This API is inaccessible to you.")
         elif response.status_code == 403:
             if '?key=' in response.request.url or '&key=' in response.request.url:
-                raise APIPrivate()
+                raise APIPrivate("You have no permission to use this API, or your key may be invalid.")
             else:
-                raise APIKeyRequired()
+                raise APIKeyRequired("This API requires a key to call.")
         elif response.status_code == 400:
-            raise APIBadCall()
+            raise APIBadCall("The parameters you sent didn't match this API's requirements.")
         else:
-            raise APIFailure()
+            raise APIFailure("Something is wrong with your configuration, parameters or environment.")
     elif response.status_code // 100 == 5:
-        raise APIError()
+        raise APIError("The API server has encountered an unknown error.")
     else:
         return
