openspeedy 0.1.0__py3-none-any.whl

openspeedy/__init__.py

@@ -0,0 +1,87 @@
+"""
+OpenSpeedy — Python bindings for the OpenSpeedy game speed controller.
+
+This library wraps the OpenSpeedy speedpatch DLL injection mechanism,
+allowing Python scripts to accelerate or decelerate Windows games by
+intercepting time-related API functions in target processes.
+
+**Windows only.**  On any other platform, importing this package raises
+``ImportError`` immediately.
+
+Quick start
+-----------
+
+::
+
+    from openspeedy import SpeedController
+
+    sc = SpeedController()
+
+    # List running processes
+    for proc in sc.list_processes():
+        print(f"PID {proc.pid}: {proc.name} ({proc.arch})")
+
+    # Inject into a process and set 2x speed
+    sc.inject(1234)
+    sc.set_speed(2.0)
+
+    # Check status
+    print(f"Speed: {sc.get_speed()}x, enabled: {sc.is_enabled(1234)}")
+
+    # Clean up
+    sc.close()
+
+License
+-------
+
+GPL v3.  See the LICENSE file for full text.
+
+The bundled ``speedpatch*.dll`` files incorporate MinHook, which is
+licensed under the BSD 2-Clause License.
+"""
+
+import sys
+
+if sys.platform != "win32":
+    raise ImportError(
+        "openspeedy is Windows-only. "
+        "It requires Windows APIs for DLL injection, process manipulation, "
+        "and shared memory. "
+        f"Current platform: {sys.platform}"
+    )
+
+from openspeedy._core import SpeedController
+from openspeedy._exceptions import (
+    DLLNotFoundError,
+    EjectionError,
+    InjectionError,
+    OpenSpeedyError,
+    PlatformNotSupportedError,
+    ProcessAccessDeniedError,
+    ProcessArchitectureMismatch,
+    ProcessNotFoundError,
+    SpeedControlError,
+    SpeedRangeError,
+)
+from openspeedy._types import ModuleInfo, ProcessInfo
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main class
+    "SpeedController",
+    # Data types
+    "ProcessInfo",
+    "ModuleInfo",
+    # Exceptions
+    "OpenSpeedyError",
+    "PlatformNotSupportedError",
+    "DLLNotFoundError",
+    "ProcessAccessDeniedError",
+    "ProcessNotFoundError",
+    "ProcessArchitectureMismatch",
+    "InjectionError",
+    "EjectionError",
+    "SpeedRangeError",
+    "SpeedControlError",
+]

openspeedy/_constants.py

