Add interfaces for extension authoring

.github/workflows/release.yaml

@@ -19,7 +19,7 @@ jobs:
     - name: build
       shell: bash
       run: |
-        python -m pip install --upgrade wheel setuptools build unasync tokenize-rt
+        python -m pip install --upgrade wheel setuptools build
         python -m build
     - name: Release PyPI
       shell: bash

.github/workflows/test.yaml

@@ -21,16 +21,28 @@ jobs:
           python -m pip install -r requirements-dev.txt
           python -m pip install .
           python -m pip install tox
-          python -m pip install ahk-binary
+          python -m pip install "ahk-binary==2023.9.0"
       - name: Test with coverage/pytest
-        timeout-minutes: 5
+        timeout-minutes: 10
         env:
           PYTHONUNBUFFERED: "1"
         run: |
           tox -e py
       - name: Coveralls
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_PARALLEL: "true"
+          COVERALLS_SERVICE_JOB_ID: ${{ github.run_id }}
         run: |
           pip install --upgrade coveralls
           coveralls --service=github
+  finish:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: finish coveralls
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          pip install --upgrade coveralls
+          coveralls --service=github --finish

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
     files: ^(ahk/daemon\.ahk|ahk/_constants\.py)
 
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     -   id: mixed-line-ending
         args: ["-f", "lf"]
@@ -31,7 +31,7 @@ repos:
     -   id: trailing-whitespace
     -   id: double-quote-string-fixer
 -   repo: https://github.com/psf/black
-    rev: '23.9.1'
+    rev: '23.11.0'
     hooks:
     -   id: black
         args:
@@ -40,12 +40,12 @@ repos:
             - "120"
         exclude: ^(ahk/_sync/.*\.py)
 -   repo: https://github.com/asottile/reorder-python-imports
-    rev: v3.10.0
+    rev: v3.12.0
     hooks:
     -   id: reorder-python-imports
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.5.1'
+    rev: 'v1.7.0'
     hooks:
     -   id: mypy
         args:

_set_constants.py

@@ -8,6 +8,12 @@
 with open('ahk/templates/hotkeys.ahk') as hotkeyfile:
     hotkey_script = hotkeyfile.read()
 
+with open('ahk/templates/daemon-v2.ahk') as fv2:
+    daemon_script_v2 = fv2.read()
+
+with open('ahk/templates/hotkeys-v2.ahk') as hotkeyfilev2:
+    hotkey_script_v2 = hotkeyfilev2.read()
+
 GIT_EXECUTABLE = shutil.which('git')
 
 if not GIT_EXECUTABLE:
@@ -22,6 +28,12 @@
 
 HOTKEYS_SCRIPT_TEMPLATE = r"""{hotkey_script}
 """
+
+DAEMON_SCRIPT_V2_TEMPLATE = r"""{daemon_script_v2}
+"""
+
+HOTKEYS_SCRIPT_V2_TEMPLATE = r"""{hotkey_script_v2}
+"""
 '''
 
 with open('ahk/_constants.py', encoding='utf-8') as f:

ahk/__init__.py

@@ -25,7 +25,7 @@
     'MsgBoxModality',
 ]
 
-_global_instance: Optional[AHK] = None
+_global_instance: Optional[AHK[None]] = None
 
 
 def __getattr__(name: str) -> Any:

ahk/_async/window.py

@@ -10,6 +10,7 @@
 from typing import Sequence
 from typing import Tuple
 from typing import TYPE_CHECKING
+from typing import TypeVar
 from typing import Union
 
 from ahk.message import Position
@@ -45,16 +46,18 @@ class WindowNotFoundException(Exception):
     'Use of the {0} property setter is not supported in the async API. Use the set_{0} instead.'
 )
 
+T_EngineVersion = TypeVar('T_EngineVersion', bound=Optional[Literal['v1', 'v2']])
+
 
 class AsyncWindow:
-    def __init__(self, engine: AsyncAHK, ahk_id: str):
-        self._engine: AsyncAHK = engine
+    def __init__(self, engine: AsyncAHK[T_EngineVersion], ahk_id: str):
+        self._engine: AsyncAHK[T_EngineVersion] = engine
         if not ahk_id:
             raise ValueError(f'Invalid ahk_id: {ahk_id!r}')
         self._ahk_id: str = ahk_id
 
     def __repr__(self) -> str:
-        return f'<{self.__class__.__qualname__} ahk_id={self._ahk_id}>'
+        return f'<{self.__class__.__qualname__} ahk_id={self._ahk_id!r}>'
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, AsyncWindow):
@@ -302,17 +305,20 @@ def always_on_top(self, toggle: Literal['On', 'Off', 'Toggle', 1, -1, 0]) -> Any
 
     # fmt: off
     @overload
-    async def send(self, keys: str) -> None: ...
+    async def send(self, keys: str, control: str = '') -> None: ...
     @overload
-    async def send(self, keys: str, *, blocking: Literal[False]) -> AsyncFutureResult[None]: ...
+    async def send(self, keys: str, control: str = '', *, blocking: Literal[False]) -> AsyncFutureResult[None]: ...
     @overload
-    async def send(self, keys: str, *, blocking: Literal[True]) -> None: ...
+    async def send(self, keys: str, control: str = '', *, blocking: Literal[True]) -> None: ...
     @overload
-    async def send(self, keys: str, *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]: ...
+    async def send(self, keys: str, control: str = '', *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]: ...
     # fmt: on
-    async def send(self, keys: str, *, blocking: bool = True) -> Union[None, AsyncFutureResult[None]]:
+    async def send(
+        self, keys: str, control: str = '', *, blocking: bool = True
+    ) -> Union[None, AsyncFutureResult[None]]:
         return await self._engine.control_send(
             keys=keys,
+            control=control,
             title=f'ahk_id {self._ahk_id}',
             blocking=blocking,
             detect_hidden_windows=True,
@@ -378,10 +384,12 @@ async def get_position(self, *, blocking: Literal[False]) -> AsyncFutureResult[O
     @overload
     async def get_position(self, *, blocking: Literal[True]) -> Position: ...
     @overload
-    async def get_position(self, *, blocking: bool = True) -> Union[Position, AsyncFutureResult[Optional[Position]]]: ...
+    async def get_position(self, *, blocking: bool = True) -> Union[Position, AsyncFutureResult[Optional[Position]], AsyncFutureResult[Position]]: ...
     # fmt: on
-    async def get_position(self, *, blocking: bool = True) -> Union[Position, AsyncFutureResult[Optional[Position]]]:
-        resp = await self._engine.win_get_position(
+    async def get_position(
+        self, *, blocking: bool = True
+    ) -> Union[Position, AsyncFutureResult[Optional[Position]], AsyncFutureResult[Position]]:
+        resp = await self._engine.win_get_position(  # type: ignore[misc] # this appears to be a mypy bug
             title=f'ahk_id {self._ahk_id}',
             blocking=blocking,
             detect_hidden_windows=True,
@@ -649,11 +657,11 @@ async def move(
         )
 
     @classmethod
-    async def from_pid(cls, engine: AsyncAHK, pid: int) -> Optional[AsyncWindow]:
+    async def from_pid(cls, engine: AsyncAHK[Any], pid: int) -> Optional[AsyncWindow]:
         return await engine.win_get(title=f'ahk_pid {pid}')
 
     @classmethod
-    async def from_mouse_position(cls, engine: AsyncAHK) -> Optional[AsyncWindow]:
+    async def from_mouse_position(cls, engine: AsyncAHK[Any]) -> Optional[AsyncWindow]:
         return await engine.win_get_from_mouse_position()