mini_arcade.modules.game_runner.processors ========================================== .. py:module:: mini_arcade.modules.game_runner.processors .. autoapi-nested-parse:: Game and example runner logic. Exceptions ---------- .. autoapisummary:: mini_arcade.modules.game_runner.processors.TargetMetadataError Classes ------- .. autoapisummary:: mini_arcade.modules.game_runner.processors.TargetSpec mini_arcade.modules.game_runner.processors.BaseTargetLocator mini_arcade.modules.game_runner.processors.GameLocator mini_arcade.modules.game_runner.processors.ExampleLocator mini_arcade.modules.game_runner.processors.GameRunnerProcessor Functions --------- .. autoapisummary:: mini_arcade.modules.game_runner.processors.load_game_meta mini_arcade.modules.game_runner.processors.load_example_meta Module Contents --------------- .. py:exception:: TargetMetadataError Bases: :py:obj:`RuntimeError` Raised when there is an error loading target metadata from pyproject.toml. .. py:function:: load_game_meta(game_dir: pathlib.Path) -> dict[str, Any] Load game metadata from pyproject.toml. The pyproject.toml must contain a [tool.mini-arcade.game] table with at least the following fields: - id (optional): The game id (defaults to the folder name if not provided). - entrypoint (optional): The relative path to the game's entrypoint script (defaults to "manage.py" if not provided). :param game_dir: The directory of the game to load metadata from. :type game_dir: Path :return: The game metadata as a dictionary. :rtype: dict[str, Any] :raises TargetMetadataError: If the pyproject.toml is missing or does not contain the required table. .. py:function:: load_example_meta(example_dir: pathlib.Path) -> dict[str, Any] Load example metadata from pyproject.toml, if present. This is optional for examples, but if provided, it must contain a [tool.mini-arcade.example] table. :param example_dir: The directory of the example to load metadata from. :type example_dir: Path :return: The example metadata as a dictionary. :rtype: dict[str, Any] :raises TargetMetadataError: If the pyproject.toml is missing or does not contain the required table. .. py:class:: TargetSpec Specification for a target (game or example) to run. :ivar kind: str: The kind of target ("game" or "example"). :ivar target_id: str: The id of the target (e.g. game id or example id). :ivar root_dir: Path: The root directory of the target. :ivar entrypoint: Path: The path to the entrypoint script to execute. :ivar meta: dict[str, Any]: The metadata loaded from pyproject.toml (for games) or inferred (for examples). .. py:attribute:: kind :type: str .. py:attribute:: target_id :type: str .. py:attribute:: root_dir :type: pathlib.Path .. py:attribute:: entrypoint :type: pathlib.Path .. py:attribute:: meta :type: dict[str, Any] .. py:class:: BaseTargetLocator(*, dev_default_parent_dir: pathlib.Path) Base class for locating a target (game or example) based on command arguments. :cvar kind: str: The kind of target this locator handles (e.g. "game" or "example"). Used in error messages and TargetSpec. .. py:attribute:: kind :type: str :value: 'target' .. py:method:: resolve_parent_dir(parent_override: Optional[str]) -> pathlib.Path Resolve the parent directory for the target, using the override if provided, or falling back to the dev default. :param parent_override: An optional string path to override the default parent directory. :type parent_override: Optional[str] :return: The resolved parent directory as a Path object. :rtype: Path :raises CommandException: If the provided override path does not exist or is not a directory. .. py:method:: find_dir(parent_dir: pathlib.Path, target_id: str) -> pathlib.Path Find the target directory under the parent directory. :param parent_dir: The parent directory to search under. :type parent_dir: Path :param target_id: The id/folder name of the target to find. :type target_id: str :return: The resolved path to the target directory. :rtype: Path :raises CommandException: If the target directory does not exist or is not a directory. .. py:method:: validate(target_dir: pathlib.Path) -> TargetSpec :abstractmethod: Validate the target directory and return a TargetSpec. :param target_dir: The directory of the target to validate. :type target_dir: Path :return: A TargetSpec instance with the validated target information. :rtype: TargetSpec .. py:class:: GameLocator(*, dev_default_parent_dir: pathlib.Path) Bases: :py:obj:`BaseTargetLocator` Game locator with TOML-DRIVEN validation. See validate() for the signature. :cvar kind: str: The kind of target this locator handles (e.g. "game" or "example"). Used in error messages and TargetSpec. .. py:attribute:: kind :value: 'game' .. py:method:: validate(target_dir: pathlib.Path) -> TargetSpec Validate the target directory and return a TargetSpec. :param target_dir: The directory of the target to validate. :type target_dir: Path :return: A TargetSpec instance with the validated target information. :rtype: TargetSpec .. py:class:: ExampleLocator(*, dev_default_parent_dir: pathlib.Path) Bases: :py:obj:`BaseTargetLocator` Example locator with CODE-DRIVEN validation. See validate() for the signature. :cvar kind: str: The kind of target this locator handles (e.g. "game" or "example"). Used in error messages and TargetSpec. .. py:attribute:: kind :value: 'example' .. py:method:: validate(target_dir: pathlib.Path) -> TargetSpec CODE-DRIVEN example validation: We do NOT require pyproject.toml. Signature for examples: - examples//main.py exists - OR examples//run_example.py exists - Optional: examples//src/ exists (added to PYTHONPATH if present) The entrypoint is always the shared runner: /examples/_shared/run_example.py The example_id is the folder name. .. py:class:: GameRunnerProcessor(**kwargs) Bases: :py:obj:`mini_arcade.cli.base_command_processor.BaseCommandProcessor` Processor for the "run" command, which can run either a game or an example based on the provided arguments. The processor validates the input arguments, locates the target game or example, builds the appropriate PYTHONPATH, and executes the target's entrypoint script with any additional passthrough arguments. It handles errors gracefully and provides informative messages for common issues such as missing targets or entrypoints. .. py:attribute:: game .. py:attribute:: example .. py:attribute:: from_source .. py:attribute:: examples_dir .. py:attribute:: pass_through .. py:method:: run() Run the command processor. :return: Optional result of the command execution. :rtype: Optional[Any]