@@ -0,0 +1,130 @@
+"""
+Win32 API constants used across the openspeedy package.
+
+Grouped by API surface for readability. All values are from the Windows SDK.
+"""
+
+# ---------------------------------------------------------------------------
+# Process access rights
+# ---------------------------------------------------------------------------
+PROCESS_TERMINATE = 0x0001
+PROCESS_CREATE_THREAD = 0x0002
+PROCESS_SET_SESSIONID = 0x0004
+PROCESS_VM_OPERATION = 0x0008
+PROCESS_VM_READ = 0x0010
+PROCESS_VM_WRITE = 0x0020
+PROCESS_DUP_HANDLE = 0x0040
+PROCESS_CREATE_PROCESS = 0x0080
+PROCESS_SET_QUOTA = 0x0100
+PROCESS_SET_INFORMATION = 0x0200
+PROCESS_QUERY_INFORMATION = 0x0400
+PROCESS_SUSPEND_RESUME = 0x0800
+PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+PROCESS_ALL_ACCESS = 0x1FFFFF
+
+# Commonly needed combination for DLL injection
+PROCESS_INJECT_ACCESS = (
+    PROCESS_CREATE_THREAD
+    | PROCESS_QUERY_INFORMATION
+    | PROCESS_VM_OPERATION
+    | PROCESS_VM_WRITE
+    | PROCESS_VM_READ
+)
+
+PROCESS_EJECT_ACCESS = (
+    PROCESS_CREATE_THREAD
+    | PROCESS_QUERY_INFORMATION
+    | PROCESS_VM_OPERATION
+)
+
+# ---------------------------------------------------------------------------
+# Memory allocation
+# ---------------------------------------------------------------------------
+MEM_COMMIT = 0x00001000
+MEM_RESERVE = 0x00002000
+MEM_RELEASE = 0x00008000
+MEM_DECOMMIT = 0x00004000
+PAGE_READWRITE = 0x04
+PAGE_EXECUTE_READWRITE = 0x40
+
+# ---------------------------------------------------------------------------
+# ToolHelp snapshots
+# ---------------------------------------------------------------------------
+TH32CS_SNAPPROCESS = 0x00000002
+TH32CS_SNAPMODULE = 0x00000008
+TH32CS_SNAPTHREAD = 0x00000004
+
+# ---------------------------------------------------------------------------
+# File mapping
+# ---------------------------------------------------------------------------
+FILE_MAP_ALL_ACCESS = 0x000F001F
+FILE_MAP_READ = 0x00000004
+FILE_MAP_WRITE = 0x00000002
+SECTION_QUERY = 0x0001
+SECTION_MAP_WRITE = 0x0002
+SECTION_MAP_READ = 0x0004
+SECTION_MAP_EXECUTE = 0x0008
+SECTION_EXTEND_SIZE = 0x0010
+SECTION_ALL_ACCESS = 0x000F001F
+STANDARD_RIGHTS_REQUIRED = 0x000F0000
+INVALID_HANDLE_VALUE_SIGNED = -1
+
+# ---------------------------------------------------------------------------
+# Wait / synchronization
+# ---------------------------------------------------------------------------
+INFINITE = 0xFFFFFFFF
+WAIT_OBJECT_0 = 0x00000000
+WAIT_TIMEOUT = 0x00000102
+WAIT_FAILED = 0xFFFFFFFF
+WAIT_ABANDONED_0 = 0x00000080
+
+# ---------------------------------------------------------------------------
+# Token / security
+# ---------------------------------------------------------------------------
+TOKEN_QUERY = 0x0008
+TOKEN_ADJUST_PRIVILEGES = 0x0020
+TokenElevation = 20  # TOKEN_INFORMATION_CLASS
+
+# ---------------------------------------------------------------------------
+# Process name format
+# ---------------------------------------------------------------------------
+PROCESS_NAME_WIN32 = 0
+PROCESS_NAME_NATIVE = 1
+
+# ---------------------------------------------------------------------------
+# Module filter flags for EnumProcessModulesEx
+# ---------------------------------------------------------------------------
+LIST_MODULES_DEFAULT = 0x00
+LIST_MODULES_32BIT = 0x01
+LIST_MODULES_64BIT = 0x02
+LIST_MODULES_ALL = 0x03
+
+# ---------------------------------------------------------------------------
+# Error codes
+# ---------------------------------------------------------------------------
+ERROR_SUCCESS = 0
+ERROR_ACCESS_DENIED = 5
+ERROR_INVALID_PARAMETER = 87
+ERROR_PIPE_CONNECTED = 535
+ERROR_BROKEN_PIPE = 109
+ERROR_NO_DATA = 232
+ERROR_PIPE_NOT_CONNECTED = 233
+ERROR_MORE_DATA = 234
+
+# ---------------------------------------------------------------------------
+# Window enumeration
+# ---------------------------------------------------------------------------
+GW_OWNER = 4
+GW_HWNDFIRST = 0
+GW_HWNDLAST = 1
+GW_HWNDNEXT = 2
+GW_HWNDPREV = 3
+GW_CHILD = 5
+GW_ENABLEDPOPUP = 6
+
+# ---------------------------------------------------------------------------
+# Speed factor limits
+# ---------------------------------------------------------------------------
+SPEED_MIN = 0.001
+SPEED_MAX = 1000.0
+SPEED_DEFAULT = 1.0

openspeedy/_core.py

