Move type hints to stubs directory

BoboTiG · BoboTiG · commit 977f48638367 · 2016-10-17T18:14:04.000+02:00
diff --git a/.travis.yml b/.travis.yml
@@ -23,7 +23,6 @@ install:
 script:
   - py.test --display=":42.0"
   - flake8 mss
-#  - mypy --check-untyped-defs --warn-incomplete-stub -m mss
 
 after_script:
   - xpra stop :42
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -33,13 +33,13 @@ Screenshot of the monitor 1 with callback::
 
 
     def on_exists(fname):
+        # type: (str) -> None
         ''' Callback example when we try to overwrite an existing screenshot. '''
 
         if isfile(fname):
             newfile = fname + '.old'
             print('{0} -> {1}'.format(fname, newfile))
             rename(fname, newfile)
-        return True
 
 
     for filename in sct.save(mon=1, callback=on_exists):
diff --git a/examples/callback.py b/examples/callback.py
@@ -7,13 +7,16 @@
 from os import rename
 from os.path import isfile
 
-from mss import mss, ScreenshotError
+from mss.exception import ScreenshotError
+from mss.factory import mss
 
 
 def main():
+    # type: () -> int
     ''' Usage example. '''
 
     def on_exists(fname):
+        # type: (str) -> None
         ''' Callback example when we try to overwrite an existing
             screenshot.
         '''
@@ -22,26 +25,25 @@ def on_exists(fname):
             newfile = fname + '.old'
             print('{0} -> {1}'.format(fname, newfile))
             rename(fname, newfile)
-        return True
 
     try:
-        with mss() as screenshotter:
+        with mss() as sct:
             # For MacOS X only
-            # screenshotter.max_displays = 32
+            # sct.max_displays = 32
 
             print('One screenshot per monitor')
-            for filename in screenshotter.save():
+            for filename in sct.save():
                 print(filename)
 
             print("\nScreenshot of the monitor 1")
-            print(next(screenshotter.save(mon=1, output='monitor-%d.png')))
+            print(next(sct.save(mon=1, output='monitor-%d.png')))
 
             print("\nA screenshot to grab them all")
-            print(next(screenshotter.save(mon=-1, output='fullscreen.png')))
+            print(next(sct.save(mon=-1, output='fullscreen.png')))
 
             print("\nScreenshot of the monitor 1, with callback")
-            print(next(screenshotter.save(mon=1, output='mon-%d.png',
-                                          callback=on_exists)))
+            print(next(sct.save(mon=1, output='mon-%d.png',
+                                callback=on_exists)))
 
             return 0
     except ScreenshotError as ex:
diff --git a/examples/linux-display_keyword.py b/examples/linux-display_keyword.py
@@ -4,20 +4,21 @@
     Source: https://github.com/BoboTiG/python-mss
 '''
 
-from mss import ScreenshotError
+from mss.exception import ScreenshotError
 from mss.linux import MSS
 
 
 def main():
+    # type: () -> int
     ''' Usage example with a specific display. '''
 
     display = ':0.0'
     print('Screenshot of display "{0}"'.format(display))
 
     try:
-        with MSS(display=display) as screenshotter:
+        with MSS(display=display) as sct:
             output = 'monitor{0}-%d.png'.format(display)
-            for filename in screenshotter.save(output=output):
+            for filename in sct.save(output=output):
                 print(filename)
 
             return 0
diff --git a/examples/pil.py b/examples/pil.py
@@ -4,28 +4,30 @@
     Source: https://github.com/BoboTiG/python-mss
 '''
 
-from mss import mss, ScreenshotError
+from mss.exception import ScreenshotError
+from mss.factory import mss
 from PIL import Image
 
 
 def main():
+    # type: () -> int
     ''' PIL example using frombytes(). '''
 
     try:
-        with mss() as screenshotter:
+        with mss() as sct:
             # We retrieve monitors informations:
-            monitors = screenshotter.enum_display_monitors()
+            monitors = sct.enum_display_monitors()
 
             # Get rid of the first, as it represents the "All in One" monitor:
             for num, monitor in enumerate(monitors[1:], 1):
                 # Get raw pixels from the screen.
                 # This method will store screen size into `width` and `height`
                 # and raw pixels into `image`.
