Merge pull request #363 from justjanne/type-hints

Type Checking

Author: justjanne

.github/workflows/test.yaml

@@ -1,4 +1,4 @@
-name: Test
+name: Build
 
 on: [push]
 
@@ -18,8 +18,13 @@ jobs:
         with:
           python-version-file: "pyproject.toml"
       - name: Install the project
-        run: uv sync --dev
-      - name: Run tests
+        run: |-
+          uv venv --system-site-packages
+          uv pip install pygobject-stubs --config-settings=config=Gtk3,Gdk3
+          uv sync --dev
+      - name: Typechecking
+        run: uv run mypy -p voctocore -p voctogui
+      - name: Tests
         run: uv run pytest
   docker:
     runs-on: ubuntu-latest

README.md

@@ -10,14 +10,15 @@ those.
 
 ```bash
 uv venv --system-site-packages
-uv sync
-uv pip install pygobject-stubs --config-settings=config=Gtk3
+uv pip install pygobject-stubs --config-settings=config=Gtk3,Gdk3
+uv sync --dev
 ```
 
 ## Tests
 
 ```bash
 uv run pytest
+uv run mypy -p voctocore -p voctogui
 ```
 
 ## Current Documentation

pyproject.toml

@@ -6,6 +6,7 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "scipy>=1.15.2",
+    "scipy-stubs>=1.15.2.1",
     "sdnotify>=0.3.2",
 ]
 
@@ -14,11 +15,20 @@ dev = [
     "mock>=5.2.0",
     "pytest>=8.3.5",
     "pygobject-stubs>=2.13.0",
+    "mypy>=1.15.0",
 ]
 
 [tool.uv]
 python-preference = "only-system"
 