@@ -0,0 +1,240 @@
+"""
+High-level ``SpeedController`` — the main entry point for the openspeedy
+library.
+
+Aggregates process enumeration, DLL injection/ejection, speed factor
+control, and per-process enable/disable into a single, easy-to-use class.
+"""
+
+import threading
+from contextlib import contextmanager
+from typing import Iterator, List, Set
+
+from ._constants import SPEED_DEFAULT
+from ._eject import eject_dll as _eject_dll
+from ._inject import inject_dll as _inject_dll
+from ._process import list_processes as _list_processes
+from ._speeddll import (
+    disable as _disable,
+    enable as _enable,
+    get_speed as _get_speed,
+    is_enabled as _is_enabled,
+    set_speed as _set_speed,
+)
+from ._types import ProcessInfo
+
+
+class SpeedController:
+    """Control game speed by injecting OpenSpeedy's speedpatch DLL into
+    target Windows processes.
+
+    Usage::
+
+        from openspeedy import SpeedController
+
+        sc = SpeedController()
+        processes = sc.list_processes()
+
+        # Inject into a game
+        sc.inject(pid)
+
+        # Set 2x speed
+        sc.set_speed(2.0)
+
+        # Temporarily boost to 5x
+        with sc.speed_context(5.0):
+            ...  # game runs at 5x
+
+        # Clean up
+        sc.close()
+
+    Thread safety
+    -------------
+
+    Injection/ejection operations are serialized with an internal lock.
+    Speed factor read/write is inherently atomic (the DLL uses
+    ``std::atomic<double>`` in a shared PE section) and requires no
+    additional synchronization at the Python level.
+
+    .. note::
+
+        **v1 architecture limitation**: A 64-bit Python interpreter can
+        only inject into 64-bit processes; a 32-bit interpreter can only
+        inject into 32-bit processes.  This is because ``LoadLibraryW``
+        must be at the same virtual address in both the calling and target
+        processes.
+    """
+
+    def __init__(self) -> None:
+        self._injected_pids: Set[int] = set()
+        self._lock = threading.Lock()
+
+    # ── Process enumeration ─────────────────────────────────────────────
+
+    def list_processes(self, fast: bool = True) -> List[ProcessInfo]:
+        """Enumerate all running Windows processes.
+
+        Args:
+            fast: If ``True`` (default), use snapshot-only enumeration
+                (faster but less detail).  If ``False``, open each process
+                to collect window title, memory, path, and admin status.
+
+        Returns:
+            List of :class:`ProcessInfo` objects.
+        """
+        return _list_processes(fast=fast)
+
+    # ── Injection / ejection ────────────────────────────────────────────
+
+    def inject(self, pid: int) -> None:
+        """Inject the speedpatch DLL into a target process and enable
+        speed control for it.
+
+        Args:
+            pid: Target process ID.
+
+        Raises:
+            ProcessNotFoundError: The PID does not exist.
+            ProcessAccessDeniedError: Cannot open the process (protected
+                or insufficient privileges).
+            ProcessArchitectureMismatch: Python and target architectures
+                differ.
+            InjectionError: The injection itself failed.
+        """
+        with self._lock:
+            _inject_dll(pid)
+            _enable(pid)
+            self._injected_pids.add(pid)
+
+    def eject(self, pid: int) -> None:
+        """Unload the speedpatch DLL from a target process.
+
+        Args:
+            pid: Target process ID.
+
+        Raises:
+            EjectionError: The DLL was not found or ``FreeLibrary`` failed.
+        """
+        with self._lock:
+            _eject_dll(pid)
+            self._injected_pids.discard(pid)
+
+    # ── Global speed factor ─────────────────────────────────────────────
+
+    def set_speed(self, factor: float) -> None:
+        """Set the global speed multiplier.
+
+        Applies to **all** processes that have the speedpatch DLL injected
+        (via the shared PE data section).
+
+        Args:
+            factor: Speed multiplier (1.0 = normal, 2.0 = double,
+                0.5 = half).  Must be in ``[0.001, 1000.0]``.
+
+        Raises:
+            SpeedRangeError: The factor is out of the valid range.
+        """
+        _set_speed(factor)
+
+    def get_speed(self) -> float:
+        """Get the current global speed multiplier.
+
+        Returns:
+            The speed factor (defaults to 1.0).
+        """
+        return _get_speed()
+
+    # ── Per-process enable / disable ────────────────────────────────────
+
+    def enable(self, pid: int) -> None:
+        """Enable (or re-enable) speed control for a previously injected
+        process.
+
+        When a process is disabled, the injected DLL still intercepts time
+        API calls but returns unmodified values (factor = 1.0).  Calling
+        ``enable()`` restores speed modification.
+
+        Args:
+            pid: Target process ID.
+        """
+        _enable(pid)
+
+    def disable(self, pid: int) -> None:
+        """Temporarily disable speed control for a process.
+
+        The process still has the DLL loaded, but time APIs are not
+        affected.  Call :meth:`enable` to re-apply speed control.
+
+        Args:
+            pid: Target process ID.
+        """
+        _disable(pid)
+
+    def is_enabled(self, pid: int) -> bool:
+        """Check whether speed control is currently active for a process.
+
+        Args:
+            pid: Target process ID.
+
+        Returns:
+            ``True`` if speed control is enabled for the process.
+        """
+        return _is_enabled(pid)
+
+    # ── Context manager ─────────────────────────────────────────────────
+
+    @contextmanager
+    def speed_context(self, factor: float) -> Iterator[None]:
+        """Temporarily set a speed factor, restoring the previous value on
+        exit.
+
+        Usage::
+
+            with sc.speed_context(3.0):
+                # everything runs at 3x
+                ...
+            # speed restored
+
+        Args:
+            factor: Temporary speed multiplier.
+        """
+        old = _get_speed()
+        _set_speed(factor)
+        try:
+            yield
+        finally:
+            _set_speed(old)
+
+    # ── Cleanup ─────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Eject from all processes that were injected by this controller
+        instance.
+
+        This is a best-effort operation — some ejections may fail
+        (e.g. if the target process has already exited).  Failures are
+        logged but do not prevent ejecting the remaining processes.
+
+        The controller can still be used after ``close()``; the tracking
+        set is simply cleared.
+        """
+        with self._lock:
+            pids = list(self._injected_pids)
+            for pid in pids:
+                try:
+                    _eject_dll(pid)
+                except Exception:
+                    pass  # best-effort
+            self._injected_pids.clear()
+
+    def __enter__(self) -> "SpeedController":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"<SpeedController injected={len(self._injected_pids)} "
+            f"speed={_get_speed():.2f}>"
+        )

openspeedy/_dll_resolver.py

@@ -0,0 +1,82 @@
+"""
+Locate the speedpatch DLLs on disk.
+
+Resolution order:
+1. ``OPENSPEEDY_DLL_DIR`` environment variable (directory containing the DLLs)
+2. Package data directory ``openspeedy/data/``
+3. Current working directory
+"""
+
+import os
+import struct
+from pathlib import Path
+from typing import Optional
+
+from ._exceptions import DLLNotFoundError
+
+
+def _get_data_dir() -> Path:
+    """Return the absolute path to ``openspeedy/data/``."""
+    return Path(__file__).resolve().parent / "data"
+
+
+def _is_python_64bit() -> bool:
+    """Return ``True`` if the running Python interpreter is 64-bit."""
+    return struct.calcsize("P") == 8
+
+
+def _get_own_dll_path() -> Path:
+    """Return the path to the speedpatch DLL matching the Python
+    interpreter's own architecture."""
+    dll_name = "speedpatch64.dll" if _is_python_64bit() else "speedpatch32.dll"
+    return _resolve_dll_path(dll_name)
+
+
+def _get_target_dll_path(is_64bit: bool) -> Path:
+    """Return the path to the speedpatch DLL for a target of the given
+    architecture."""
+    dll_name = "speedpatch64.dll" if is_64bit else "speedpatch32.dll"
+    return _resolve_dll_path(dll_name)
+
+
+def _resolve_dll_path(dll_name: str) -> Path:
+    """Resolve a DLL by name using the standard search order.
+
+    Raises:
+        DLLNotFoundError: If the DLL cannot be found at any search location.
+    """
+    # 1. Environment variable override
+    env_dir = os.environ.get("OPENSPEEDY_DLL_DIR")
+    if env_dir:
+        candidate = Path(env_dir) / dll_name
+        if candidate.is_file():
+            return candidate
+
+    # 2. Package data directory
+    candidate = _get_data_dir() / dll_name
+    if candidate.is_file():
+        return candidate
+
+    # 3. Current working directory
+    candidate = Path.cwd() / dll_name
+    if candidate.is_file():
+        return candidate
+
+    raise DLLNotFoundError(str(candidate))
+
+
+def _find_all_dll_paths() -> dict:
+    """Find paths for both DLLs if available.
+
+    Returns:
+        Dict mapping arch name to Path, e.g.
+        ``{"x64": Path(...), "x86": Path(...)}``.
+        Missing entries are simply omitted.
+    """
+    result: dict = {}
+    for arch, dll_name in [("x64", "speedpatch64.dll"), ("x86", "speedpatch32.dll")]:
+        try:
+            result[arch] = _resolve_dll_path(dll_name)
+        except DLLNotFoundError:
+            pass
+    return result

