Merge pull request plotly#304 from plotly/clean-up-error-handling

Clean up error handling

Author: theengineear

plotly/exceptions.py

@@ -4,16 +4,6 @@
 
 A module that contains plotly's exception hierarchy.
 
-message (required!) (should be root message + caller message)
-info: (required!)
-    path_to_error (required!)
-    minimal_message (required!)
-
-- minimal_message is set inside this module, should not be set elsewhere
-
-- message is set inside this module, should not be set elsewhere
-
-
 """
 import json
 
@@ -56,7 +46,7 @@ def __str__(self):
         return self.message
 
 
-# Grid Errors #
+# Grid Errors
 COLUMN_NOT_YET_UPLOADED_MESSAGE = (
     "Hm... it looks like your column '{column_name}' hasn't "
     "been uploaded to Plotly yet. You need to upload your "
@@ -72,126 +62,86 @@ def __str__(self):
     "the column \"{0}\" and try again."
 )
 
-# Would Cause Server Errors
 
 class PlotlyEmptyDataError(PlotlyError):
     pass
 
 
 # Graph Objects Errors
 class PlotlyGraphObjectError(PlotlyError):
-    def __init__(self, message='', path=None, notes=None, plain_message=''):
+    def __init__(self, message='', path=(), notes=()):
+        """
+        General graph object error for validation failures.
+
+        :param (str|unicode) message: The error message.
+        :param (iterable) path: A path pointing to the error.
+        :param notes: Add additional notes, but keep default exception message.
+
+        """
         self.message = message
-        self.plain_message=plain_message
-        if isinstance(path, list):
-            self.path = path
-        elif path is None:
-            self.path = []
-        else:
-            self.path = [path]
-        if isinstance(notes, list):
-            self.notes = notes
-        elif notes is None:
-            self.notes = []
-        else:
-            self.notes = [notes]
+        self.plain_message = message  # for backwards compat
+        self.path = list(path)
+        self.notes = notes
         super(PlotlyGraphObjectError, self).__init__(message)
-        self.prepare()
-
-    def add_note(self, note):
-        if isinstance(note, list):
-            self.notes += note
-        else:
-            self.notes += [note]
 
-    def add_to_error_path(self, path):
-        if isinstance(path, list):
-            self.path = path + self.path
-        else:
-            self.path = [path] + self.path
-
-    def prepare(self):
-        message = self.message
-        message += "\n\nPath To Error:\n["
-        for iii, key in enumerate(self.path):
-            message += repr(key)
-            if iii < len(self.path) - 1:
-                message += "]["
-        message += "]"
-        if len(self.notes):
-            message += "\n\nAdditional Notes:\n{0}".format(
-                "\n".join(self.notes))
-        if len(self.args) > 1:
-            self.args = (message, self.args[1:][0])
-        else:
-            self.args = message,
+    def __str__(self):
+        """This is called by Python to present the error message."""
+        format_dict = {
+            'message': self.message,
+            'path': '[' + ']['.join(repr(k) for k in self.path) + ']',
+            'notes': '\n'.join(self.notes)
+        }
+        return ('{message}\n\nPath To Error: {path}\n\n{notes}'
+                .format(**format_dict))
 
 
 class PlotlyDictKeyError(PlotlyGraphObjectError):
-    def __init__(self, obj='', key='', **kwargs):
-        message = (
-            "Invalid key, '{key}', for class, '{obj_name}'.\n\nRun "
-            "'help(plotly.graph_objs.{obj_name})' for more information."
-            "".format(key=key, obj_name=obj.__class__.__name__)
+    def __init__(self, obj, path, notes=()):
+        """See PlotlyGraphObjectError.__init__ for param docs."""
+        format_dict = {'attribute': path[-1], 'object_name': obj._name}
+        message = ("'{attribute}' is not allowed in '{object_name}'"
+                   .format(**format_dict))
+        notes = [obj.help(return_help=True)] + list(notes)
+        super(PlotlyDictKeyError, self).__init__(
+            message=message, path=path, notes=notes
         )
-        plain_message = ("Invalid key, '{key}', found in '{obj}' object"
-                         "".format(key=key, obj=obj.__class__.__name__))
-        super(PlotlyDictKeyError, self).__init__(message=message,
-                                                 path=[key],
-                                                 plain_message=plain_message,
-                                                 **kwargs)
 
 
 class PlotlyDictValueError(PlotlyGraphObjectError):
-    def __init__(self, obj='', key='', value='', val_types='', **kwargs):
-        message = (
-            "Invalid value type, '{value_name}', associated with key, "
-            "'{key}', for class, '{obj_name}'.\nValid types for this key "
-            "are:\n '{val_types}'.\n\nRun 'help(plotly.graph_objs.{obj_name})' "
-            "for more information.".format(key=key,
-                                           value_name=value.__class__.__name__,
-                                           val_types=val_types,
-                                           obj_name=obj.__class__.__name__)
+    def __init__(self, obj, path, notes=()):
+        """See PlotlyGraphObjectError.__init__ for param docs."""
+        format_dict = {'attribute': path[-1], 'object_name': obj._name}
+        message = ("'{attribute}' has invalid value inside '{object_name}'"
+                   .format(**format_dict))
+        notes = [obj.help(path[-1], return_help=True)] + list(notes)
+        super(PlotlyDictValueError, self).__init__(
+            message=message, notes=notes, path=path
         )
-        plain_message = ("Invalid value found in '{obj}' associated with key, "
-                         "'{key}'".format(key=key, obj=obj.__class__.__name__))
-        super(PlotlyDictValueError, self).__init__(message=message,
-                                                   plain_message=plain_message,
-                                                   path=[key],
-                                                   **kwargs)
 
 
 class PlotlyListEntryError(PlotlyGraphObjectError):
-    def __init__(self, obj='', index='', entry='', **kwargs):
-        message = (
-            "The entry at index, '{0}', is invalid in a '{1}' object"
-            "".format(index, obj.__class__.__name__)
-        )
-        plain_message = (
-            "Invalid entry found in '{obj}' object at index, '{index}'."
-            "".format(obj=obj.__class__.__name__, index=index)
+    def __init__(self, obj, path, notes=()):
+        """See PlotlyGraphObjectError.__init__ for param docs."""
+        format_dict = {'index': path[-1], 'object_name': obj._name}
+        message = ("Invalid entry found in '{object_name}' at index, '{index}'"
+                   .format(**format_dict))
+        notes = [obj.help(return_help=True)] + list(notes)
+        super(PlotlyListEntryError, self).__init__(
+            message=message, path=path, notes=notes
         )
-        super(PlotlyListEntryError, self).__init__(message=message,
-                                                   plain_message=plain_message,
-                                                   path=[index],
-                                                   **kwargs)
 
 
 class PlotlyDataTypeError(PlotlyGraphObjectError):
-    def __init__(self, obj='', index='', **kwargs):
-        message = (
-                "The entry at index, '{0}', is invalid because it does not "
-                "contain a valid 'type' key-value. This is required for valid "
-                "'{1}' lists.".format(index, obj.__class__.__name__)
+    def __init__(self, obj, path, notes=()):
+        """See PlotlyGraphObjectError.__init__ for param docs."""
+        format_dict = {'index': path[-1], 'object_name': obj._name}
+        message = ("Invalid entry found in '{object_name}' at index, '{index}'"
+                   .format(**format_dict))
+        note = "It's invalid because it does't contain a valid 'type' value."
+        notes = [note] + list(notes)
+        super(PlotlyDataTypeError, self).__init__(
+            message=message, path=path, notes=notes
         )
-        plain_message = (
-                "Invalid entry found in 'data' object at index, '{0}'. It "
-                "does not contain a valid 'type' key, required for 'data' "
-                "lists.".format(index))
-        super(PlotlyDataTypeError, self).__init__(message=message,
-                                                  plain_message=plain_message,
-                                                  path=[index],
-                                                  **kwargs)
 
 
 # Local Config Errors
@@ -201,7 +151,8 @@ class PlotlyLocalError(PlotlyError):
 
 class PlotlyLocalCredentialsError(PlotlyLocalError):
     def __init__(self):
-        message = ("\n"
+        message = (
+            "\n"
             "Couldn't find a 'username', 'api-key' pair for you on your local "
             "machine. To sign in temporarily (until you stop running Python), "
             "run:\n"
@@ -210,8 +161,10 @@ def __init__(self):
             "Even better, save your credentials permanently using the 'tools' "
             "module:\n"
             ">>> import plotly.tools as tls\n"
-            ">>> tls.set_credentials_file(username='username', api_key='api-key')\n\n"
-            "For more help, see https://plot.ly/python.\n")
+            ">>> tls.set_credentials_file(username='username', "
+            "api_key='api-key')\n\n"
+            "For more help, see https://plot.ly/python.\n"
+        )
         super(PlotlyLocalCredentialsError, self).__init__(message)
 
 

plotly/graph_objs/graph_objs.py

@@ -88,13 +88,21 @@ def _get_class_name(self):
         """For convenience. See `graph_reference.object_name_to_class_name`."""
         return graph_reference.object_name_to_class_name(self._name)
 
-    def help(self):
-        """Print a help string for this object."""
+    def help(self, return_help=False):
+        """
+        Print a help string for this object.
+
+        :param (bool) return_help: Return help string instead of prining?
+        :return: (None|str) Optionally can return help string.
+
+        """
         object_name = self._name
         path = self._get_path()
         parent_object_names = self._get_parent_object_names()
         help_string = graph_objs_tools.get_help(object_name, path,
                                                 parent_object_names)
+        if return_help:
+            return help_string
         print(help_string)
 
     def to_graph_objs(self, **kwargs):
@@ -137,21 +145,20 @@ def __init__(self, *args, **kwargs):
             )
 
         if args and isinstance(args[0], dict):
-            raise exceptions.PlotlyListEntryError(
-                obj=self,
-                index=0,
-                notes="Just like a `list`, `{name}` must be instantiated with "
-                      "a *single* collection.\n"
-                      "In other words these are OK:\n"
-                      ">>> {name}()\n"
-                      ">>> {name}([])\n"
-                      ">>> {name}([dict()])\n"
-                      ">>> {name}([dict(), dict()])\n"
-                      "However, these don't make sense:\n"
-                      ">>> {name}(dict())\n"
-                      ">>> {name}(dict(), dict())"
-                      "".format(name=self._get_class_name())
+            note = (
+                "Just like a `list`, `{name}` must be instantiated "
+                "with a *single* collection.\n"
+                "In other words these are OK:\n"
+                ">>> {name}()\n"
+                ">>> {name}([])\n"
+                ">>> {name}([dict()])\n"
+                ">>> {name}([dict(), dict()])\n"
+                "However, these don't make sense:\n"
+                ">>> {name}(dict())\n"
+                ">>> {name}(dict(), dict())"
+                .format(name=self._get_class_name())
             )
+            raise exceptions.PlotlyListEntryError(self, [0], notes=[note])
 
         super(PlotlyList, self).__init__()
 
@@ -211,10 +218,8 @@ def _value_to_graph_object(self, index, value, _raise=True):
         """
         if not isinstance(value, dict):
             if _raise:
