Add mypy type checking (gorakhargosh#908)

* Add mypy as a tox test environment

* Fix all of the issues reported by mypy

* Update platform-specific Observer imports so mypy understands them

This allows mypy to perform platform-specific type-checking,
which fixes type-checking of the example code in `README.rst`.

Closes gorakhargosh#840

* Add a changelog entry

* Add mypy as a CI environment

* Resolve an error with mypy 1.1.1

Author: kurtmckee

.github/workflows/tests.yml

@@ -28,6 +28,8 @@ jobs:
       - name: Run flake8
         run: |
           tox -e flake8
+      - name: Run mypy
+        run: tox -e mypy
 
   tests:
     name: Run tests for ${{ matrix.os }} for ${{ matrix.python }}

changelog.rst

@@ -8,8 +8,8 @@ Changelog
 
 2023-xx-xx • `full history <https://github.com/gorakhargosh/watchdog/compare/v2.3.1...HEAD>`__
 
-- 
-- Thanks to our beloved contributors: @
+- [testing] watchdog is now PEP 561 compatible and is tested by mypy.
+- Thanks to our beloved contributors: @kurtmckee
 
 2.3.1
 ~~~~~

requirements-tests.txt

@@ -5,3 +5,6 @@ pytest
 pytest-cov
 pytest-timeout
 sphinx
+# mypy testing
+mypy
+types-PyYAML

src/watchdog/events.py

@@ -114,7 +114,7 @@ class FileSystemEvent:
     can be used as keys in dictionaries or be added to sets.
     """
 
-    event_type = None
+    event_type = ""
     """The type of the event as a string."""
 
     is_directory = False

src/watchdog/observers/__init__.py

@@ -50,33 +50,38 @@
 
 """
 
+import sys
 import warnings
-from watchdog.utils import platform
+from typing import Type
+
 from watchdog.utils import UnsupportedLibc
+from .api import BaseObserver
+
+Observer: Type[BaseObserver]
 
-if platform.is_linux():
+
+if sys.platform.startswith("linux"):
     try:
         from .inotify import InotifyObserver as Observer
     except UnsupportedLibc:
         from .polling import PollingObserver as Observer
 
-elif platform.is_darwin():
+elif sys.platform.startswith("darwin"):
     try:
         from .fsevents import FSEventsObserver as Observer
     except Exception:
         try:
-            from .kqueue import KqueueObserver as Observer
-
+            from .kqueue import KqueueObserver as Observer  # type: ignore[attr-defined,no-redef]
             warnings.warn("Failed to import fsevents. Fall back to kqueue")
         except Exception:
             from .polling import PollingObserver as Observer
 
             warnings.warn("Failed to import fsevents and kqueue. Fall back to polling.")
 
-elif platform.is_bsd():
-    from .kqueue import KqueueObserver as Observer
+elif sys.platform in ("dragonfly", "freebsd", "netbsd", "openbsd", "bsd"):
+    from .kqueue import KqueueObserver as Observer  # type: ignore[attr-defined,no-redef]
 
-elif platform.is_windows():
+elif sys.platform.startswith("win"):
     try:
         from .read_directory_changes import WindowsApiObserver as Observer
     except Exception:

src/watchdog/observers/fsevents.py

@@ -26,7 +26,7 @@
 import os
 import threading
 import unicodedata
-import _watchdog_fsevents as _fsevents
+import _watchdog_fsevents as _fsevents  # type: ignore
 
 from watchdog.events import (
     FileDeletedEvent,

src/watchdog/observers/fsevents2.py

@@ -43,8 +43,8 @@
 )
 
 # pyobjc
-import AppKit
-from FSEvents import (
+import AppKit  # type: ignore
+from FSEvents import (  # type: ignore
     FSEventStreamCreate,
     CFRunLoopGetCurrent,
     FSEventStreamScheduleWithRunLoop,

src/watchdog/observers/kqueue.py

@@ -13,6 +13,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# The `select` module varies between platforms.
+# mypy may complain about missing module attributes
+# depending on which platform it's running on.
+# The comment below disables mypy's attribute check.
+#
+# mypy: disable-error-code=attr-defined
+#
+
 """
 :module: watchdog.observers.kqueue
 :synopsis: ``kqueue(2)`` based emitter implementation.

src/watchdog/observers/winapi.py

@@ -119,11 +119,11 @@ def _errcheck_dword(value, func, args):
     return args
 
 
-kernel32 = ctypes.WinDLL("kernel32")
+kernel32 = ctypes.WinDLL("kernel32")  # type: ignore[attr-defined]
 
 ReadDirectoryChangesW = kernel32.ReadDirectoryChangesW
 ReadDirectoryChangesW.restype = ctypes.wintypes.BOOL
-ReadDirectoryChangesW.errcheck = _errcheck_bool
+ReadDirectoryChangesW.errcheck = _errcheck_bool  # type: ignore
 ReadDirectoryChangesW.argtypes = (
     ctypes.wintypes.HANDLE,  # hDirectory
     LPVOID,  # lpBuffer
@@ -137,7 +137,7 @@ def _errcheck_dword(value, func, args):
 
 CreateFileW = kernel32.CreateFileW
 CreateFileW.restype = ctypes.wintypes.HANDLE
-CreateFileW.errcheck = _errcheck_handle
+CreateFileW.errcheck = _errcheck_handle  # type: ignore
 CreateFileW.argtypes = (
     ctypes.wintypes.LPCWSTR,  # lpFileName
     ctypes.wintypes.DWORD,  # dwDesiredAccess
@@ -154,15 +154,15 @@ def _errcheck_dword(value, func, args):
 
 CancelIoEx = kernel32.CancelIoEx
 CancelIoEx.restype = ctypes.wintypes.BOOL
-CancelIoEx.errcheck = _errcheck_bool
+CancelIoEx.errcheck = _errcheck_bool  # type: ignore
 CancelIoEx.argtypes = (
     ctypes.wintypes.HANDLE,  # hObject
     ctypes.POINTER(OVERLAPPED),  # lpOverlapped
 )
 
 CreateEvent = kernel32.CreateEventW
 CreateEvent.restype = ctypes.wintypes.HANDLE
-CreateEvent.errcheck = _errcheck_handle
+CreateEvent.errcheck = _errcheck_handle  # type: ignore
 CreateEvent.argtypes = (
     LPVOID,  # lpEventAttributes
     ctypes.wintypes.BOOL,  # bManualReset
@@ -172,12 +172,12 @@ def _errcheck_dword(value, func, args):
 
 SetEvent = kernel32.SetEvent
 SetEvent.restype = ctypes.wintypes.BOOL
-SetEvent.errcheck = _errcheck_bool
+SetEvent.errcheck = _errcheck_bool  # type: ignore
 SetEvent.argtypes = (ctypes.wintypes.HANDLE,)  # hEvent
 
 WaitForSingleObjectEx = kernel32.WaitForSingleObjectEx
 WaitForSingleObjectEx.restype = ctypes.wintypes.DWORD
-WaitForSingleObjectEx.errcheck = _errcheck_dword
+WaitForSingleObjectEx.errcheck = _errcheck_dword  # type: ignore
 WaitForSingleObjectEx.argtypes = (
     ctypes.wintypes.HANDLE,  # hObject
     ctypes.wintypes.DWORD,  # dwMilliseconds
@@ -186,7 +186,7 @@ def _errcheck_dword(value, func, args):
 
 CreateIoCompletionPort = kernel32.CreateIoCompletionPort
 CreateIoCompletionPort.restype = ctypes.wintypes.HANDLE
-CreateIoCompletionPort.errcheck = _errcheck_handle
+CreateIoCompletionPort.errcheck = _errcheck_handle  # type: ignore
 CreateIoCompletionPort.argtypes = (
     ctypes.wintypes.HANDLE,  # FileHandle
     ctypes.wintypes.HANDLE,  # ExistingCompletionPort
@@ -196,7 +196,7 @@ def _errcheck_dword(value, func, args):
 
 GetQueuedCompletionStatus = kernel32.GetQueuedCompletionStatus
 GetQueuedCompletionStatus.restype = ctypes.wintypes.BOOL
-GetQueuedCompletionStatus.errcheck = _errcheck_bool
+GetQueuedCompletionStatus.errcheck = _errcheck_bool  # type: ignore
 GetQueuedCompletionStatus.argtypes = (
     ctypes.wintypes.HANDLE,  # CompletionPort
     LPVOID,  # lpNumberOfBytesTransferred
@@ -207,7 +207,7 @@ def _errcheck_dword(value, func, args):
 
 PostQueuedCompletionStatus = kernel32.PostQueuedCompletionStatus
 PostQueuedCompletionStatus.restype = ctypes.wintypes.BOOL
-PostQueuedCompletionStatus.errcheck = _errcheck_bool
+PostQueuedCompletionStatus.errcheck = _errcheck_bool  # type: ignore
 PostQueuedCompletionStatus.argtypes = (
     ctypes.wintypes.HANDLE,  # CompletionPort
     ctypes.wintypes.DWORD,  # lpNumberOfBytesTransferred
@@ -218,7 +218,7 @@ def _errcheck_dword(value, func, args):
 
 GetFinalPathNameByHandleW = kernel32.GetFinalPathNameByHandleW
 GetFinalPathNameByHandleW.restype = ctypes.wintypes.DWORD
-GetFinalPathNameByHandleW.errcheck = _errcheck_dword
+GetFinalPathNameByHandleW.errcheck = _errcheck_dword  # type: ignore
 GetFinalPathNameByHandleW.argtypes = (
     ctypes.wintypes.HANDLE,  # hFile
     ctypes.wintypes.LPWSTR,  # lpszFilePath

tests/test_emitter.py

@@ -19,6 +19,7 @@
 import logging
 from functools import partial
 from queue import Queue, Empty
+from typing import Type
 
 from .shell import mkfile, mkdir, touch, mv, rm
 from watchdog.utils import platform
@@ -34,7 +35,9 @@
     FileClosedEvent,
     FileOpenedEvent,
 )
-from watchdog.observers.api import ObservedWatch
+from watchdog.observers.api import EventEmitter, ObservedWatch
+
+Emitter: Type[EventEmitter]
 
 if platform.is_linux():
     from watchdog.observers.inotify import (
@@ -46,7 +49,9 @@
 elif platform.is_windows():
     from watchdog.observers.read_directory_changes import WindowsApiEmitter as Emitter
 elif platform.is_bsd():
-    from watchdog.observers.kqueue import KqueueEmitter as Emitter
+    from watchdog.observers.kqueue import (  # type: ignore[attr-defined,no-redef]
+        KqueueEmitter as Emitter
+    )
 
 logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger(__name__)

tests/test_fsevents.py

@@ -15,7 +15,7 @@
 from time import sleep
 from unittest.mock import patch
 
-import _watchdog_fsevents as _fsevents
+import _watchdog_fsevents as _fsevents  # type: ignore
 from watchdog.events import FileSystemEventHandler
 from watchdog.observers import Observer
 from watchdog.observers.api import ObservedWatch

tests/test_skip_repeats_queue.py

@@ -103,7 +103,7 @@ def test_consecutives_allowed_across_empties():
 @cpython_only
 def test_eventlet_monkey_patching():
     try:
-        import eventlet
+        import eventlet  # type: ignore
     except Exception:
         pytest.skip("eventlet not installed")
 

tools/dump_fsevents_constants.py

@@ -3,7 +3,7 @@
 import sys
 from io import StringIO
 
-import FSEvents
+import FSEvents  # type: ignore
 
 header = """ File generated by watchdog/scripts/dump_mac_constants.py
 

tox.ini

@@ -1,5 +1,8 @@
 [tox]
-envlist = py{311,310,39,38,37,36,py3}, docs
+envlist =
+    py{311,310,39,38,37,36,py3}
+    docs
+    mypy
 skip_missing_interpreters = True
 
 [testenv]
@@ -28,3 +31,10 @@ extras =
     watchmedo
 commands =
     sphinx-build -aEWb html docs/source docs/build/html
+
+[testenv:mypy]
+usedevelop = true
+deps =
+    -r requirements-tests.txt
+commands =
+    mypy tools src tests