alphawindow 0.1.0__tar.gz

alphawindow-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include src/alphawindow py.typed

alphawindow-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: alphawindow
+Version: 0.1.0
+Summary: Windows-first window automation abstractions with pluggable input and output modes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: native
+Requires-Dist: pywin32>=306; platform_system == "Windows" and extra == "native"
+Requires-Dist: pynput>=1.7.6; platform_system == "Windows" and extra == "native"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# AlphaWindow
+
+AlphaWindow is a Windows-first automation abstraction layer. It exposes one session API for window operations while allowing callers to choose different input and output modes.
+
+The first implementation includes:
+
+- Built-in I/O profiles for every declared input and output mode, including `inspect`, `observe`, `desktop_observe`, `dry_run`, `win32_message`, `message_only`, `uia_control`, `uia_visual`, `global_input`, `foreground_visual`, `guarded_input`, `guarded_desktop`, `isolated_observe`, `isolated_telemetry`, `virtual_window`, `virtual_telemetry`, and `virtual_input_only`.
+- A `WindowSession` API for `prefetch`, `capture`, `observe`, `click`, `key_down`, `key_up`, and `type_text`.
+- Generic delegation backends for message, UIA, foreground, guarded foreground, state, desktop-region, hook-telemetry, and no-output modes.
+- Compatibility checks so a backend cannot silently fall back to a broader side-effect mode.
+- Hook-aware `isolated` and `virtualized` input backends that accept pluggable hook managers and virtual input transports.
+
+Native pywin32, pynput, and DLL hook adapters are intended to plug into the same protocols in later slices.
+
+## Install
+
+From PyPI after publishing:
+
+```powershell
+pip install alphawindow
+```
+
+From this checkout:
+
+```powershell
+pip install .
+```
+
+## Import
+
+```python
+import alphawindow
+
+from alphawindow import (
+    AutomationConfig,
+    InputMode,
+    OutputMode,
+    WindowSelector,
+    WindowSession,
+    get_profile,
+)
+
+print(alphawindow.__version__)
+print(get_profile("observe").input_mode is InputMode.DRY_RUN)
+```
+
+## Release
+
+Publishing is handled by GitHub Actions in `.github/workflows/publish.yml`.
+
+1. Configure PyPI Trusted Publishing for this repository, environment `pypi`, and workflow `publish.yml`.
+2. Update the version in `pyproject.toml` and `src/alphawindow/_version.py`.
+3. Push a version tag:
+
+```powershell
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs tests on Windows for Python 3.11, 3.12, and 3.13, builds the package, checks distribution metadata, and publishes to PyPI only for `v*` tags.

alphawindow-0.1.0/README.md

@@ -0,0 +1,60 @@
+# AlphaWindow
+
+AlphaWindow is a Windows-first automation abstraction layer. It exposes one session API for window operations while allowing callers to choose different input and output modes.
+
+The first implementation includes:
+
+- Built-in I/O profiles for every declared input and output mode, including `inspect`, `observe`, `desktop_observe`, `dry_run`, `win32_message`, `message_only`, `uia_control`, `uia_visual`, `global_input`, `foreground_visual`, `guarded_input`, `guarded_desktop`, `isolated_observe`, `isolated_telemetry`, `virtual_window`, `virtual_telemetry`, and `virtual_input_only`.
+- A `WindowSession` API for `prefetch`, `capture`, `observe`, `click`, `key_down`, `key_up`, and `type_text`.
+- Generic delegation backends for message, UIA, foreground, guarded foreground, state, desktop-region, hook-telemetry, and no-output modes.
+- Compatibility checks so a backend cannot silently fall back to a broader side-effect mode.
+- Hook-aware `isolated` and `virtualized` input backends that accept pluggable hook managers and virtual input transports.
+
+Native pywin32, pynput, and DLL hook adapters are intended to plug into the same protocols in later slices.
+
+## Install
+
+From PyPI after publishing:
+
+```powershell
+pip install alphawindow
+```
+
+From this checkout:
+
+```powershell
+pip install .
+```
+
+## Import
+
+```python
+import alphawindow
+
+from alphawindow import (
+    AutomationConfig,
+    InputMode,
+    OutputMode,
+    WindowSelector,
+    WindowSession,
+    get_profile,
+)
+
+print(alphawindow.__version__)
+print(get_profile("observe").input_mode is InputMode.DRY_RUN)
+```
+
+## Release
+
+Publishing is handled by GitHub Actions in `.github/workflows/publish.yml`.
+
+1. Configure PyPI Trusted Publishing for this repository, environment `pypi`, and workflow `publish.yml`.
+2. Update the version in `pyproject.toml` and `src/alphawindow/_version.py`.
+3. Push a version tag:
+
+```powershell
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs tests on Windows for Python 3.11, 3.12, and 3.13, builds the package, checks distribution metadata, and publishes to PyPI only for `v*` tags.

