Complete jack-client stub (#9530)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

stubs/JACK-Client/METADATA.toml

@@ -1,4 +1,6 @@
 version = "0.5.*"
+# Requires a version of numpy with a `py.typed` file
+requires = ["types-cffi", "numpy>=1.20"]
 
 [tool.stubtest]
 ignore_missing_stub = false

stubs/JACK-Client/jack/__init__.pyi

@@ -1,12 +1,38 @@
 import sys
 from _typeshed import Self
 from collections.abc import Callable, Generator, Iterable, Iterator, Sequence
-from typing import Any, overload
-from typing_extensions import Literal, TypeAlias
+from typing import Any, NoReturn, overload
+from typing_extensions import Literal
 
-_NDArray: TypeAlias = Any  # FIXME: no typings for numpy arrays
+import numpy
+from _cffi_backend import _CDataBase
+from numpy.typing import NDArray
 
-class _JackPositionT: ...
+# Aka jack_position_t
+# Actual type: _cffi_backend.__CDataOwn <cdata 'struct _jack_position *'>
+# This is not a real subclassing. Just ensuring type-checkers sees this type as compatible with _CDataBase
+# pyright has no error code for subclassing final
+class _JackPositionT(_CDataBase):  # type: ignore[misc]  # pyright: ignore
+    audio_frames_per_video_frame: float
+    bar: int
+    bar_start_tick: float
+    bbt_offset: int
+    beat: int
+    beat_type: float
+    beats_per_bar: float
+    beats_per_minute: float
+    frame: int
+    frame_rate: int
+    frame_time: float
+    next_time: float
+    padding: _CDataBase  # <cdata 'int32_t[7]'>
+    tick: int
+    ticks_per_beat: float
+    unique_1: int
+    unique_2: int
+    usecs: int
+    valid: int
+    video_offset: int
 
 class _CBufferType:
     @overload
@@ -100,9 +126,9 @@ class Client:
     @transport_frame.setter
     def transport_frame(self, frame: int) -> None: ...
     def transport_locate(self, frame: int) -> None: ...
-    def transport_query(self) -> tuple[TransportState, dict[str, Any]]: ...
+    def transport_query(self) -> tuple[TransportState, dict[str, Any]]: ...  # Anyof[int, float, _CDataBase]
     def transport_query_struct(self) -> tuple[TransportState, _JackPositionT]: ...
-    def transport_reposition_struct(self, position: _JackPositionT) -> None: ...  # TODO
+    def transport_reposition_struct(self, position: _JackPositionT) -> None: ...
     def set_sync_timeout(self, timeout: int) -> None: ...
     def set_freewheel(self, onoff: bool) -> None: ...
     def set_shutdown_callback(self, callback: Callable[[Status, str], object]) -> None: ...
@@ -149,7 +175,8 @@ class Client:
     def remove_all_properties(self) -> None: ...
 
 class Port:
-    def __init__(self, port_ptr: Any, client: Client) -> None: ...
+    # <cdata 'struct _jack_port *'>
+    def __init__(self, port_ptr: _CDataBase, client: Client) -> None: ...
     def __eq__(self, other: object) -> bool: ...
     def __ne__(self, other: object) -> bool: ...
     @property
@@ -196,12 +223,14 @@ class OwnPort(Port):
     def disconnect(self, other: str | Port | None = ...) -> None: ...
     def unregister(self) -> None: ...
     def get_buffer(self) -> _CBufferType: ...
-    def get_array(self) -> _NDArray: ...
+    def get_array(self) -> NDArray[numpy.float32]: ...
 
 class OwnMidiPort(MidiPort, OwnPort):
-    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
-    def get_buffer(self) -> _CBufferType: ...
-    def get_array(self) -> _NDArray: ...
+    def __init__(self, port_ptr: _CDataBase, client: Client) -> None: ...
+    # The implementation raises NotImplementedError, but this is not an abstract class.
+    # `get_buffer()` and `get_array()` are disabled for OwnMidiPort
+    def get_buffer(self) -> NoReturn: ...
+    def get_array(self) -> NoReturn: ...
     @property
     def max_event_size(self) -> int: ...
     @property
@@ -212,7 +241,7 @@ class OwnMidiPort(MidiPort, OwnPort):
     def reserve_midi_event(self, time: int, size: int) -> _CBufferType: ...
 
 class Ports:
-    def __init__(self, client: Client, porttype: Any, flag: Any) -> None: ...
+    def __init__(self, client: Client, porttype: str, flag: int) -> None: ...
     def __len__(self) -> int: ...
     def __getitem__(self, name: str) -> Port: ...
     def __iter__(self) -> Iterator[Port]: ...
@@ -278,7 +307,7 @@ class CallbackExit(Exception): ...
 def get_property(subject: int | str, key: str) -> tuple[bytes, str] | None: ...
 def get_properties(subject: int | str) -> dict[str, tuple[bytes, str]]: ...
 def get_all_properties() -> dict[str, dict[str, tuple[bytes, str]]]: ...
-def position2dict(pos: _JackPositionT) -> dict[str, Any]: ...
+def position2dict(pos: _JackPositionT) -> dict[str, Any]: ...  # Anyof[int, float, _CDataBase]
 def version() -> tuple[int, int, int, int]: ...
 def version_string() -> str: ...
 def client_name_size() -> int: ...