Codenames
Code infrastructure for the Codenames board game.
Designed to serve as a base for implementing players (agents) with different strategies and algorithms.
See the codenames-solvers repository for such examples.
Game rules:
Installation
Install from PyPI using pip: pip install codenames
Usage
Here is a simple example of command-line based players, and a GameRunner that runs a game between them:
import logging
import sys
from codenames.classic.board import ClassicBoard
from codenames.classic.player import ClassicOperative, ClassicSpymaster
from codenames.classic.runner import ClassicGamePlayers, ClassicGameRunner
from codenames.classic.state import ClassicOperativeState, ClassicSpymasterState
from codenames.classic.team import ClassicTeam
from codenames.generic.move import Clue, Guess
from codenames.utils.vocabulary.languages import get_vocabulary
####################################
# Naive CLI players implementation #
####################################
class CLISpymaster(ClassicSpymaster):
def give_clue(self, game_state: ClassicSpymasterState) -> Clue:
print("\nGive a hint. Board: \n" + game_state.board.printable_string)
print(f"Revealed cards: {list(game_state.board.revealed_card_indexes)}")
hint_word = input("Enter hint word: ")
card_amount = int(input("Enter card amount: "))
return Clue(word=hint_word, card_amount=card_amount)
class CLIOperative(ClassicOperative):
def guess(self, game_state: ClassicOperativeState) -> Guess:
print(f"\nGuess a card. Given clue: {game_state.current_clue}. Current board state: ")
print(game_state.board.printable_string)
card_word = input("Enter card word: ")
card_index = game_state.board.find_card_index(word=card_word)
return Guess(card_index=card_index)
############
# Run Game #
############
def run_classic_cli_game():
# Init players
blue_spymaster = CLISpymaster(name="Yoda", team=ClassicTeam.BLUE)
blue_operative = CLIOperative(name="Luke", team=ClassicTeam.BLUE)
red_spymaster = CLISpymaster(name="Einstein", team=ClassicTeam.RED)
red_operative = CLIOperative(name="Newton", team=ClassicTeam.RED)
players = ClassicGamePlayers.from_collection(blue_spymaster, blue_operative, red_spymaster, red_operative)
# Init board
vocabulary = get_vocabulary(language="english")
board = ClassicBoard.from_vocabulary(vocabulary=vocabulary)
# Run game
runner = ClassicGameRunner(players=players, board=board)
winner = runner.run_game()
print(f"Winner: {winner}")
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stdout)
run_classic_cli_game()
Example output:
-----
[RED] turn.
Give a hint. Board:
+-----------+-------------+------------+-----------------+------------+
| 🟦 pretty | ⬜ young | ⬜ essay | 🟥 apple | ⬜ kiss |
+-----------+-------------+------------+-----------------+------------+
| ⬜ poem | 🟦 solve | 🟥 pan | 🟦 organization | 🟦 union |
+-----------+-------------+------------+-----------------+------------+
| 🟥 myth | 🟥 neck | 🟥 shelter | 🟦 locate | 🟥 pet |
+-----------+-------------+------------+-----------------+------------+
| 🟥 react | ⬜ person | ⬜ mood | 🟥 heart | ⬜ breath |
+-----------+-------------+------------+-----------------+------------+
| 🟥 rich | 🟦 standard | 🟦 crop | 💀 chicken | 🟦 wedding |
+-----------+-------------+------------+-----------------+------------+
Revealed cards: []
Enter hint word: example
Enter card amount: 2
Spymaster: [example] 2 card(s)
Guess a card. Given clue: [example] [2]. Current board state:
+--------+----------+---------+--------------+---------+
| pretty | young | essay | apple | kiss |
+--------+----------+---------+--------------+---------+
| poem | solve | pan | organization | union |
+--------+----------+---------+--------------+---------+
| myth | neck | shelter | locate | pet |
+--------+----------+---------+--------------+---------+
| react | person | mood | heart | breath |
+--------+----------+---------+--------------+---------+
| rich | standard | crop | chicken | wedding |
+--------+----------+---------+--------------+---------+
Enter card word: heart
Operative: '🟥 heart', correct!
Guess a card. Given clue: [example] [2]. Current board state:
+--------+----------+---------+--------------+---------+
| pretty | young | essay | apple | kiss |
+--------+----------+---------+--------------+---------+
| poem | solve | pan | organization | union |
+--------+----------+---------+--------------+---------+
| myth | neck | shelter | locate | pet |
+--------+----------+---------+--------------+---------+
| react | person | mood | 🟥 heart | breath |
+--------+----------+---------+--------------+---------+
| rich | standard | crop | chicken | wedding |
+--------+----------+---------+--------------+---------+
Enter card word: pet
Operative: '🟥 pet', correct!
Guess a card. Given clue: [example] [2]. Current board state:
+--------+----------+---------+--------------+---------+
| pretty | young | essay | apple | kiss |
+--------+----------+---------+--------------+---------+
| poem | solve | pan | organization | union |
+--------+----------+---------+--------------+---------+
| myth | neck | shelter | locate | 🟥 pet |
+--------+----------+---------+--------------+---------+
| react | person | mood | 🟥 heart | breath |
+--------+----------+---------+--------------+---------+
| rich | standard | crop | chicken | wedding |
+--------+----------+---------+--------------+---------+
Enter card word: mood
Operative: '⬜ mood', wrong!
Operative wrong, turn is over
-----
[BLUE] turn.
Give a hint. Board:
+-----------+-------------+------------+-----------------+------------+
| 🟦 pretty | ⬜ young | ⬜ essay | 🟥 apple | ⬜ kiss |
+-----------+-------------+------------+-----------------+------------+
| ⬜ poem | 🟦 solve | 🟥 pan | 🟦 organization | 🟦 union |
+-----------+-------------+------------+-----------------+------------+
| 🟥 myth | 🟥 neck | 🟥 shelter | 🟦 locate | 🟥 pet |
+-----------+-------------+------------+-----------------+------------+
| 🟥 react | ⬜ person | ⬜ mood | 🟥 heart | ⬜ breath |
+-----------+-------------+------------+-----------------+------------+
| 🟥 rich | 🟦 standard | 🟦 crop | 💀 chicken | 🟦 wedding |
+-----------+-------------+------------+-----------------+------------+
Revealed cards: [14, 17, 18]
Enter hint word:
......
1 maintainer
Release files for codenames 5.5.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| codenames-5.5.5.tar.gz | 38.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| codenames-5.5.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 87.9 kB
Release files / codenames-5.5.5.tar.gz
| Download URL | codenames-5.5.5.tar.gz |
|---|---|
| Size | 38.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
922647a566a0d2d66466b23c5780194bb87e8555142753adf0534858dbab5af5
|
|
BLAKE2b-256 checksum How to use checksums |
e149832a0f9781e9890323c812075603045ba0879dcde20550cd574bb2d7d5d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2025.
Transparency logRelease files / codenames-5.5.5-py3-none-any.whl
| Download URL | codenames-5.5.5-py3-none-any.whl |
|---|---|
| Size | 49.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
80a413852fc349d5c4a4bb450c8de4690e9c145a4a3b0a75953a1125a9d3ecf8
|
|
BLAKE2b-256 checksum How to use checksums |
ba3a45ae3970a223f5fd8cc3b32e50a89dcd0a4afc9e610806bea44604d37a49
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 22, 2025.
Transparency log