openspeedy/_eject.py

@@ -0,0 +1,139 @@
+"""
+DLL ejection from a target Windows process.
+
+Re-implements the Rust ``do_eject()`` function from ``src-bridge/src/main.rs``
+in pure Python via ``ctypes``.
+
+Ejection flow
+-------------
+
+1. Determine the DLL name from the target architecture
+2. ``CreateToolhelp32Snapshot(TH32CS_SNAPMODULE, pid)``
+3. ``Module32FirstW`` / ``Module32NextW`` loop to find the speedpatch DLL
+4. Extract ``hModule`` (the module base address)
+5. ``OpenProcess`` on the target
+6. Get ``FreeLibrary`` address from local ``kernel32.dll``
+7. ``CreateRemoteThread`` with ``FreeLibrary(hModule)`` as entry point
+8. ``WaitForSingleObject``
+9. Cleanup handles
+"""
+
+import ctypes
+
+from ._constants import (
+    PROCESS_EJECT_ACCESS,
+    PROCESS_QUERY_INFORMATION,
+    TH32CS_SNAPMODULE,
+    WAIT_OBJECT_0,
+)
+from ._exceptions import (
+    EjectionError,
+    ProcessAccessDeniedError,
+)
+from ._process import _detect_arch_for_pid
+from ._winapi import (
+    MODULEENTRY32W,
+    kernel32,
+    wintypes,
+    get_freelibrary_address,
+)
+
+
+def eject_dll(pid: int) -> None:
+    """Unload the speedpatch DLL from a target process.
+
+    Args:
+        pid: Target process ID.
+
+    Raises:
+        EjectionError: The DLL was not found in the target or
+            ``FreeLibrary`` failed.
+        ProcessAccessDeniedError: Cannot open the process.
+    """
+    # 1. Determine DLL name from target architecture
+    arch = _detect_arch_for_pid(pid)
+    dll_name = "speedpatch64.dll" if arch == "x64" else "speedpatch32.dll"
+    dll_name_lower = dll_name.lower()
+
+    # 2. Enumerate modules in the target
+    h_module = _find_dll_module(pid, dll_name_lower)
+    if h_module is None:
+        raise EjectionError(pid, f"module '{dll_name}' not found in process")
+
+    # 3. Open the target process
+    h_proc = kernel32.OpenProcess(PROCESS_EJECT_ACCESS, False, pid)
+    if not h_proc:
+        err = ctypes.get_last_error()
+        raise ProcessAccessDeniedError(pid, win_error=err)
+
+    try:
+        # 4. Get FreeLibrary address
+        lp_free = get_freelibrary_address()
+        if not lp_free:
+            raise EjectionError(pid, "cannot get FreeLibrary address")
+
+        # 5. Create remote thread calling FreeLibrary(h_module)
+        thread_id = wintypes.DWORD(0)
+        h_thread = kernel32.CreateRemoteThread(
+            h_proc,
+            None,
+            0,
+            lp_free,
+            h_module,
+            0,
+            ctypes.byref(thread_id),
+        )
+        if not h_thread:
+            err = ctypes.get_last_error()
+            raise EjectionError(
+                pid, "CreateRemoteThread for FreeLibrary failed", win_error=err
+            )
+
+        try:
+            ret = kernel32.WaitForSingleObject(h_thread, 5000)
+            if ret != WAIT_OBJECT_0:
+                raise EjectionError(
+                    pid, "WaitForSingleObject timed out or failed"
+                )
+        finally:
+            kernel32.CloseHandle(h_thread)
+
+    finally:
+        kernel32.CloseHandle(h_proc)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_dll_module(pid: int, dll_name_lower: str) -> int | None:
+    """Find the HMODULE (base address) of a DLL loaded in a target process.
+
+    Args:
+        pid: Target process ID.
+        dll_name_lower: Lower-cased DLL name to search for.
+
+    Returns:
+        Module handle value, or ``None`` if not found.
+    """
+    snapshot = kernel32.CreateToolhelp32Snapshot(TH32CS_SNAPMODULE, pid)
+    if not snapshot or snapshot == ctypes.c_void_p(-1).value:
+        return None
+
+    try:
+        entry = MODULEENTRY32W()
+        entry.dwSize = ctypes.sizeof(MODULEENTRY32W)
+
+        if kernel32.Module32FirstW(snapshot, ctypes.byref(entry)):
+            while True:
+                mod_name = entry.szModule.rstrip("\x00").lower()
+                if mod_name == dll_name_lower:
+                    return entry.hModule
+
+                if not kernel32.Module32NextW(snapshot, ctypes.byref(entry)):
+                    break
+    finally:
+        kernel32.CloseHandle(snapshot)
+
+    return None