ucbc-sdk 0.1.0__tar.gz

ucbc_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.3
+Name: ucbc-sdk
+Version: 0.1.0
+Summary: UCalgary Battlecode: the `ucbc` package a bot imports, one handle per game
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://ucbc.andrewheschl.ca
+Description-Content-Type: text/markdown
+
+# ucbc-sdk
+
+UCalgary Battlecode: the pure-Python `ucbc` package a bot imports, one typed handle per
+game. `pip install ucbc` brings it along with the engine and the `ucbc` command (Linux);
+install `ucbc-sdk` alone for types and completion on any platform.
+
+```python
+from ucbc.games.tictactoe import TicTacToeHandle
+
+
+def step(handle: TicTacToeHandle) -> None:
+    handle.place(*handle.empty_cells()[0])
+```
+
+https://ucbc.andrewheschl.ca

ucbc_sdk-0.1.0/README.md

@@ -0,0 +1,15 @@
+# ucbc-sdk
+
+UCalgary Battlecode: the pure-Python `ucbc` package a bot imports, one typed handle per
+game. `pip install ucbc` brings it along with the engine and the `ucbc` command (Linux);
+install `ucbc-sdk` alone for types and completion on any platform.
+
+```python
+from ucbc.games.tictactoe import TicTacToeHandle
+
+
+def step(handle: TicTacToeHandle) -> None:
+    handle.place(*handle.empty_cells()[0])
+```
+
+https://ucbc.andrewheschl.ca

ucbc_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["uv_build>=0.8,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "ucbc-sdk"
+version = "0.1.0"
+description = "UCalgary Battlecode: the `ucbc` package a bot imports, one handle per game"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed"]
+
+[project.urls]
+Homepage = "https://ucbc.andrewheschl.ca"
+
+[tool.uv.build-backend]
+module-name = "ucbc"
+module-root = ""

ucbc_sdk-0.1.0/ucbc/__init__.py

@@ -0,0 +1,3 @@
+"""UCalgary Battlecode: what a bot sees. ``ucbc.handle`` is the game-agnostic
+handle, ``ucbc.games.<game>`` the typed one a bot's ``step`` receives. Running
+matches is ``ucbc_engine``'s job."""

ucbc_sdk-0.1.0/ucbc/games/__init__.py

@@ -0,0 +1 @@
+"""One module per game. Each defines ``HANDLE``, the class a bot's ``step`` receives."""

ucbc_sdk-0.1.0/ucbc/games/tictactoe/__init__.py

@@ -0,0 +1,27 @@
+"""Tic-tac-toe as a bot sees it. A bot's ``step`` receives a :class:`TicTacToeHandle`:
+the generated queries and actions plus a few conveniences."""
+
+from ucbc.games.tictactoe._api import BoardView, Cell, Placed, TicTacToeApi
+
+__all__ = ["HANDLE", "BoardView", "Cell", "Placed", "TicTacToeHandle"]
+
+
+class TicTacToeHandle(TicTacToeApi):
+    def cell(self, row: int, col: int) -> Cell:
+        return self.board().cells[row * 3 + col]
+
+    def empty_cells(self) -> list[tuple[int, int]]:
+        return [(i // 3, i % 3) for i, c in enumerate(self.board().cells) if c == Cell.EMPTY]
+
+    @property
+    def me(self) -> Cell:
+        """The mark this bot plays."""
+        return self.board().you
+
+    @property
+    def turn(self) -> int:
+        """Marks placed so far this set."""
+        return self.board().turn
+
+
+HANDLE = TicTacToeHandle

ucbc_sdk-0.1.0/ucbc/games/tictactoe/_api.py

@@ -0,0 +1,66 @@
+"""Generated by `ucbc-dev gen-sdk` from the Rust types of the `tictactoe` game. Do not edit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Self
+
+from ucbc.handle import Handle
+
+
+@dataclass(frozen=True)
+class BoardView:
+    """What a bot sees when it asks for the board."""
+
+    cells: list[Cell]
+    you: Cell
+    """The mark this bot plays."""
+    to_move: Cell
+    turn: int
+    """Marks placed so far this set."""
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> Self:
+        return cls(
+            cells=[Cell(v) for v in d["cells"]],
+            you=Cell(d["you"]),
+            to_move=Cell(d["to_move"]),
+            turn=d["turn"],
+        )
+
+
+class Cell(str, Enum):
+    EMPTY = "empty"
+    X = "x"
+    O = "o"
+
+
+@dataclass(frozen=True)
+class Placed:
+    """The mark that was placed."""
+
+    row: int
+    col: int
+    mark: Cell
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> Self:
+        return cls(
+            row=d["row"],
+            col=d["col"],
+            mark=Cell(d["mark"]),
+        )
+
+
+class TicTacToeApi(Handle):
+    """Queries and actions of the `tictactoe` game, one method each."""
+
+    def board(self) -> BoardView:
+        """The board and whose turn it is."""
+        return BoardView._from(self._query({"type": "board"}))
+
+    def place(self, row: int, col: int) -> Placed:
+        """Place this bot's mark. Refused if the cell is taken or a mark was already
+        placed this step."""
+        return Placed._from(self._act({"type": "place", "row": row, "col": col}))

ucbc_sdk-0.1.0/ucbc/handle.py

@@ -0,0 +1,86 @@
+"""The game-agnostic side of what a bot's ``step(handle)`` receives: a handle to the
+one game the engine runs."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "ActionError",
+    "BridgeFn",
+    "Handle",
+    "Identity",
+    "QueryError",
+    "SetOver",
+]
+
+BridgeFn = Callable[[str, dict[str, Any]], dict[str, Any]]
+"""Sends one ``"query"`` or ``"act"`` payload to the engine and returns its reply."""
+
+
+class QueryError(Exception):
+    """The game refused a query."""
+
+
+class ActionError(Exception):
+    """The game refused an action. Nothing is forfeited; try something else."""
+
+
+class SetOver(ActionError):
+    """The set is already over."""
+
+
+@dataclass(frozen=True)
+class Identity:
+    bot_id: int
+    team: int
+    team_name: str
+    seed: int
+    game: str
+
+
+class Handle:
+    """Wraps the engine's bridge. Each game subclasses this with typed methods."""
+
+    def __init__(self, identity: Identity, bridge: BridgeFn) -> None:
+        self._identity = identity
+        self._bridge = bridge
+        self.set_index = 0
+        self.tick = 0
+        self.memory: dict[str, Any] = {}
+        """Persists across this bot's steps within a set."""
+
+    @property
+    def bot_id(self) -> int:
+        return self._identity.bot_id
+
+    @property
+    def team(self) -> int:
+        return self._identity.team
+
+    @property
+    def team_name(self) -> str:
+        return self._identity.team_name
+
+    @property
+    def seed(self) -> int:
+        """Per bot, per set; stable for a given match seed."""
+        return self._identity.seed
+
+    def _call(self, name: str, payload: dict[str, Any]) -> dict[str, Any]:
+        reply = self._bridge(name, payload)
+        if "err" in reply:
+            kind, message = reply["err"]["kind"], reply["err"]["message"]
+            if kind == "query":
+                raise QueryError(message)
+            if kind == "set_over":
+                raise SetOver(message)
+            raise ActionError(message)
+        response: dict[str, Any] = reply["ok"]
+        return response
+
+    def _query(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._call("query", payload)
+
+    def _act(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._call("act", payload)