Linux: add an error handler for the XServer to prevent interpreter crash

Author: BoboTiG

CHANGELOG

@@ -2,6 +2,9 @@ History:
 
 <see Git checking messages for history>
 
+3.3.0   2018/08/xx
+      - Linux: add an error handler for the XServer to prevent interpreter crash (fix #61)
+
 3.2.1   2018/05/21
       - new contributor: Ryan Fox
       - Windows: enable Hi-DPI awareness

CHANGES.rst

@@ -1,3 +1,15 @@
+3.3.0 (2018-08-xx)
+==================
+
+exception.py
+------------
+- Added ``details`` attribute to ``ScreenShotError`` exception. Empty dict by default.
+
+linux.py
+--------
+- Added ``error_handler()`` function
+
+
 3.2.1 (2018-05-21)
 ==================
 

docs/source/api.rst

@@ -26,6 +26,20 @@ GNU/Linux
 
         See :meth:`mss.base.MSSBase.grab()` for details.
 
+.. function:: error_handler(display, event)
+
+    :type display: ctypes.POINTER(Display)
+    :param display: The display impacted by the error.
+    :type event: ctypes.POINTER(Event)
+    :param event: XError details.
+    :return int: Always ``0``.
+
+    Error handler passed to `X11.XSetErrorHandler()` to catch any error that can happen when calling a X11 function.
+    This will prevent Python interpreter crashes.
+
+    When such an error happen, a :class:`mss.exception.ScreenShotError` exception is raised and all XError information are added to the :attr:`mss.exception.ScreenShotError.details` attribute.
+
+    .. versionadded:: 3.3.0
 
 Methods
 =======
@@ -231,6 +245,17 @@ Exception
 
     Base class for MSS exceptions.
 
+    .. attribute:: details
+
+        On GNU/Linux, and if the error comes from the XServer, it contains XError details.
+        This is an empty dict by default.
+
+        For Xerrors, you can find information on `Using the Default Error Handlers <https://tronche.com/gui/x/xlib/event-handling/protocol-errors/default-handlers.html>`_.
+
+        :rtype: dict[str, Any]
+
+        .. versionchanged:: 3.3.0
+
 
 Factory
 =======

docs/source/conf.py

@@ -31,7 +31,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.2.1'
+version = '3.3.0'
 
 # The full version, including alpha/beta/rc tags.
 release = 'latest'

mss/__init__.py

@@ -13,7 +13,7 @@
 from .exception import ScreenShotError
 from .factory import mss
 
-__version__ = '3.2.1'
+__version__ = "3.3.0"
 __author__ = "Mickaël 'Tiger-222' Schoentgen"
 __copyright__ = """
     Copyright (c) 2013-2018, Mickaël 'Tiger-222' Schoentgen

mss/exception.py

@@ -7,3 +7,8 @@
 
 class ScreenShotError(Exception):
     """ Error handling class. """
+
+    def __init__(self, message, details=None):
+        # type: (Dict[str, Any]) -> None
+        super(Exception, self).__init__(message)
+        self.details = details or dict()