Add PyBananas docstrings and update README.md

Author: mdeclerk

PyBananas/README.md

@@ -2,15 +2,13 @@
 
 PyBananas is a Python wrapper of Bananas ROM for AI/ML training tasks.
 
-## Usage
-
-Install wheel packges:
+## Install PIP Wheel
 
 ```bash
-pip install https://github.com/mdeclerk/Bananas/releases/latest/download/pybananas-0.1.0-py3-none-any.whl
+pip install https://github.com/mdeclerk/Bananas/releases/latest/download/pybananas-0.1.1-py3-none-any.whl
 ```
 
-Use in code:
+## Quickstart
 
 ```python
 from pybananas import BananasEnv, GameInput, GameStateEnum
@@ -23,9 +21,26 @@ with BananasEnv() as env:
     print(f"P1: {state.players[0].score} pts, {state.players[0].lives} lives")
 ```
 
-## Pixi Build Workflow
+## PyBananas API
+
+
+| API | Purpose |
+| --- | --- |
+| `BananasEnv(window="null", frame_skip=4, ...)` | Create a headless training environment. |
+| `env.reset()` | Start a randomized episode and return the first observation. |
+| `env.step(action)` | Apply `GameInput` or an 8-value button array and return the next observation. |
+| `env.observe()` | Read the current frame without stepping. |
+| `env.game_state()` | Read decoded scores, lives, terrain, projectile, and turn state. |
+| `env.tick(count=1, render=True)` | Manually advance emulator frames. |
+| `env.set_emulation_speed(speed)` | Set emulator speed; `0` means unlimited. |
+| `env.close()` | Stop the emulator. |
+
+Observations are grayscale `uint8` arrays with shape `(144, 160)` and values
+`0..3`. Action arrays use `(UP, DOWN, LEFT, RIGHT, A, B, START, SELECT)` order.
+
+## Pixi Build Environment
 
