317. Lanzadores de PyPy

Añade lanzadores explícitos de PyPy para la ejecución manual.

Lección 317 de 356 · tests/chapter_10_performance/test_317_pypy_launchers.py

Archivos a crear en la raíz del repositorio

launcher.sh
launcher.cmd

Por qué existe este paso

PyPy puede mejorar el rendimiento del núcleo del emulador porque gran parte del emulador es código Python que se ejecuta en bucles ajustados. En lugar de cambiar pyproject.toml o forzar a todos los estudiantes a usar PyPy por defecto, este paso añade lanzadores manuales explícitos.

Después de crear estos lanzadores, los estudiantes deberían usarlos para experimentos manuales de rendimiento en lugar de lanzar main.py directamente con CPython.

Uso en Linux/macOS

sh launcher.sh

o, si se añadió permiso de ejecución:

chmod +x launcher.sh
./launcher.sh

Uso en el símbolo del sistema de Windows

launcher.cmd

Señal manual esperada

El contador de FPS añadido anteriormente debería mejorar cuando el núcleo del emulador se beneficie de PyPy. Tras la ruta de carga del framebuffer con pygame más rápida, PyPy puede hacer que el emulador funcione más rápido que la velocidad real de NES. Durante el desarrollo del tutorial, la combinación de la ruta de dibujado con pygame más rápida y PyPy alcanzó aproximadamente 90-120 FPS en la ruta manual de la ROM.

El número exacto depende de la máquina y del estado de la ROM, pero la salida de FPS en el terminal es ahora la evidencia con la que comparar:

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

Si los FPS ahora están por encima de la velocidad de NES, eso es una buena evidencia de que el siguiente paso debería añadir ritmo de fotogramas / control de velocidad esperada para que el juego manual no vaya demasiado rápido.

Comando esperado delegado por ambos lanzadores

uv run --python pypy python main.py

Ejemplo en 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

Ejemplo en CMD de Windows

@echo off

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

uv run --python pypy python main.py

Regla de test importante

Estos tests no deben ejecutar los lanzadores. Ejecutarlos iniciaría el frontend manual de pygame y requeriría un archivo de ROM local. Solo inspeccionamos los archivos como texto.

Fuera de alcance

cambiar el Python por defecto en pyproject.toml
lanzar PyPy desde pytest
abrir ventanas de pygame
medir FPS
optimizar el renderizado

Ejecutar esta lección

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

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()