+[tool.mypy]
+mypy_path = "python_stubs"
+exclude = "tests|venv"
+
+[[tool.mypy.overrides]]
+module = ["cairo.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = [
     "voctocore/tests",

python_stubs/gi/repository/GstController.pyi

@@ -0,0 +1,126 @@
+import enum
+
+from gi.repository import Gst, GLib
+
+
+# https://gstreamer.freedesktop.org/documentation/controller/gsttimedvaluecontrolsource.html?gi-language=python
+
+class ControlPoint:
+    timestamp: int = ...
+    value: float = ...
+
+    def copy(self) -> ControlPoint: ...
+    def free(self) -> None: ...
+
+class TimedValueControlSource(Gst.ControlSource):
+    class Props(Gst.ControlSource.Props): ...
+
+    parent: Gst.ControlSource = ...
+    props: Props = ...
+
+    lock: GLib.Mutex = ...
+    values: list[Gst.TimedValue] = ...
+    nvalues: int = ...
+    valid_cache: bool = ...
+
+    def find_control_point_iter(self, timestamp: int) -> GLib.SequenceIter: ...
+    def get_all(self) -> list[Gst.TimedValue]: ...
+    def get_count(self) -> int: ...
+    def set(self, timestamp: int, value: float) -> bool: ...
+    def set_from_list(self, timedvalues: list[Gst.TimedValue]) -> bool: ...
+    def unset(self, timestamp: int) -> bool: ...
+    def unset_all(self) -> bool: ...
+
+def timed_value_control_invalidate_cache(source: TimedValueControlSource) -> None: ...
+
+# https://gstreamer.freedesktop.org/documentation/controller/gstinterpolationcontrolsource.html?gi-language=python
+
+class InterpolationControlSource(TimedValueControlSource):
+    class Props(TimedValueControlSource.Props):
+        mode: InterpolationMode
+
+    parent: TimedValueControlSource = ...
+    props: Props = ...
+
+    @staticmethod
+    def new() -> InterpolationControlSource: ...
+
+class InterpolationMode(enum.IntEnum):
+    NONE = 0
+    LINEAR = 1
+    CUBIC = 2
+    CUBIC_MONOTONIC = 3
+
+# https://gstreamer.freedesktop.org/documentation/controller/gsttriggercontrolsource.html?gi-language=python
+
+class TriggerControlSource(TimedValueControlSource):
+    class Props(TimedValueControlSource.Props):
+        tolerance: int
+
+    parent: TimedValueControlSource = ...
+    props: Props = ...
+
+    @staticmethod
+    def new() -> TriggerControlSource: ...
+
+# https://gstreamer.freedesktop.org/documentation/controller/gstlfocontrolsource.html?gi-language=python
+
+class LFOControlSource(Gst.ControlSource):
+    class Props(Gst.ControlSource.Props):
+        amplitude: float
+        frequency: float
+        offset: float
+        timeshift: int
+        waveform: LFOWaveform
+
+    parent: Gst.ControlSource = ...
+    props: Props = ...
+
+    @staticmethod
+    def new() -> LFOControlSource: ...
+
+class LFOWaveform(enum.IntEnum):
+    SINE = 0
+    SQUARE = 1
+    SAW = 2
+    REVERSE_SAW = 3
+    TRIANGLE = 4
+
+# https://gstreamer.freedesktop.org/documentation/controller/gstargbcontrolbinding.html?gi-language=python
+
+class ARGBControlBinding(Gst.ControlBinding):
+    class Props(Gst.ControlBinding.Props):
+        control_source_a: Gst.ControlSource
+        control_source_r: Gst.ControlSource
+        control_source_g: Gst.ControlSource
+        control_source_b: Gst.ControlSource
+
+    parent: Gst.ControlBinding = ...
+    props: Props = ...
+
+    @staticmethod
+    def new(object: Gst.Object, property_name: str, cs_a: Gst.ControlSource, cs_r: Gst.ControlSource, cs_g: Gst.ControlSource, cs_b: Gst.ControlSource) -> ARGBControlBinding: ...
+
+# https://gstreamer.freedesktop.org/documentation/controller/gstdirectcontrolbinding.html?gi-language=python
+
+class DirectControlBinding(Gst.ControlBinding):
+    class Props(Gst.ControlBinding.Props):
+        absolute: bool
+        control_source: Gst.ControlSource
+
+    parent: Gst.ControlBinding = ...
+    props: Props = ...
+
+    @staticmethod
+    def new(object: Gst.Object, property_name: str, cs: Gst.ControlSource) -> DirectControlBinding: ...
+
+    @staticmethod
+    def new_absolute(object: Gst.Object, property_name: str, cs: Gst.ControlSource) -> DirectControlBinding: ...
+
+# https://gstreamer.freedesktop.org/documentation/controller/gstproxycontrolbinding.html?gi-language=python
+
+class ProxyControlBinding(Gst.ControlBinding):
+    @staticmethod
+    def new(object: Gst.Object, property_name: str, ref_object: Gst.Object, ref_property_name: str) -> ProxyControlBinding: ...
+
+

python_stubs/gi/repository/GstNet.pyi

@@ -0,0 +1,118 @@
+from typing import Any, Optional, Callable
+
+from gi.repository import Gst, GObject, Gio
+
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnetaddressmeta.html?gi-language=python
+
+class NetAddressMeta(Gst.Meta):
+    meta: Gst.Meta
+    addr: Gio.SocketAddress
+
+def net_address_meta_get_info() -> Gst.MetaInfo: ...
+def buffer_add_net_address_meta(buffer: Gst.Buffer, addr:  Gio.SocketAddress) -> NetAddressMeta: ...
+def buffer_get_net_address_meta(buffer: Gst.Buffer) -> NetAddressMeta: ...
+def net_address_meta_api_get_type() -> GObject.GType: ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnetclientclock.html?gi-language=python
+
+class NetClientClock(Gst.SystemClock):
+    class Props(Gst.SystemClock.Props):
+        address: str
+        base_time: int
+        bus: Gst.Bus
+        internal_clock: Gst.Clock
+        minimum_update_interval: int
+        port: int
+        qos_dscp: int
+        round_trip_limit: int
+
+    props: Props = ...
+
+    clock: Gst.SystemClock = ...
+
+    @staticmethod
+    def new(name: str, remote_address: str, remote_port: int, base_time: int) -> 'NetClientClock': ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnetcontrolmessagemeta.html?gi-language=python
+
+class NetControlMessageMeta(Gst.Meta):
+    meta: Gst.Meta
+    message: Gio.SocketControlMessage
+
+def net_control_message_meta_get_info() -> Gst.MetaInfo: ...
+def buffer_add_net_control_message_meta(buffer: Gst.Buffer, message: Gio.SocketControlMessage) -> NetControlMessageMeta: ...
+def net_control_message_meta_api_get_type() -> GObject.GType: ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnettimepacket.html?gi-language=python
+
+NET_TIME_PACKET_SIZE = 16
+
+class NetTimePacket:
+    local_time: int = ...
+    remote_time: int = ...
+
+    @staticmethod
+    def new(buffer: list[int]) -> NetTimePacket: ...
+
+    def copy(self) -> NetTimePacket: ...
+    def free(self) -> None: ...
+    def send(self, socket: Gio.Socket, dest_address: Gio.SocketAddress) -> bool: ...
+    def serialize(self) -> list[int]: ...
+
+def net_time_packet_receive(socket: Gio.Socket) -> tuple[NetTimePacket, Gio.SocketAddress]: ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnettimeprovider.html?gi-language=python
+
+class NetTimeProvider(Gst.Object):
+    class Props(Gst.Object.Props):
+        active: bool
+        address: str
+        clock: Gst.Clock
+        port: int
+        qos_dscp: int
+
+    props: Props = ...
+
+    @staticmethod
+    def new(clock: Gst.Clock, address: str, port: int) -> 'NetTimeProvider': ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnetclientclock.html?gi-language=python#GstNtpClock
+
+class NtpClock(NetClientClock):
+    @staticmethod
+    def new(name: str, remote_address: str, remote_port: int, base_time: int) -> 'NtpClock': ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstptpclock.html?gi-language=python
+
+PTP_CLOCK_ID_NONE: int = ...
+PTP_STATISTICS_BEST_MASTER_CLOCK_SELECTED: str = "GstPtpStatisticsBestMasterClockSelected"
+PTP_STATISTICS_NEW_DOMAIN_FOUND: str = "GstPtpStatisticsNewDomainFound"
+PTP_STATISTICS_PATH_DELAY_MEASURED: str = "GstPtpStatisticsPathDelayMeasured"
+PTP_STATISTICS_TIME_UPDATED: str = "GstPtpStatisticsTimeUpdated"
+
+class PtpClock(Gst.SystemClock):
+    class Props(Gst.SystemClock.Props):
+        domain: int
+        grandmaster_clock_id: int
+        internal_clock: Gst.Clock
+        master_clock_id: int
+
+    props: Props = ...
+
+    @staticmethod
+    def new(name: str, domain: int) -> 'PtpClock': ...
+
+def ptp_deinit() -> None: ...
+def ptp_init(clock_id: int, interfaces: list[str]) -> bool: ...
+def ptp_init_full(config: Gst.Structure) -> bool: ...
+def ptp_is_initialized() -> bool: ...
+def ptp_is_supported() -> bool: ...
+
+PtpStatisticsCallback = Callable[[int, Gst.Structure, Any], bool]
+def ptp_statistics_callback_add(callback: Optional[PtpStatisticsCallback] = None, *user_data: Any) -> int: ...
+def ptp_statistics_callback_remove(id: int) -> None: ...
+
+# https://gstreamer.freedesktop.org/documentation/net/gstnetutils.html?gi-language=python
+
+def net_utils_set_socket_tos(socket: Gio.Socket, qos_dscp: int) -> bool: ...

python_stubs/gi/repository/GstVideo.pyi

@@ -0,0 +1,20 @@
+# https://gstreamer.freedesktop.org/documentation/video/gstvideo.html?gi-language=python
+
+
+class GstVideoAlignment:
+    padding_top: int
+    padding_bottom: int
+    padding_left: int
+    padding_right: int
+    stride_align: list[int]
+
+    def reset(self) -> None: ...
+
+def video_calculate_display_ratio(video_width: int, video_height: int, video_par_n: int, video_par_d: int, display_par_n: int, display_par_d: int) -> tuple[bool, int, int]: ...
+def video_guess_framerate(duration: int) -> tuple[bool, int, int]: ...
+def video_is_common_aspect_ratio(width: int, height: int, par_n: int, par_d: int) -> bool: ...
+
+GST_META_TAG_VIDEO_COLORSPACE_STR = "colorspace"
+GST_META_TAG_VIDEO_ORIENTATION_STR = "orientation"
+GST_META_TAG_VIDEO_SIZE_STR = "size"
+GST_META_TAG_VIDEO_STR = "video"

python_stubs/sdnotify.pyi

@@ -0,0 +1,6 @@
+from typing import Protocol
+
+
+class SystemdNotifier(Protocol):
+    def notify(self, state: str) -> None:
+        pass