Add mypy type checking and py.typed marker (#139)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: letmaik <530988+letmaik@users.noreply.github.com>
Co-authored-by: Maik Riechert <letmaik@outlook.com>

Author: Copilot

dev-requirements.txt

@@ -1,5 +1,6 @@
 # test dependencies
 pytest
+mypy
 # https://github.com/opencv/opencv-python/issues/291#issuecomment-841816850
 opencv-python; sys_platform != 'darwin'
 imageio

mypy.ini

@@ -0,0 +1,20 @@
+[mypy]
+# Minimum Python version that the codebase should be compatible with
+python_version = 3.10
+# Exclude test helper modules with complex setup patterns
+exclude = test/win-dshow-capture/
+
+# Test-specific native modules
+[mypy-pyvirtualcam_win_dshow_capture.*]
+ignore_missing_imports = True
+
+# Libraries without type stubs
+[mypy-cv2]
+ignore_missing_imports = True
+
+[mypy-imageio]
+ignore_missing_imports = True
+
+[mypy-pybind11]
+ignore_missing_imports = True
+

pyvirtualcam/camera.py

@@ -1,4 +1,4 @@
-from typing import Optional, Dict, Type
+from typing import Optional, Dict, Type, TYPE_CHECKING, Callable
 from abc import ABC, abstractmethod
 import platform
 import time
@@ -105,20 +105,24 @@ def register_backend(name: str, clazz):
     BACKENDS[name] = clazz
 
 if platform.system() == 'Windows':
-    from pyvirtualcam import _native_windows_obs, _native_windows_unity_capture
-    register_backend('obs', _native_windows_obs.Camera)
-    register_backend('unitycapture', _native_windows_unity_capture.Camera)
+    if not TYPE_CHECKING:
+        from pyvirtualcam import _native_windows_obs, _native_windows_unity_capture
+        register_backend('obs', _native_windows_obs.Camera)
+        register_backend('unitycapture', _native_windows_unity_capture.Camera)
 elif platform.system() == 'Darwin':
     # Darwin 22 is used on macOS 13
     if int(platform.release().split(".")[0]) >= 22:
-        from pyvirtualcam import _native_macos_obs_cmioextension
-        register_backend('obs', _native_macos_obs_cmioextension.Camera)
+        if not TYPE_CHECKING:
+            from pyvirtualcam import _native_macos_obs_cmioextension
+            register_backend('obs', _native_macos_obs_cmioextension.Camera)
     else:
-        from pyvirtualcam import _native_macos_obs_dal
-        register_backend('obs', _native_macos_obs_dal.Camera)
+        if not TYPE_CHECKING:
+            from pyvirtualcam import _native_macos_obs_dal
+            register_backend('obs', _native_macos_obs_dal.Camera)
 elif platform.system() == 'Linux':
-    from pyvirtualcam import _native_linux_v4l2loopback
-    register_backend('v4l2loopback', _native_linux_v4l2loopback.Camera)
+    if not TYPE_CHECKING:
+        from pyvirtualcam import _native_linux_v4l2loopback
+        register_backend('v4l2loopback', _native_linux_v4l2loopback.Camera)
 
 class PixelFormat(Enum):
     """ Pixel formats.
@@ -206,28 +210,29 @@ def __init__(self, width: int, height: int, fps: float, *,
             backends = [(backend, BACKENDS[backend])]
         else:
             backends = list(BACKENDS.items())
-        self._backend = None
+        backend_instance: Optional[Backend] = None
         errors = []
         for name, clazz in backends:
             try:
-                self._backend = clazz(
+                backend_instance = clazz(
                     width=width, height=height, fps=fps,
                     fourcc=encode_fourcc(fmt.value),
                     device=device,
                     **kw)
             except Exception as e:
                 errors.append(f"'{name}' backend: {e}")
             else:
-                self._backend_name = name
+                self._backend_name: str = name
                 break
-        if self._backend is None:
+        if backend_instance is None:
             raise RuntimeError('\n'.join(errors))
-
-        self._width = width
-        self._height = height
-        self._fps = fps
-        self._fmt = fmt
-        self._print_fps = print_fps
+        
+        self._backend: Backend = backend_instance
+        self._width: int = width
+        self._height: int = height
+        self._fps: float = fps
+        self._fmt: PixelFormat = fmt
+        self._print_fps: bool = print_fps
 
         frame_shape = FrameShapes[fmt](width, height)
         if isinstance(frame_shape, int):
@@ -239,20 +244,20 @@ def check_frame_shape(frame: np.ndarray):
                 if frame.shape != frame_shape:
                     raise ValueError(f"unexpected frame shape: {frame.shape} != {frame_shape}")
 
-        self._check_frame_shape = check_frame_shape
+        self._check_frame_shape: Callable[[np.ndarray], None] = check_frame_shape
 
-        self._fps_counter = FPSCounter(fps)
-        self._fps_last_printed = time.perf_counter()
-        self._frames_sent = 0
-        self._last_frame_t = None
-        self._extra_time_per_frame = 0
+        self._fps_counter: FPSCounter = FPSCounter(fps)
+        self._fps_last_printed: float = time.perf_counter()
+        self._frames_sent: int = 0
+        self._last_frame_t: float = time.perf_counter()
+        self._extra_time_per_frame: float = 0.0
+        self._closed: bool = False
 
     def __enter__(self):
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback) -> bool:
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
         self.close()
-        return False
 
     def __del__(self):
         self.close()
@@ -319,9 +324,9 @@ def close(self) -> None:
         This method is automatically called when using ``with`` or
         when this instance goes out of scope.
         """
-        if self._backend is not None:
+        if not self._closed:
             self._backend.close()
-            self._backend = None
+            self._closed = True
 
     def send(self, frame: np.ndarray) -> None:
         """Send a frame to the virtual camera device.

pyvirtualcam/py.typed

@@ -166,6 +166,7 @@ def build_extensions(self):
     ],
     ext_modules=ext_modules,
     packages = find_packages(),
+    package_data={'pyvirtualcam': ['py.typed']},
     setup_requires=['pybind11>=2.6.0'],
     install_requires=['numpy'],
     cmdclass={'build_ext': BuildExt},

setup.py

@@ -134,7 +134,7 @@ def check_native_fmt(cam):
         cam.send(np.zeros(cam.height * cam.width * 2, np.uint8))
 
 @pytest.mark.skipif(
-    os.environ.get('CI') and platform.system() == 'Darwin',
+    bool(os.environ.get('CI')) and platform.system() == 'Darwin',
     reason='disabled due to high fluctuations in CI, manually verified on MacBook Pro')
 def test_sleep_until_next_frame():
     target_fps = 20

test/test_camera.py

@@ -1,8 +1,7 @@
 import os
 import signal
-from typing import Union
+from typing import Union, Tuple
 import sys
-import signal
 import subprocess
 import json
 import traceback
@@ -30,12 +29,13 @@
 if platform.system() == 'Windows':
     import pyvirtualcam_win_dshow_capture as dshow
 
-    def capture_rgb(device: str, width: int, height: int):
+    def capture_rgb(device: Union[str, int], width: int, height: int) -> Tuple[np.ndarray, float]:
+        assert isinstance(device, str), "Windows requires device to be a string"
         rgb, timestamp_ms = dshow.capture(device, width, height)
         return rgb, timestamp_ms
 
 elif platform.system() in ['Linux', 'Darwin']:
-    def capture_rgb(device: Union[str, int], width: int, height: int):
+    def capture_rgb(device: Union[str, int], width: int, height: int) -> Tuple[np.ndarray, float]:
         print(f'Opening device {device} for capture')
         vc = cv2.VideoCapture(device)
         assert vc.isOpened()
@@ -272,7 +272,7 @@ def send_frames(backend: str, fmt: PixelFormat, info_path: Path, mode: str):
 
 def capture_frame(backend: str, fmt: PixelFormat, info_path: Path, mode: str):
     if platform.system() == 'Darwin':
-        device = 0
+        device: Union[str, int] = 0
     else:
         with open(info_path) as f:
             device = json.load(f)

test/test_capture.py

@@ -0,0 +1,20 @@
+"""Test mypy type checking on the source and test folders."""
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_mypy():
+    """Run mypy on the source and test folders."""
+    # Build absolute paths based on test file location
+    test_dir = Path(__file__).parent
+    repo_root = test_dir.parent
+    
+    result = subprocess.run(
+        [sys.executable, '-m', 'mypy', '--install-types', '--non-interactive', 
+         'pyvirtualcam/', 'test/'],
+        capture_output=True,
+        text=True,
+        cwd=str(repo_root)
+    )
+    assert result.returncode == 0, f"mypy failed:\n{result.stdout}\n{result.stderr}"

test/test_mypy.py

@@ -5,7 +5,7 @@
 import pyvirtualcam.util
 
 @pytest.mark.skipif(
-    os.environ.get('CI') and platform.system() == 'Darwin',
+    bool(os.environ.get('CI')) and platform.system() == 'Darwin',
     reason='disabled due to high fluctuations in CI, manually verified on MacBook Pro')
 def test_fps_counter():
     target_fps = 20

test/test_util.py

@@ -1,5 +1,6 @@
 # https://github.com/pybind/python_example/blob/master/setup.py
 
+from typing import Dict, List
 import glob
 from setuptools import setup, Extension, find_packages
 from setuptools.command.build_ext import build_ext
@@ -11,7 +12,7 @@ class get_pybind_include(object):
     until it is actually installed, so that the ``get_include()``
     method can be invoked. """
 
-    def __str__(self):
+    def __str__(self) -> str:
         import pybind11
         return pybind11.get_include()
 
@@ -71,7 +72,7 @@ class BuildExt(build_ext):
         'msvc': ['/EHsc'],
         'unix': [],
     }
-    l_opts = {
+    l_opts: Dict[str, List[str]] = {
         'msvc': [],
         'unix': [],
     }