-                e = exceptions.PlotlyListEntryError(self, index, value)
-                e.path = self._get_path() + (index, )
-                e.prepare()
-                raise e
+                path = self._get_path() + (index, )
+                raise exceptions.PlotlyListEntryError(self, path)
             else:
                 return
 
@@ -423,10 +428,8 @@ def __setitem__(self, key, value, _raise=True):
                 return super(PlotlyDict, self).__setitem__(key, value)
             else:
                 if _raise:
-                    e = exceptions.PlotlyDictKeyError(self, key)
-                    e.path = self._get_path() + (key, )
-                    e.prepare()
-                    raise e
+                    path = self._get_path() + (key, )
+                    raise exceptions.PlotlyDictKeyError(self, path)
                 return
 
         if self._get_attribute_role(key) == 'object':
@@ -534,30 +537,36 @@ def _value_to_graph_object(self, key, value, _raise=True):
 
         if not isinstance(value, val_types):
             if _raise:
-                e = exceptions.PlotlyDictValueError(self, key, value,
-                                                    val_types)
-                e.path = self._get_path() + (key, )
-                e.prepare()
-                raise e
+                path = self._get_path() + (key, )
+                raise exceptions.PlotlyDictValueError(self, path)
             else:
                 return
 
         # this can be `None` when `_raise == False`
         return GraphObjectFactory.create(key, value, _raise=_raise,
                                          _parent=self, _parent_key=key)
 