alphawindow-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alphawindow"
+version = "0.1.0"
+description = "Windows-first window automation abstractions with pluggable input and output modes."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+native = [
+  "pywin32>=306; platform_system == 'Windows'",
+  "pynput>=1.7.6; platform_system == 'Windows'",
+]
+test = [
+  "pytest>=8",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+alphawindow = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

alphawindow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alphawindow-0.1.0/src/alphawindow/__init__.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from .backends import (
+    DelegatingInputBackend,
+    DelegatingOutputBackend,
+    DryRunInputBackend,
+    IsolatedInputBackend,
+    NullOutputBackend,
+    StateOutputBackend,
+    VirtualizedInputBackend,
+)
+from .profiles import BUILTIN_PROFILES, get_profile
+from .session import WindowSession, open_window
+from ._version import __version__
+from .types import (
+    AutomationConfig,
+    AutomationProfile,
+    BackendCompatibilityError,
+    Capability,
+    InputMode,
+    Operation,
+    OperationResult,
+    OutputMode,
+    WindowNotFoundError,
+    WindowSelector,
+    WindowSnapshot,
+)
+
+__all__ = [
+    "AutomationConfig",
+    "AutomationProfile",
+    "BUILTIN_PROFILES",
+    "BackendCompatibilityError",
+    "Capability",
+    "DelegatingInputBackend",
+    "DelegatingOutputBackend",
+    "DryRunInputBackend",
+    "InputMode",
+    "IsolatedInputBackend",
+    "NullOutputBackend",
+    "Operation",
+    "OperationResult",
+    "OutputMode",
+    "StateOutputBackend",
+    "VirtualizedInputBackend",
+    "WindowNotFoundError",
+    "WindowSelector",
+    "WindowSession",
+    "WindowSnapshot",
+    "__version__",
+    "get_profile",
+    "open_window",
+]

alphawindow-0.1.0/src/alphawindow/_version.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.1.0"

alphawindow-0.1.0/src/alphawindow/backends.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .types import (
+    BackendCompatibilityError,
+    Capability,
+    HookManager,
+    InputBackend,
+    InputMode,
+    Operation,
+    OperationResult,
+    OutputMode,
+    VirtualInputTransport,
+    WindowSnapshot,
+)
+
+
+INPUT_MODE_CAPABILITIES: dict[InputMode, frozenset[Capability]] = {
+    InputMode.DRY_RUN: frozenset(),
+    InputMode.MESSAGE: frozenset({Capability.WINDOW_MESSAGE_INPUT}),
+    InputMode.UIA: frozenset({Capability.UIA_INPUT}),
+    InputMode.FOREGROUND: frozenset({Capability.GLOBAL_INPUT}),
+    InputMode.GUARDED_FOREGROUND: frozenset({Capability.GUARDED_GLOBAL_INPUT}),
+    InputMode.ISOLATED: frozenset({Capability.HOOKED_INPUT}),
+    InputMode.VIRTUALIZED: frozenset({Capability.HOOKED_INPUT, Capability.VIRTUAL_INPUT}),
+}
+
+OUTPUT_MODE_CAPABILITIES: dict[OutputMode, frozenset[Capability]] = {
+    OutputMode.STATE: frozenset({Capability.WINDOW_STATE}),
+    OutputMode.WINDOW_CAPTURE: frozenset({Capability.WINDOW_CAPTURE}),
+    OutputMode.DESKTOP_REGION: frozenset({Capability.DESKTOP_CAPTURE}),
+    OutputMode.HOOK_TELEMETRY: frozenset({Capability.HOOK_TELEMETRY}),
+    OutputMode.NONE: frozenset(),
+}
+
+
+class DryRunInputBackend:
+    mode = InputMode.DRY_RUN
+    capabilities = frozenset()
+
+    def __init__(self) -> None:
+        self.operations: list[Operation] = []
+
+    def perform(self, target: WindowSnapshot, operation: Operation) -> OperationResult:
+        self.operations.append(operation)
+        return OperationResult(
+            operation=operation,
+            executed=False,
+            backend="dry_run",
+            details={"hwnd": target.hwnd},
+        )
+
+
+@dataclass
+class DelegatingInputBackend:
+    mode: InputMode
+    performer: Callable[[WindowSnapshot, Operation], OperationResult | None]
+    name: str | None = None
+    capabilities: frozenset[Capability] | None = None
+
+    def __post_init__(self) -> None:
+        if self.mode in {InputMode.ISOLATED, InputMode.VIRTUALIZED}:
+            raise BackendCompatibilityError(
+                "use dedicated hook-aware backends for isolated and virtualized input"
+            )
+        if self.capabilities is None:
+            self.capabilities = INPUT_MODE_CAPABILITIES[self.mode]
+        if self.name is None:
+            self.name = self.mode.value
+
+    def perform(self, target: WindowSnapshot, operation: Operation) -> OperationResult:
+        result = self.performer(target, operation)
+        if isinstance(result, OperationResult):
+            return result
+        return OperationResult(
+            operation=operation,
+            executed=True,
+            backend=str(self.name),
+            details={"hwnd": target.hwnd},
+        )
+
+
+class StateOutputBackend:
+    mode = OutputMode.STATE
+    capabilities = frozenset({Capability.WINDOW_STATE})
+
+    def capture(self, target: WindowSnapshot) -> WindowSnapshot:
+        return target
+
+    def observe(self, target: WindowSnapshot) -> WindowSnapshot:
+        return target
+
+
+class NullOutputBackend:
+    mode = OutputMode.NONE
+    capabilities = frozenset()
+
+    def capture(self, target: WindowSnapshot) -> None:
+        return None
+
+    def observe(self, target: WindowSnapshot) -> WindowSnapshot:
+        return target
+
+
+@dataclass
+class DelegatingOutputBackend:
+    mode: OutputMode
+    capture_fn: Callable[[WindowSnapshot], Any] | None = None
+    observe_fn: Callable[[WindowSnapshot], WindowSnapshot] | None = None
+    name: str | None = None
+    capabilities: frozenset[Capability] | None = None
+
+    def __post_init__(self) -> None:
+        if self.capabilities is None:
+            self.capabilities = OUTPUT_MODE_CAPABILITIES[self.mode]
+        if self.name is None:
+            self.name = self.mode.value
+
+    def capture(self, target: WindowSnapshot) -> Any:
+        if self.capture_fn is None:
+            if self.mode is OutputMode.NONE:
+                return None
+            if self.mode is OutputMode.STATE:
+                return target
+            raise BackendCompatibilityError(
+                f"output backend {self.name!r} has no capture function"
+            )
+        return self.capture_fn(target)
+
+    def observe(self, target: WindowSnapshot) -> WindowSnapshot:
+        if self.observe_fn is None:
+            return target
+        return self.observe_fn(target)
+
+
+@dataclass
+class IsolatedInputBackend:
+    hook_manager: HookManager
+    delegate: InputBackend | None = None
+
+    mode = InputMode.ISOLATED
+    capabilities = frozenset({Capability.HOOKED_INPUT})
+
+    def __post_init__(self) -> None:
+        if self.hook_manager is None:
+            raise BackendCompatibilityError("isolated input requires a hook manager")
+
+    def perform(self, target: WindowSnapshot, operation: Operation) -> OperationResult:
+        self.hook_manager.ensure_injected(target)
+        if self.delegate is not None:
+            return self.delegate.perform(target, operation)
+        return OperationResult(
+            operation=operation,
+            executed=False,
+            backend="isolated",
+            details={"hwnd": target.hwnd, "hooked": True},
+        )
+
+
+@dataclass
+class VirtualizedInputBackend:
+    hook_manager: HookManager
+    transport: VirtualInputTransport
+
+    mode = InputMode.VIRTUALIZED
+    capabilities = frozenset({Capability.HOOKED_INPUT, Capability.VIRTUAL_INPUT})
+
+    def __post_init__(self) -> None:
+        if self.hook_manager is None:
+            raise BackendCompatibilityError("virtualized input requires a hook manager")
+        if self.transport is None:
+            raise BackendCompatibilityError("virtualized input requires a transport")
+
+    def perform(self, target: WindowSnapshot, operation: Operation) -> OperationResult:
+        self.hook_manager.ensure_injected(target)
+        return self.transport.send(target, operation)

alphawindow-0.1.0/src/alphawindow/profiles.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from .types import (
+    AutomationProfile,
+    BackendCompatibilityError,
+    InputMode,
+    OutputMode,
+)
+
+
+BUILTIN_PROFILES: dict[str, AutomationProfile] = {
+    "inspect": AutomationProfile(
+        name="inspect",
+        input_mode=InputMode.DRY_RUN,
+        output_mode=OutputMode.STATE,
+        description="Inspect window state without capture or input.",
+    ),
+    "observe": AutomationProfile(
+        name="observe",
+        input_mode=InputMode.DRY_RUN,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        description="Capture or inspect a window without sending input.",
+    ),
+    "desktop_observe": AutomationProfile(
+        name="desktop_observe",
+        input_mode=InputMode.DRY_RUN,
+        output_mode=OutputMode.DESKTOP_REGION,
+        description="Observe a target through desktop-region capture.",
+    ),
+    "dry_run": AutomationProfile(
+        name="dry_run",
+        input_mode=InputMode.DRY_RUN,
+        output_mode=OutputMode.NONE,
+        description="Plan operations without output or input side effects.",
+    ),
+    "win32_message": AutomationProfile(
+        name="win32_message",
+        input_mode=InputMode.MESSAGE,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        description="Send window-message input while capturing the target window.",
+    ),
+    "message_only": AutomationProfile(
+        name="message_only",
+        input_mode=InputMode.MESSAGE,
+        output_mode=OutputMode.NONE,
+        description="Send window-message input without output capture.",
+    ),
+    "uia_control": AutomationProfile(
+        name="uia_control",
+        input_mode=InputMode.UIA,
+        output_mode=OutputMode.STATE,
+        description="Drive standard controls through Windows UI Automation.",
+    ),
+    "uia_visual": AutomationProfile(
+        name="uia_visual",
+        input_mode=InputMode.UIA,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        description="Drive UI Automation controls while capturing the window.",
+    ),
+    "global_input": AutomationProfile(
+        name="global_input",
+        input_mode=InputMode.FOREGROUND,
+        output_mode=OutputMode.DESKTOP_REGION,
+        description="Use global foreground input such as pynput or SendInput.",
+    ),
+    "foreground_visual": AutomationProfile(
+        name="foreground_visual",
+        input_mode=InputMode.FOREGROUND,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        description="Use global foreground input with direct window capture.",
+    ),
+    "guarded_input": AutomationProfile(
+        name="guarded_input",
+        input_mode=InputMode.GUARDED_FOREGROUND,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        description="Use foreground input with cleanup and focus restoration.",
+    ),
+    "guarded_desktop": AutomationProfile(
+        name="guarded_desktop",
+        input_mode=InputMode.GUARDED_FOREGROUND,
+        output_mode=OutputMode.DESKTOP_REGION,
+        description="Use guarded foreground input with desktop-region capture.",
+    ),
+    "isolated_observe": AutomationProfile(
+        name="isolated_observe",
+        input_mode=InputMode.ISOLATED,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        requires_hook=True,
+        description="Inject an isolation hook before any optional delegated input.",
+    ),
+    "isolated_telemetry": AutomationProfile(
+        name="isolated_telemetry",
+        input_mode=InputMode.ISOLATED,
+        output_mode=OutputMode.HOOK_TELEMETRY,
+        requires_hook=True,
+        description="Inject an isolation hook and read hook telemetry.",
+    ),
+    "virtual_window": AutomationProfile(
+        name="virtual_window",
+        input_mode=InputMode.VIRTUALIZED,
+        output_mode=OutputMode.WINDOW_CAPTURE,
+        requires_hook=True,
+        description="Route virtual mouse and keyboard operations through a hook transport.",
+    ),
+    "virtual_telemetry": AutomationProfile(
+        name="virtual_telemetry",
+        input_mode=InputMode.VIRTUALIZED,
+        output_mode=OutputMode.HOOK_TELEMETRY,
+        requires_hook=True,
+        description="Route virtual input and read hook telemetry.",
+    ),
+    "virtual_input_only": AutomationProfile(
+        name="virtual_input_only",
+        input_mode=InputMode.VIRTUALIZED,
+        output_mode=OutputMode.NONE,
+        requires_hook=True,
+        description="Route virtual input without output capture.",
+    ),
+}
+
+
+def get_profile(profile: str | AutomationProfile) -> AutomationProfile:
+    if isinstance(profile, AutomationProfile):
+        return profile
+    try:
+        return BUILTIN_PROFILES[profile]
+    except KeyError as exc:
+        raise BackendCompatibilityError(
+            f"unknown automation profile: {profile}"
+        ) from exc

alphawindow-0.1.0/src/alphawindow/py.typed

@@ -0,0 +1 @@
+

alphawindow-0.1.0/src/alphawindow/session.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .profiles import get_profile
+from .types import (
+    AutomationConfig,
+    AutomationProfile,
+    BackendCompatibilityError,
+    Capability,
+    InputBackend,
+    InputMode,
+    Operation,
+    OperationResult,
+    OutputBackend,
+    WindowNotFoundError,
+    WindowResolver,
+    WindowSelector,
+    WindowSnapshot,
+)
+
+
+class WindowSession:
+    def __init__(
+        self,
+        *,
+        selector: WindowSelector,
+        resolver: WindowResolver,
+        input_backend: InputBackend,
+        output_backend: OutputBackend,
+        config: AutomationConfig | None = None,
+    ) -> None:
+        self.selector = selector
+        self.resolver = resolver
+        self.input_backend = input_backend
+        self.output_backend = output_backend
+        self.config = config or AutomationConfig()
+        self.profile: AutomationProfile = get_profile(self.config.profile)
+        self._prefetched: tuple[float, WindowSnapshot] | None = None
+        self._validate_backends()
+
+    def prefetch(self, *, now: float | None = None) -> WindowSnapshot:
+        snapshot = self._resolve_snapshot()
+        self._prefetched = (self._clock(now), snapshot)
+        return snapshot
+
+    def capture(self, *, now: float | None = None) -> Any:
+        return self.output_backend.capture(self._target_snapshot(now=now))
+
+    def observe(self, *, now: float | None = None) -> WindowSnapshot:
+        observe = getattr(self.output_backend, "observe", None)
+        target = self._target_snapshot(now=now)
+        if observe is None:
+            return target
+        return observe(target)
+
+    def click(self, x: int | float, y: int | float, *, now: float | None = None) -> OperationResult:
+        target = self._target_snapshot(now=now)
+        px, py = target.normalize_point(x, y)
+        return self._perform(target, Operation(kind="click", x=px, y=py))
+
+    def key_down(self, key: str, *, now: float | None = None) -> OperationResult:
+        return self._perform(
+            self._target_snapshot(now=now),
+            Operation(kind="key_down", key=key),
+        )
+
+    def key_up(self, key: str, *, now: float | None = None) -> OperationResult:
+        return self._perform(
+            self._target_snapshot(now=now),
+            Operation(kind="key_up", key=key),
+        )
+
+    def type_text(self, text: str, *, now: float | None = None) -> OperationResult:
+        return self._perform(
+            self._target_snapshot(now=now),
+            Operation(kind="type_text", text=text),
+        )
+
+    def _perform(self, target: WindowSnapshot, operation: Operation) -> OperationResult:
+        return self.input_backend.perform(target, operation)
+
+    def _target_snapshot(self, *, now: float | None = None) -> WindowSnapshot:
+        current = self._clock(now)
+        if self._prefetched is not None:
+            resolved_at, snapshot = self._prefetched
+            fresh = current - resolved_at <= self.config.prefetch_ttl_seconds
+            if fresh and self._snapshot_is_valid(snapshot):
+                return snapshot
+        return self.prefetch(now=current)
+
+    def _resolve_snapshot(self) -> WindowSnapshot:
+        snapshot = self.resolver.resolve(self.selector)
+        if snapshot is None:
+            raise WindowNotFoundError(f"window not found: {self.selector}")
+        return snapshot
+
+    def _snapshot_is_valid(self, snapshot: WindowSnapshot) -> bool:
+        validator = getattr(self.resolver, "is_valid", None)
+        if validator is None:
+            return snapshot.visible
+        return bool(validator(snapshot))
+
+    def _validate_backends(self) -> None:
+        input_mode = getattr(self.input_backend, "mode", None)
+        allowed_input_modes = {
+            self.profile.input_mode,
+            *self.config.allowed_input_fallbacks,
+        }
+        if input_mode not in allowed_input_modes:
+            raise BackendCompatibilityError(
+                "input backend mode "
+                f"{input_mode!r} is not allowed for profile {self.profile.name!r}"
+            )
+
+        output_mode = getattr(self.output_backend, "mode", None)
+        if output_mode != self.profile.output_mode:
+            raise BackendCompatibilityError(
+                "output backend mode "
+                f"{output_mode!r} does not match profile {self.profile.name!r}"
+            )
+
+        if self.profile.requires_hook:
+            capabilities = getattr(self.input_backend, "capabilities", frozenset())
+            if Capability.HOOKED_INPUT not in capabilities:
+                raise BackendCompatibilityError(
+                    f"profile {self.profile.name!r} requires a hook-capable input backend"
+                )
+
+    @staticmethod
+    def _clock(now: float | None) -> float:
+        return time.monotonic() if now is None else now
+
+
+def open_window(
+    *,
+    selector: WindowSelector,
+    resolver: WindowResolver,
+    input_backend: InputBackend,
+    output_backend: OutputBackend,
+    config: AutomationConfig | None = None,
+) -> WindowSession:
+    return WindowSession(
+        selector=selector,
+        resolver=resolver,
+        input_backend=input_backend,
+        output_backend=output_backend,
+        config=config,
+    )