-                screenshotter.get_pixels(monitor)
+                sct.get_pixels(monitor)
 
                 # Create an Image:
-                size = (screenshotter.width, screenshotter.height)
-                img = Image.frombytes('RGB', size, screenshotter.image)
+                size = (sct.width, sct.height)
+                img = Image.frombytes('RGB', size, sct.image)
 
                 # And save it!
                 output = 'monitor-{0}.png'.format(num)
diff --git a/mss/base.pyi b/mss/base.pyi
diff --git a/mss/factory.py b/mss/factory.py
@@ -9,7 +9,7 @@
 from .exception import ScreenshotError
 
 
-def mss(*args, **kwargs):
+def mss(**kwargs):
     ''' Factory returning a proper MSS class instance.
 
         It detects the plateform we are running on
@@ -31,4 +31,4 @@ def mss(*args, **kwargs):
         err = 'System "{0}" not implemented.'.format(operating_system)
         raise ScreenshotError(err)
 
-    return MSS(*args, **kwargs)
+    return MSS(**kwargs)
diff --git a/mss/factory.pyi b/mss/factory.pyi
diff --git a/mss/windows.pyi b/mss/windows.pyi
diff --git a/stubs/mss/__init__.pyi b/stubs/mss/__init__.pyi
@@ -0,0 +1 @@
+# Stubs for mss
diff --git a/stubs/mss/base.pyi b/stubs/mss/base.pyi
@@ -0,0 +1,21 @@
+from typing import Callable, Dict, Iterator, List, Optional
+from types import TracebackType
+
+
+Monitor = Dict[str, int]
+Monitors = List[Monitor]
+
+
+class MSSBase(object):
+    monitors = ...  # type: Monitors
+    image = ...  # type: bytes
+    width = ...  # type: int
+    height = ...  # type: int
+
+    def __enter__(self) -> MSSBase: ...
+    def __exit__(self, exc_type: Optional[type], exc_value: Optional[Exception], traceback: Optional[TracebackType]) -> None: ...
+    def bgra_to_rgb(self, raw: bytearray) -> bytes: ...
+    def enum_display_monitors(self, force: bool=False) -> Monitors: ...
+    def get_pixels(self, monitor: Monitor) -> bytes: ...
+    def save(self, mon: int=0, output: str='monitor-%d.png', callback: Callable[[str], None]=None) -> Iterator[str]: ...
+    def to_png(self, data: bytes, output: str) -> None: ...
diff --git a/stubs/mss/darwin.pyi b/stubs/mss/darwin.pyi
@@ -2,7 +2,7 @@ from typing import Any
 from .base import MSSBase
 
 
-def cgfloat() -> Any: ...
+def cgfloat() -> Any: ...  # reveal_type(ctypes.c_double or ctypes.c_float) == Any
 def get_infinity(maxi: bool=False) -> float: ...
 
 
diff --git a/stubs/mss/factory.pyi b/stubs/mss/factory.pyi
@@ -0,0 +1,4 @@
+from .base import MSSBase
+
+
+def mss(**kwargs: str) -> MSSBase: ...
diff --git a/stubs/mss/linux.pyi b/stubs/mss/linux.pyi
diff --git a/stubs/mss/windows.pyi b/stubs/mss/windows.pyi
@@ -0,0 +1,5 @@
+from typing import Any, Callable
+
+
+def set_argtypes(callback: Callable[[int, Any, Any, Any, float], int]) -> None: ...
+def set_restypes() -> None: ...
diff --git a/tests/check-types.sh b/tests/check-types.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+
+export MYPYPATH="$(pwd)/stubs"
+
+~/.local/bin/mypy \
+    --silent-imports \
+    --disallow-untyped-calls \
+    --disallow-untyped-defs \
+    --check-untyped-defs \
+    --warn-incomplete-stub \
+    --warn-redundant-casts \
+    --warn-unused-ignores \
+    --strict-optional \
+    --scripts-are-modules \
+    --show-column-numbers \
+    "$@"