-    def help(self, attribute=None):
-        """Print help string for this object or an attribute of this object."""
+    def help(self, attribute=None, return_help=False):
+        """
+        Print help string for this object or an attribute of this object.
+
+        :param (str) attribute: A valid attribute string for this object.
+        :param (bool) return_help: Return help_string instead of printing it?
+        :return: (None|str)
+
+        """
         if not attribute:
-            super(PlotlyDict, self).help()
-        else:
-            object_name = self._name
-            path = self._get_path()
-            parent_object_names = self._get_parent_object_names()
-            help_string = graph_objs_tools.get_help(object_name, path,
-                                                    parent_object_names,
-                                                    attribute)
-            print(help_string)
+            return super(PlotlyDict, self).help(return_help=return_help)
+
+        object_name = self._name
+        path = self._get_path()
+        parent_object_names = self._get_parent_object_names()
+        help_string = graph_objs_tools.get_help(object_name, path,
+                                                parent_object_names, attribute)
+
+        if return_help:
+            return help_string
+        print(help_string)
 
     def update(self, dict1=None, **dict2):
         """
@@ -929,19 +938,17 @@ def _value_to_graph_object(self, index, value, _raise=True):
 
         if not isinstance(value, dict):
             if _raise:
-                e = exceptions.PlotlyListEntryError(self, index, value)
-                e.add_note('Entry should subclass dict.')
-                raise e
+                notes = ['Entry should subclass dict.']
+                path = self._get_path() + (index, )
+                raise exceptions.PlotlyListEntryError(self, path, notes=notes)
             else:
                 return
 
         item = value.get('type', 'scatter')
         if item not in graph_reference.ARRAYS['data']['items']:
             if _raise:
-                err = exceptions.PlotlyDataTypeError(self, index)
-                err.path = self._get_path() + (0, )
-                err.prepare()
-                raise err
+                path = self._get_path() + (0, )
+                raise exceptions.PlotlyDataTypeError(self, path)
 
         return GraphObjectFactory.create(item, _raise=_raise, _parent=self,
                                          _parent_key=index, **value)