317. PyPy 启动脚本

为手动运行添加明确的 PyPy 启动脚本。

第 317 / 356 · tests/chapter_10_performance/test_317_pypy_launchers.py

需要在仓库根目录创建的文件

launcher.sh
launcher.cmd

为什么需要这一步

PyPy 可以提升模拟器核心的吞吐量，因为模拟器的大部分代码都是运行在紧密循环中的 Python 代码。这一步没有去修改 pyproject.toml 或强制所有学员默认使用 PyPy，而是添加了明确的手动启动脚本。

创建这些启动脚本之后，学员在进行手动性能实验时应当使用它们，而不是直接用 CPython 启动 main.py。

Linux/macOS 用法

sh launcher.sh

或者，如果已经添加了可执行权限：

chmod +x launcher.sh
./launcher.sh

Windows 命令提示符用法

launcher.cmd

预期的手动信号

当模拟器核心从 PyPy 中受益时，之前添加的 FPS 计数器数值应当会提升。在采用更快的 pygame 帧缓冲上传路径之后，PyPy 可能会让模拟器运行得比真实 NES 速度更快。在教程开发过程中，更快的 pygame 绘制路径加上 PyPy，在手动 ROM 路径上大约达到了 90-120 FPS。

具体数值取决于机器和 ROM 状态，但现在终端输出的 FPS 就是可以用来比较的依据：

fps=30.0    # example after faster pygame drawing on CPython
fps=100.0   # example after faster pygame drawing + PyPy launcher

如果此时 FPS 高于 NES 速度，这就是一个很好的证据，说明下一步应当添加帧节奏 / 预期速度控制，以避免手动游戏运行得太快。

两个启动脚本最终委托执行的命令

uv run --python pypy python main.py

Linux/macOS 示例

#!/usr/bin/env sh

# Run NES with PyPy through uv.
# Usage:
#     sh launcher.sh
# or:
#     chmod +x launcher.sh
#     ./launcher.sh

uv run --python pypy python main.py

Windows CMD 示例

@echo off

REM Run NES with PyPy through uv.
REM Usage:
REM     launcher.cmd

uv run --python pypy python main.py

重要的测试规则

这些测试不得执行这些启动脚本。运行它们会启动手动的 pygame 前端，并需要本地 ROM 文件。我们只是以文本方式检查这些文件。

本步骤范围之外

更改 pyproject.toml 中的默认 Python
从 pytest 中启动 PyPy
打开 pygame 窗口
测量 FPS
优化渲染

运行本课

uv run pytest tests/chapter_10_performance/test_317_pypy_launchers.py -v

示例实现

Windows CMD 示例

@echo off

REM Run NES with PyPy through uv.
REM Usage:
REM     launcher.cmd

uv run --python pypy python main.py

查看测试代码test_317_pypy_launchers.py

from pathlib import Path


ROOT = Path(__file__).resolve().parents[2]
LAUNCHER_SH = ROOT / "launcher.sh"
LAUNCHER_CMD = ROOT / "launcher.cmd"
EXPECTED_COMMAND = "uv run --python pypy python main.py"


def test_linux_mac_pypy_launcher_exists_at_repo_root():
    """
    Objective:
    Linux/macOS users should have a simple shell launcher at the repository root.
    """
    assert LAUNCHER_SH.exists()


def test_windows_pypy_launcher_exists_at_repo_root():
    """
    Objective:
    Windows users should have a simple CMD launcher at the repository root.
    """
    assert LAUNCHER_CMD.exists()


def test_linux_mac_launcher_uses_sh_shebang():
    """
    Objective:
    launcher.sh should be runnable with POSIX sh on Linux/macOS.
    """
    source = LAUNCHER_SH.read_text()

    assert source.startswith("#!/usr/bin/env sh")


def test_linux_mac_launcher_delegates_to_uv_pypy_main():
    """
    Objective:
    The shell launcher should explicitly run main.py using PyPy through uv.
    """
    source = LAUNCHER_SH.read_text()

    assert EXPECTED_COMMAND in source


def test_windows_launcher_disables_echo_and_delegates_to_uv_pypy_main():
    """
    Objective:
    The CMD launcher should explicitly run main.py using PyPy through uv.
    """
    source = LAUNCHER_CMD.read_text()

    assert source.lower().startswith("@echo off")
    assert EXPECTED_COMMAND in source


def test_launchers_do_not_import_or_execute_emulator_modules_directly():
    """
    Objective:
    Launchers should only delegate to uv. They should not import pygame, main.py, or
    emulator core modules themselves.
    """
    combined = LAUNCHER_SH.read_text() + "\n" + LAUNCHER_CMD.read_text()

    forbidden_fragments = [
        "import pygame",
        "import main",
        "from emulator",
        "python -m pytest",
    ]

    for fragment in forbidden_fragments:
        assert fragment not in combined


def test_launchers_do_not_change_project_default_python_runtime():
    """
    Objective:
    PyPy should remain explicit and opt-in. This step should not force the whole
    project to use PyPy through pyproject.toml.
    """
    pyproject = ROOT / "pyproject.toml"
    if not pyproject.exists():
        return

    source = pyproject.read_text()

    assert "python-preference" not in source
    assert "pypy" not in source.lower()

测试函数 (7)

test_linux_mac_pypy_launcher_exists_at_repo_root
test_windows_pypy_launcher_exists_at_repo_root
test_linux_mac_launcher_uses_sh_shebang
test_linux_mac_launcher_delegates_to_uv_pypy_main
test_windows_launcher_disables_echo_and_delegates_to_uv_pypy_main
test_launchers_do_not_import_or_execute_emulator_modules_directly
test_launchers_do_not_change_project_default_python_runtime