From 361420df7a17e56003c3aed2d55df5f98eeb42a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=A0=95=EC=8B=9C=EC=9B=90?= Date: Wed, 6 May 2026 19:21:17 +0900 Subject: [PATCH] =?UTF-8?q?=ED=81=B4=EB=9E=98=EC=8B=9D=20=EA=B3=B5?= =?UTF-8?q?=EA=B0=9C=20API=20=EC=A0=95=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 맥락: - GUI 이식 전에 classic 패키지 루트에서 노출할 API 범위를 정리했다. - Claude Opus 4.7 xhigh 자문에서 root export 축소와 backend builder 이름 단일화를 우선 권장했다. 변경: - classic package root export를 GameState, config, env, backend, bot registry 중심으로 줄였다. - backend factory 이름을 build_backend로 단일화하고 README 사용 예시를 갱신했다. - public API smoke test를 추가하고 pyproject description 및 Cython build failure 처리를 정리했다. 확인: - uv run pytest tests/games/classic - uv run lost-cities-classic --- README.md | 23 ++++++++++++ pyproject.toml | 2 +- setup.py | 36 +++++++++---------- .../games/classic/__init__.py | 28 +++++++++++++-- .../games/classic/backends/__init__.py | 4 +-- .../games/classic/backends/factory.py | 2 +- tests/games/classic/test_public_api.py | 24 +++++++++++++ 7 files changed, 94 insertions(+), 25 deletions(-) create mode 100644 tests/games/classic/test_public_api.py 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)