MSS: improve type annotations and add CI check

Author: BoboTiG

.gitignore

@@ -14,3 +14,4 @@ MANIFEST*
 .tox
 .vscode
 docs/output/
+.mypy_cache/

.travis.yml

@@ -2,10 +2,17 @@ language: python
 dist: xenial
 
 matrix:
+  fast_finish: true
   include:
     - os: linux
       python: "3.7"
       env: TOXENV=lint
+    - os: linux
+      python: "3.7"
+      env: TOXENV=types
+    - os: linux
+      python: "3.7"
+      env: TOXENV=docs
     - os: osx
       language: generic
       env:

CHANGELOG

@@ -2,6 +2,10 @@ History:
 
 <see Git checking messages for history>
 
+5.0.0   2019/xx/xx
+      - removed support for Python 2.7
+      - MSS: improve type annotations and add CI check
+
 4.0.1   2019/01/26
       - Linux: fix several XLib functions signature (fixes #92)
       - Linux: improve monitors finding by a factor of 44

CHANGES.rst

@@ -1,3 +1,25 @@
+5.0.0 (2019-xx-xx)
+==================
+
+linux.py
+--------
+- Deleted ``LAST_ERROR`` constant. Use ``ERROR`` namespace instead, specially the ``ERROR.details`` attribute.
+
+models.py
+---------
+- Added ``Monitor``
+- Added ``Monitors``
+- Added ``Pixel``
+- Added ``Pixels``
+- Added ``Pos``
+- Added ``Size``
+
+screenshot.py
+-------------
+- Removed ``Pos``. Use ``models.Pos`` instead.
+- Removed ``Size``. Use ``models.Size`` instead.
+
+
 4.0.1 (2019-01-26)
 ==================
 

docs/source/api.rst

@@ -10,13 +10,13 @@ GNU/Linux
 
 .. module:: mss.linux
 
-.. attribute:: LAST_ERROR
+.. attribute:: ERROR
 
-    :type: dict[str, Any]
+    :type: types.SimpleNamspacedict
 
-    Contains the latest Xlib or XRANDR function.
+    The `details` attribute contains the latest Xlib or XRANDR function. It is a dict.
 
-    .. versionadded:: 4.0.0
+    .. versionadded:: 5.0.0
 
 .. class:: MSS
 

docs/source/conf.py

@@ -29,7 +29,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = "4.0.1"
+version = "5.0.0"
 
 # The full version, including alpha/beta/rc tags.
 release = "latest"

docs/source/developers.rst

@@ -41,27 +41,20 @@ Launch the test suit::
 This will test MSS and ensure a good code quality.
 
 
-Static Type Checking
-====================
-
-`mypy <http://mypy-lang.org/>`_ is a compile-time static type checker for Python, allowing optional, gradual typing of Python code.
-MSS is using special files syntax for type annotations, which means that type annotations are written inside **pyi** files.
+Code Quality
+============
 
+To ensure the code is always well enough using `flake8 <https://pypi.org/project/flake8/>`_::
 
-Dependencies
-------------
-
-Install required packages::
+    $ TOXENV=lint tox
 
-    $ python -m pip install --upgrade --user mypy-lang
 
+Static Type Checking
+====================
 
-Running Mypy
-------------
-
-::
+To check type annotation using `mypy <http://mypy-lang.org/>`_::
 
-    $ sh check-types.sh -p mss
+    $ TOXENV=types tox
 
 
 Documentation

mss/__init__.py

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

mss/__main__.py

@@ -9,12 +9,16 @@
 import os.path
 import sys
 from argparse import ArgumentParser
+from typing import TYPE_CHECKING
 
 from . import __version__
 from .exception import ScreenShotError
 from .factory import mss
 from .tools import to_png
 
+if TYPE_CHECKING:
+    from typing import List, Optional  # noqa
+
 
 def main(args=None):
     # type: (Optional[List[str]]) -> int

mss/base.py

@@ -5,17 +5,23 @@
 """
 
 from datetime import datetime
+from typing import TYPE_CHECKING
 
 from .exception import ScreenShotError
 from .screenshot import ScreenShot
 from .tools import to_png
 
+if TYPE_CHECKING:
+    from typing import Any, Callable, Iterator, List, Optional, Type  # noqa
+
+    from .models import Monitor, Monitors  # noqa
+
 
 class MSSMixin:
     """ This class will be overloaded by a system specific one. """
 
-    cls_image = ScreenShot  # type: object
-    compression_level = 6  # type: int
+    cls_image = ScreenShot  # type: Type[ScreenShot]
+    compression_level = 6
 
     def __enter__(self):
         # type: () -> MSSMixin
@@ -24,7 +30,6 @@ def __enter__(self):
         return self
 
     def __exit__(self, *_):
-        # type: (*str) -> None
         """ For the cool call `with MSS() as mss:`. """
 
         self.close()
@@ -34,7 +39,7 @@ def close(self):
         """ Clean-up. """
 
     def grab(self, monitor):
-        # type: (Dict[str, int]) -> ScreenShot
+        # type: (Monitor) -> ScreenShot
         """
         Retrieve screen pixels for a given monitor.
 
@@ -47,7 +52,7 @@ def grab(self, monitor):
 
     @property
     def monitors(self):
-        # type: () -> List[Dict[str, int]]
+        # type: () -> Monitors
         """
         Get positions of all monitors.
         If the monitor has rotation, you have to deal with it
@@ -131,6 +136,7 @@ def save(self, mon=0, output="monitor-{mon}.png", callback=None):
             yield output
 
     def shot(self, **kwargs):
+        # type: (Any) -> str
         """
         Helper to save the screen shot of the 1st monitor, by default.
         You can pass the same arguments as for ``save``.
@@ -142,7 +148,6 @@ def shot(self, **kwargs):
     @staticmethod
     def _cfactory(attr, func, argtypes, restype, errcheck=None):
         # type: (Any, str, List[Any], Any, Optional[Callable]) -> None
-        # pylint: disable=too-many-locals
         """ Factory to create a ctypes function and automatically manage errors. """
 
         meth = getattr(attr, func)

mss/darwin.py

@@ -11,16 +11,23 @@
 import ctypes
 import ctypes.util
 import sys
+from typing import TYPE_CHECKING
 
 from .base import MSSMixin
 from .exception import ScreenShotError
 from .screenshot import Size
 
+if TYPE_CHECKING:
+    from typing import Any, List, Type, Union  # noqa
+
+    from .models import Monitor, Monitors  # noqa
+    from .screenshot import ScreenShot  # noqa
+
 __all__ = ("MSS",)
 
 
 def cgfloat():
-    # type: () -> Any
+    # type: () -> Union[Type[ctypes.c_double], Type[ctypes.c_float]]
     """ Get the appropriate value for a float. """
 
     return ctypes.c_double if sys.maxsize > 2 ** 32 else ctypes.c_float
@@ -61,13 +68,11 @@ class MSS(MSSMixin):
     It uses intensively the CoreGraphics library.
     """
 
-    max_displays = 32  # type: int
-
-    def __init__(self):
-        # type: () -> None
+    def __init__(self, **_):
         """ macOS initialisations. """
 
-        self._monitors = []  # type: List[Dict[str, int]]
+        self._monitors = []  # type: Monitors
+        self.max_displays = 32
 
         coregraphics = ctypes.util.find_library("CoreGraphics")
         if not coregraphics:
@@ -77,13 +82,15 @@ def __init__(self):
         self._set_cfunctions()
 
     def _set_cfunctions(self):
+        # type: () -> None
         """ Set all ctypes functions and attach them to attributes. """
 
-        def cfactory(attr=self.core, func=None, argtypes=None, restype=None):
-            # type: (Any, str, List[Any], Any) -> None
-            # pylint: disable=too-many-locals
+        def cfactory(func, argtypes, restype):
+            # type: (str, List[Any], Any) -> None
             """ Factorize ctypes creations. """
-            self._cfactory(attr=attr, func=func, argtypes=argtypes, restype=restype)
+            self._cfactory(
+                attr=self.core, func=func, argtypes=argtypes, restype=restype
+            )
 
         uint32 = ctypes.c_uint32
         void = ctypes.c_void_p
@@ -117,7 +124,7 @@ def cfactory(attr=self.core, func=None, argtypes=None, restype=None):
 
     @property
     def monitors(self):
-        # type: () -> List[Dict[str, int]]
+        # type: () -> Monitors
         """ Get positions of monitors (see parent class). """
 
         if not self._monitors:
@@ -165,7 +172,7 @@ def monitors(self):
         return self._monitors
 
     def grab(self, monitor):
-        # type: (Dict[str, int]) -> ScreenShot
+        # type: (Monitor) -> ScreenShot
         """
         See :meth:`MSSMixin.grab <mss.base.MSSMixin.grab>` for full details.
         """

mss/exception.py

@@ -4,11 +4,16 @@
 Source: https://github.com/BoboTiG/python-mss
 """
 
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any, Dict  # noqa
+
 
 class ScreenShotError(Exception):
     """ Error handling class. """
 
     def __init__(self, message, details=None):
-        # type: (Dict[str, Any]) -> None
+        # type: (str, Dict[str, Any]) -> None
         super().__init__(message)
         self.details = details or {}

mss/factory.py

@@ -10,7 +10,6 @@
 
 
 def mss(**kwargs):
-    # type: (**str) -> MSS
     """ Factory returning a proper MSS class instance.
 
         It detects the plateform we are running on
@@ -25,11 +24,11 @@ def mss(**kwargs):
 
     operating_system = platform.system().lower()
     if operating_system == "darwin":
-        from .darwin import MSS
+        from .darwin import MSS  # type: ignore
     elif operating_system == "linux":
-        from .linux import MSS
+        from .linux import MSS  # type: ignore
     elif operating_system == "windows":
-        from .windows import MSS
+        from .windows import MSS  # type: ignore
     else:
         raise ScreenShotError(
             "System {!r} not (yet?) implemented.".format(operating_system)