The prose of each docstring and comment in the core package now follows ASD-STE100 Simplified Technical English, with Canadian spelling: short sentences, simple verb tenses, no dashes or semicolons, and one word for one concept (docs/development/writing-style.md has the rules and the glossary). The meaning and each reason stay. The code does not change: the AST of each file, without its docstrings, is the same as before. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
68 lines
2.8 KiB
Python
68 lines
2.8 KiB
Python
# SPDX-License-Identifier: Apache-2.0
|
|
"""Private handles on the Windows DLLs, because all code in a process shares ``ctypes.windll``.
|
|
|
|
``ctypes.windll.kernel32`` is a cache. Each caller in the process gets the same ``WinDLL``
|
|
object, and each function on it is a cached attribute. Thus
|
|
``ctypes.windll.kernel32.GetConsoleScreenBufferInfo`` is one object, which this
|
|
application and all the libraries in it share. When code sets ``.argtypes`` on it, the
|
|
change is not local. It is a change for the full process, and the last writer wins.
|
|
|
|
This problem is real. It caused a crash of MeshTerm on Windows:
|
|
|
|
* ``ui/tui/emoji_width.py`` measured an emoji: it asked the console for its cursor
|
|
position. It declared that ``GetConsoleScreenBufferInfo`` takes a pointer to its own
|
|
copy of the screen-buffer struct.
|
|
* Later, prompt_toolkit called the same function object with a pointer to its own copy of
|
|
the same struct. The two copies had the same layout, but a different class.
|
|
* ctypes compared the two classes, found that they were not equal, and refused the call:
|
|
``expected LP__CSBI instance instead of pointer to CONSOLE_SCREEN_BUFFER_INFO``.
|
|
|
|
The application crashed while it built its screen. On a build that the user started with
|
|
a double-click, the traceback and its window disappeared at the same time.
|
|
|
|
When code makes a ``WinDLL`` directly, it gets a new object with its own function cache.
|
|
Thus only the caller that makes declarations on that object can see them. Each call in
|
|
this module returns a new object. If two parts of MeshTerm declare the same function
|
|
differently, that is the same bug on a small scale. The cost is one small object at a call
|
|
site that runs rarely.
|
|
|
|
This module exists for one rule: **no code in MeshTerm uses ``ctypes.windll``.**
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import ctypes
|
|
import sys
|
|
|
|
__all__ = ["kernel32", "user32"]
|
|
|
|
|
|
def _library(name: str) -> ctypes.WinDLL:
|
|
"""Load ``name`` into a private WinDLL.
|
|
|
|
Args:
|
|
name: The DLL to load, without its extension.
|
|
|
|
Returns:
|
|
A private handle. No other code can see or change its function signatures.
|
|
|
|
Raises:
|
|
RuntimeError: If the call is not on Windows, because these libraries exist only on
|
|
Windows.
|
|
"""
|
|
if sys.platform != "win32": # pragma: no cover - the callers all guard on platform
|
|
raise RuntimeError(f"{name} is a Windows library")
|
|
# `use_last_error` keeps GetLastError unchanged for the caller. It is the only way to
|
|
# know "the call failed" from "the call succeeded and returned zero".
|
|
return ctypes.WinDLL(name, use_last_error=True)
|
|
|
|
|
|
def kernel32() -> ctypes.WinDLL:
|
|
"""A private handle on ``kernel32``: console, handles, memory."""
|
|
return _library("kernel32")
|
|
|
|
|
|
def user32() -> ctypes.WinDLL:
|
|
"""A private handle on ``user32``: clipboard, keyboard state, windows."""
|
|
return _library("user32")
|