diff --git a/README.md b/README.md index b554ac9..e8993bc 100644 --- a/README.md +++ b/README.md @@ -21,4 +21,27 @@ uv run pytest tests/games/classic uv run lost-cities-classic ``` +## Basic Usage + +```python +from coolrl_lost_cities.games.classic import GameState, build_bot, classic_config + +state = GameState.new_game(classic_config(seed=1)) +bot = build_bot("random", seed=1) + +while not state.terminal: + state.apply_action(bot.act(state)) + +print(state.total_score(0), state.total_score(1)) +``` + +Backends use the same snapshot/apply/undo interface: + +```python +from coolrl_lost_cities.games.classic import build_backend, classic_config + +backend = build_backend("python", classic_config(), seed=1) +snapshot = backend.snapshot() +``` + See [classic port notes](docs/classic-port-notes.md) for the current direction. diff --git a/pyproject.toml b/pyproject.toml index 4523017..c914c60 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "coolrl-lost-cities" version = "0.1.0" -description = "Add your description here" +description = "Focused Lost Cities classic game extraction" readme = "README.md" authors = [ { name = "정시원", email = "sebastianrcnt@gmail.com" } diff --git a/setup.py b/setup.py index ee216a7..0b671ee 100644 --- a/setup.py +++ b/setup.py @@ -4,27 +4,25 @@ from setuptools import Extension, setup try: from Cython.Build import cythonize -except ImportError: # pragma: no cover - cythonize = None +except ImportError as exc: # pragma: no cover + raise RuntimeError("Cython is required to build coolrl-lost-cities") from exc -extensions: list[Extension] = [] -if cythonize is not None: - extensions = cythonize( - [ - Extension( - "coolrl_lost_cities.games.classic.game", - ["src/coolrl_lost_cities/games/classic/game.pyx"], - ) - ], - language_level=3, - compiler_directives={ - "boundscheck": False, - "wraparound": False, - "cdivision": True, - "initializedcheck": False, - }, - ) +extensions = cythonize( + [ + Extension( + "coolrl_lost_cities.games.classic.game", + ["src/coolrl_lost_cities/games/classic/game.pyx"], + ) + ], + language_level=3, + compiler_directives={ + "boundscheck": False, + "wraparound": False, + "cdivision": True, + "initializedcheck": False, + }, +) setup(ext_modules=extensions) diff --git a/src/coolrl_lost_cities/games/classic/__init__.py b/src/coolrl_lost_cities/games/classic/__init__.py index 5418e6a..984dd22 100644 --- a/src/coolrl_lost_cities/games/classic/__init__.py +++ b/src/coolrl_lost_cities/games/classic/__init__.py @@ -1,13 +1,37 @@ from __future__ import annotations -from .game import Card, GameState, IllegalMoveError, LostCitiesConfig, classic_config +from .backends import build_backend +from .bots import ( + LostCitiesBot, + available_bot_names, + build_bot, + play_game, + run_series, +) +from .env import LostCitiesEnv +from .game import ( + GameState, + IllegalMoveError, + LostCitiesConfig, + classic_config, +) +from .interfaces import BackendName, LostCitiesBackend, Snapshot __all__ = [ - "Card", + "BackendName", "GameState", "IllegalMoveError", + "LostCitiesBackend", + "LostCitiesBot", "LostCitiesConfig", + "LostCitiesEnv", + "Snapshot", + "available_bot_names", + "build_backend", + "build_bot", "classic_config", + "play_game", + "run_series", ] diff --git a/src/coolrl_lost_cities/games/classic/backends/__init__.py b/src/coolrl_lost_cities/games/classic/backends/__init__.py index da19037..9499102 100644 --- a/src/coolrl_lost_cities/games/classic/backends/__init__.py +++ b/src/coolrl_lost_cities/games/classic/backends/__init__.py @@ -1,11 +1,11 @@ from __future__ import annotations -from .factory import build_lost_cities_backend +from .factory import build_backend from .python import PythonLostCitiesBackend from .rust import RustLostCitiesBackend __all__ = [ "PythonLostCitiesBackend", "RustLostCitiesBackend", - "build_lost_cities_backend", + "build_backend", ] diff --git a/src/coolrl_lost_cities/games/classic/backends/factory.py b/src/coolrl_lost_cities/games/classic/backends/factory.py index f31ffc0..070104e 100644 --- a/src/coolrl_lost_cities/games/classic/backends/factory.py +++ b/src/coolrl_lost_cities/games/classic/backends/factory.py @@ -6,7 +6,7 @@ from .python import PythonLostCitiesBackend from .rust import RustLostCitiesBackend -def build_lost_cities_backend( +def build_backend( backend: BackendName, config: LostCitiesConfig, seed: int | None, diff --git a/tests/games/classic/test_public_api.py b/tests/games/classic/test_public_api.py new file mode 100644 index 0000000..dcb0ead --- /dev/null +++ b/tests/games/classic/test_public_api.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +import coolrl_lost_cities.games.classic as classic + + +def test_classic_package_exports_common_game_api() -> None: + config = classic.classic_config(seed=1) + state = classic.GameState.new_game(config) + bot = classic.build_bot("random", seed=1) + + action = bot.act(state) + assert state.unified_legal_mask()[state.to_unified_action(action)] + assert state.config.deck_size == 60 + + +def test_classic_package_exports_backend_alias() -> None: + backend = classic.build_backend("python", classic.classic_config(), seed=1) + + assert isinstance(backend.snapshot(), classic.Snapshot) + + +def test_classic_package_exports_bot_registry_helpers() -> None: + assert "random" in classic.available_bot_names() + assert isinstance(classic.build_bot("random", seed=1), classic.LostCitiesBot)