-Install [Pixi](https://pixi.sh) as dev environment and task runner.
+Install [Pixi](https://pixi.sh) as dev environment and task runner for PyBananas.
 
 ```bash
 cd PyBananas
@@ -37,4 +52,4 @@ pixi run test               # run tests
 pixi run play               # play in PyBoy for testing
 ```
 
-Commands are also available as VS Code tasks via **Terminal → Run Task**.
+Commands are also available as VS Code tasks via **Terminal → Run Task**.

PyBananas/pixi.lock

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pybananas"
-version = "0.1.0"
+version = "0.1.1"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
@@ -52,4 +52,4 @@ depends-on = ["build-rom"]
 
 [tool.pixi.tasks.test]
 cmd = "pytest -v"
-depends-on = ["build-rom"]
+depends-on = ["build-rom"]

PyBananas/pyproject.toml

@@ -1,5 +1,3 @@
-"""Open an interactive PyBoy window for playing Bananas."""
-
 from __future__ import annotations
 
 from .env import BananasEnv

PyBananas/src/pybananas/__main__.py

@@ -36,12 +36,12 @@
 
 
 class BananasEnv:
-    """PyBoy wrapper for bananas.gb.
+    """Headless PyBoy environment for the Bananas ROM.
 
-    Observation: grayscale (144, 160) uint8 in [0, 3] (0 = lightest).
-    Action: a `GameInput` (preferred) or any length-8 bool/0-1 sequence over
-    (UP, DOWN, LEFT, RIGHT, A, B, START, SELECT).
-    Step: presses the action mask for `frame_skip` ticks, then releases it.
+    Observations are grayscale ``uint8`` arrays with shape ``(144, 160)`` and
+    values ``0..3`` where ``0`` is lightest. Actions are either ``GameInput``
+    values or length-8 bool/0-1 sequences in ``(UP, DOWN, LEFT, RIGHT, A, B,
+    START, SELECT)`` order.
     """
 
     def __init__(
@@ -54,6 +54,22 @@ def __init__(
         sound: bool = False,
         no_input: bool = True,
     ) -> None:
+        """Create a Bananas environment.
+
+        Args:
+            rom_path: Optional path to a ``.gb`` ROM. Defaults to the packaged
+                Bananas ROM.
+            window: PyBoy window backend. Use ``"null"`` for headless training.
+            scale: Display scale used when a visible PyBoy window is enabled.
+            frame_skip: Emulator frames advanced by each ``step`` call.
+            skip_splash: If true, advance from the splash screen to gameplay.
+            sound: Whether PyBoy should emulate sound.
+            no_input: Whether PyBoy should ignore host keyboard input.
+
+        Raises:
+            FileNotFoundError: If the ROM or matching ``.sym`` file is missing.
+            ValueError: If ``frame_skip`` is less than 1.
+        """
         if rom_path is not None:
             rom = validate_rom(Path(rom_path))
         else:
@@ -91,10 +107,16 @@ def __init__(
     # ------------------------------------------------------------------ core
 
     def reset(self) -> np.ndarray:
-        """Reload the boot state, idle a random number of frames on the splash
-        screen so the hardware DIV register varies, then press START.  The game
-        seeds its RNG from DIV_REG at the moment START is pressed, producing
-        unique terrain each episode."""
+        """Start a new randomized episode and return the first observation.
+
+        Reloads the boot state, idles for a random number of splash-screen
+        frames, then presses START. This varies the hardware DIV register used
+        by the game seed so terrain changes between episodes.
+
+        Returns:
+            Grayscale ``uint8`` observation with shape ``(144, 160)`` and
+            values ``0..3``.
+        """
         self._pyboy.load_state(io.BytesIO(self._boot_state))
         warmup = int(self._rng.integers(0, SPLASH_WARMUP_MAX))
         self._pyboy.tick(count=warmup, render=False)
@@ -103,6 +125,18 @@ def reset(self) -> np.ndarray:
         return self.observe()
 
     def step(self, action) -> np.ndarray:
+        """Apply an action for one environment step.
+
+        Args:
+            action: ``GameInput`` or any length-8 bool/0-1 sequence in
+                ``(UP, DOWN, LEFT, RIGHT, A, B, START, SELECT)`` order.
+
+        Returns:
+            Next grayscale ``uint8`` observation with shape ``(144, 160)``.
+
+        Raises:
+            ValueError: If ``action`` is not a valid 8-button mask.
+        """
         mask = _action_mask(action)
         pressed = [name for bit, name in zip(mask, BUTTON_NAMES, strict=True) if bit]
         for name in pressed:
@@ -115,41 +149,63 @@ def step(self, action) -> np.ndarray:
         return self.observe()
 
     def observe(self) -> np.ndarray:
+        """Return the current frame without advancing the emulator.
+
+        Returns:
+            Grayscale ``uint8`` observation with shape ``(144, 160)`` and
+            values ``0..3``.
+        """
         return (255 - self._pyboy.screen.ndarray[..., 0]) >> 6
 
     # ---------------------------------------------------------------- state
 
     def game_state(self) -> GameState:
+        """Return the decoded game state from emulator memory."""
         return decode_game_state(self.g_game_bytes())
 
     def g_game_bytes(self) -> bytes:
+        """Return raw bytes for the ROM's ``g_game`` state struct."""
         return bytes(self._pyboy.memory[self._g_game_addr : self._g_game_addr + GAME_STATE_SIZE])
 
     @property
     def g_game_addr(self) -> int:
+        """Memory address of the ROM's ``g_game`` state struct."""
         return self._g_game_addr
 
     # ----------------------------------------------------------- emulation
 
     def tick(self, count: int = 1, render: bool = True) -> bool:
-        """Advance the emulator by *count* frames.
+        """Advance the emulator by ``count`` frames.
 
-        Returns ``False`` when the emulator window has been closed.
+        Args:
+            count: Number of emulator frames to advance.
+            render: Whether PyBoy should render frames while ticking.
+
+        Returns:
+            ``False`` when the emulator window has been closed, otherwise
+            ``True``.
         """
         return self._pyboy.tick(count=count, render=render)
 
     def set_emulation_speed(self, speed: int) -> None:
-        """Set the target emulation speed (1 = real-time, 0 = unlimited)."""
+        """Set target emulation speed.
+
+        Args:
+            speed: PyBoy speed multiplier. ``1`` is real-time; ``0`` is
+                unlimited.
+        """
         self._pyboy.set_emulation_speed(speed)
 
     # -------------------------------------------------------------- lifecycle
 
     def close(self) -> None:
+        """Stop the PyBoy emulator and release environment resources."""
         if self._pyboy is not None:
             self._pyboy.stop()
             self._pyboy = None  # type: ignore[assignment]
 
     def __enter__(self) -> BananasEnv:
+        """Return this environment for ``with`` statement use."""
         return self
 
     def __exit__(
@@ -158,6 +214,7 @@ def __exit__(
         exc: BaseException | None,
         tb: TracebackType | None,
     ) -> None:
+        """Close the environment when leaving a ``with`` block."""
         self.close()
 
 
@@ -166,7 +223,6 @@ def __exit__(
 
 
 def skip_through_splash(pyboy: PyBoy, g_game_addr: int) -> None:
-    """Pulse START until g_game.state == AIM and players[0].lives == 3."""
     for _ in range(0, SPLASH_MAX_FRAMES, 8):
         if _in_game(pyboy, g_game_addr):
             return

PyBananas/src/pybananas/env.py

@@ -1,5 +1,3 @@
-"""Button enum + GameInput: composable, named-button replacement for raw arrays."""
-
 from __future__ import annotations
 
 from dataclasses import dataclass, fields
@@ -16,6 +14,8 @@
 
 
 class Button(IntEnum):
+    """Game Boy controller button index used by action arrays."""
+
     UP = 0
     DOWN = 1
     LEFT = 2
@@ -32,11 +32,11 @@ class GameInput:
 
     Construct one of three ways:
 
-        GameInput()                                 # no buttons (alias: GameInput.NOOP)
-        GameInput(a=True, up=True)                  # kwargs
-        GameInput.A | GameInput.UP                  # combine named singletons
+        ``GameInput()``                       # no buttons
+        ``GameInput(a=True, up=True)``        # keyword flags
+        ``GameInput.A | GameInput.UP``        # combine named singletons
 
-    `BananasEnv.step` accepts both `GameInput` and raw 8-element arrays.
+    ``BananasEnv.step`` accepts both ``GameInput`` and raw 8-element arrays.
     """
 
     up: bool = False
@@ -61,15 +61,26 @@ class GameInput:
 
     @classmethod
     def from_buttons(cls, *buttons: Button) -> "GameInput":
-        """`GameInput.from_buttons(Button.A, Button.UP)`."""
+        """Create an input from one or more ``Button`` values."""
         kwargs: dict[str, bool] = {}
         for btn in buttons:
             kwargs[BUTTON_NAMES[Button(btn).value]] = True
         return cls(**kwargs)
 
     @classmethod
     def from_array(cls, arr) -> "GameInput":
-        """Inverse of `to_array()`; accepts any 8-element bool/0-1 sequence."""
+        """Create an input from an 8-value button mask.
+
+        Args:
+            arr: Bool/0-1 sequence in ``(UP, DOWN, LEFT, RIGHT, A, B, START,
+                SELECT)`` order.
+
+        Returns:
+            Equivalent ``GameInput`` instance.
+
+        Raises:
+            ValueError: If ``arr`` is not a valid 8-button mask.
+        """
         a = np.asarray(arr)
         if a.shape != (ACTION_SIZE,):
             raise ValueError(f"expected shape ({ACTION_SIZE},), got {a.shape}")
@@ -78,26 +89,28 @@ def from_array(cls, arr) -> "GameInput":
         return cls(**{name: bool(a[i]) for i, name in enumerate(BUTTON_NAMES)})
 
     def to_array(self) -> np.ndarray:
-        """Length-8 uint8 array in (UP, DOWN, LEFT, RIGHT, A, B, START, SELECT) order."""
+        """Return a length-8 ``uint8`` button mask in canonical button order."""
         return np.array(
             [getattr(self, name) for name in BUTTON_NAMES],
             dtype=np.uint8,
         )
 
     def pressed(self) -> tuple[Button, ...]:
-        """Buttons currently down, in canonical order."""
+        """Return pressed buttons in canonical button order."""
         return tuple(
             Button(i) for i, name in enumerate(BUTTON_NAMES) if getattr(self, name)
         )
 
     def __or__(self, other: "GameInput") -> "GameInput":
+        """Combine two button sets."""
         if not isinstance(other, GameInput):
             return NotImplemented
         return GameInput(
             **{name: getattr(self, name) or getattr(other, name) for name in BUTTON_NAMES}
         )
 
     def __iter__(self) -> Iterator[bool]:
+        """Iterate button states in canonical button order."""
         # Lets `np.asarray(game_input)` work transparently.
         return (getattr(self, name) for name in BUTTON_NAMES)
 

PyBananas/src/pybananas/input.py

@@ -33,7 +33,6 @@
 
 
 def validate_rom(rom: Path = BANANAS_ROM) -> Path:
-    """Validate ROM and .sym exist. Returns the rom path."""
     if not rom.exists():
         raise FileNotFoundError(
             f"ROM not found: {rom}\n"
@@ -49,7 +48,6 @@ def validate_rom(rom: Path = BANANAS_ROM) -> Path:
 
 
 def resolve_symbol(rom: Path, name: str) -> int:
-    """Look up `name` in the .sym file (`bank:addr name`)."""
     sym = rom.with_suffix(".sym")
     for line in sym.read_text().splitlines():
         parts = line.strip().split()