catanatron.models package¶

Submodules¶

catanatron.models.actions module¶

Move-generation functions (these return a list of actions that can be taken by current player). Main function is generate_playable_actions.

catanatron.models.actions.city_possibilities(state, color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.discard_possibilities(color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.generate_playable_actions(state) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.initial_road_possibilities(state, color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.inner_maritime_trade_possibilities(hand_freqdeck, bank_freqdeck, port_resources)¶: This inner function is to make this logic more shareable

catanatron.models.actions.maritime_trade_possibilities(state, color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.monopoly_possibilities(color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.ncr(n, r)¶: n choose r. helper for discard_possibilities

catanatron.models.actions.road_building_possibilities(state, color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.robber_possibilities(state, color) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.settlement_possibilities(state, color, initial_build_phase=False) → List[catanatron.models.enums.Action]¶

catanatron.models.actions.year_of_plenty_possibilities(color, freqdeck: List[int]) → List[catanatron.models.enums.Action]¶

catanatron.models.board module¶

class catanatron.models.board.Board(catan_map=None, initialize=True)¶

Bases: object

Encapsulates all state information regarding the board.

buildings¶

Mapping from node id to building (if there is a building there).

Type: Dict[NodeId, Tuple[Color, FastBuildingType]]

roads¶

Mapping from edge to Color (if there is a road there). Contains inverted edges as well for ease of querying.

Type: Dict[EdgeId, Color]

connected_components¶

Cache datastructure to speed up mantaining longest road computation. To be queried by Color. Value is a list of node sets.

Type: Dict[Color, List[Set[NodeId]]]

board_buildable_ids¶

Cache of buildable node ids in board.

Type: Set[NodeId]

road_color¶

Color of player with longest road.

Type: Color

road_length¶

Number of roads of longest road

Type: int

robber_coordinate¶

Coordinate where robber is.

Type: Coordinate

bfs_walk(node_id, color)¶

Generates set of nodes that are “connected” to given node.

Parameters

node_id (int) – Where to start search/walk.
color (Color) – Player color asking

Returns

Nodes that are “connected” to this one: by roads of the color player.

Return type

Set[int]

build_city(color, node_id)¶

build_road(color, edge)¶

build_settlement(color, node_id, initial_build_phase=False)¶

Adds a settlement, and ensures is a valid place to build.

Parameters

color (Color) – player’s color
node_id (int) – where to build
initial_build_phase (bool, optional) – Whether this is part of initial building phase, so as to skip connectedness validation. Defaults to True.

buildable_edges(color: catanatron.models.player.Color)¶: List of (n1,n2) tuples. Edges are in n1 < n2 order.

buildable_node_ids(color: catanatron.models.player.Color, initial_build_phase=False)¶

continuous_roads_by_player(color: catanatron.models.player.Color)¶

copy()¶

find_connected_components(color: catanatron.models.player.Color)¶

Returns

connected subgraphs. subgraphs: might include nodes that color doesnt own (on the way and on ends), just to make it is “closed” and easier for buildable_nodes to operate.

Return type

nx.Graph[]

get_edge_color(edge)¶

get_node_color(node_id)¶

get_player_port_resources(color)¶: Yields resources (None for 3:1) of ports owned by color

is_enemy_node(node_id, color)¶

is_enemy_road(edge, color)¶

catanatron.models.board.get_edges(land_nodes=None)¶

catanatron.models.board.get_node_distances()¶

catanatron.models.board.longest_acyclic_path(board: catanatron.models.board.Board, node_set: Set[int], color: catanatron.models.player.Color)¶

catanatron.models.coordinate_system module¶

class catanatron.models.coordinate_system.Direction(value)¶

Bases: enum.Enum

An enumeration.

EAST = 'EAST'¶

NORTHEAST = 'NORTHEAST'¶

NORTHWEST = 'NORTHWEST'¶

SOUTHEAST = 'SOUTHEAST'¶

SOUTHWEST = 'SOUTHWEST'¶

WEST = 'WEST'¶

catanatron.models.coordinate_system.add(acoord, bcoord)¶

catanatron.models.coordinate_system.cube_to_axial(cube)¶

catanatron.models.coordinate_system.cube_to_offset(cube)¶

catanatron.models.coordinate_system.generate_coordinate_system(num_layers)¶: Generates a set of coordinates by expanding outward from a center tile on (0,0,0) with the given number of layers (as in an onion :)). Follows BFS.

catanatron.models.coordinate_system.num_tiles_for(layer)¶: Including inner-layer tiles

catanatron.models.coordinate_system.offset_to_cube(offset)¶

catanatron.models.decks module¶

catanatron.models.decks.draw_from_listdeck(list1: List, amount: int, card: int)¶

catanatron.models.decks.freqdeck_add(list1, list2)¶

catanatron.models.decks.freqdeck_can_draw(freqdeck, amount: int, card: Literal[WOOD, BRICK, SHEEP, WHEAT, ORE])¶

catanatron.models.decks.freqdeck_contains(list1, list2)¶: True if list1 >= list2 element-wise

catanatron.models.decks.freqdeck_count(freqdeck, card: Literal[WOOD, BRICK, SHEEP, WHEAT, ORE])¶

catanatron.models.decks.freqdeck_draw(freqdeck, amount: int, card: Literal[WOOD, BRICK, SHEEP, WHEAT, ORE])¶

catanatron.models.decks.freqdeck_from_listdeck(listdeck: Iterable[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]])¶

catanatron.models.decks.freqdeck_replenish(freqdeck, amount: int, card: Literal[WOOD, BRICK, SHEEP, WHEAT, ORE])¶

catanatron.models.decks.freqdeck_subtract(list1, list2)¶

catanatron.models.decks.starting_devcard_bank()¶: Returns listdeck of devcards

catanatron.models.decks.starting_devcard_proba(card: Literal[KNIGHT, YEAR_OF_PLENTY, MONOPOLY, ROAD_BUILDING, VICTORY_POINT])¶

catanatron.models.decks.starting_resource_bank()¶: Returns freqdeck of resource cards

catanatron.models.enums module¶

class catanatron.models.enums.Action(color, action_type, value)¶

Bases: tuple

Main class to represent action. Should be immutable.

The “value” is a polymorphic field that acts as the “parameters” for the “action_type”. e.g. where to ActionType.BUILD_SETTLEMENT or who to steal from in a ActionType.MOVE_ROBBER action.

We use this class to represent both the _intent_ of say “moving a robber to Tile (0,0,0) and stealing from Blue” as well as the final result of such a move. In moves like these where the intent is not enough to be used to reproduce the game identically, we use `None`s in the “value” container as placeholders for that information needed for fully reproducing a game. (e.g. card stolen, dev card bought, etc…)

See more on ActionType.

action_type¶: Alias for field number 1

color¶: Alias for field number 0

value¶: Alias for field number 2

class catanatron.models.enums.ActionPrompt(value)¶

Bases: enum.Enum

An enumeration.

BUILD_INITIAL_ROAD = 'BUILD_INITIAL_ROAD'¶

BUILD_INITIAL_SETTLEMENT = 'BUILD_INITIAL_SETTLEMENT'¶

DISCARD = 'DISCARD'¶

MOVE_ROBBER = 'MOVE_ROBBER'¶

PLAY_TURN = 'PLAY_TURN'¶

class catanatron.models.enums.ActionType(value)¶

Bases: enum.Enum

Type of action taken by a player.

See comments next to each ActionType for the shape of the corresponding .value field in Actions of that type.

BUILD_CITY = 'BUILD_CITY'¶

BUILD_ROAD = 'BUILD_ROAD'¶

BUILD_SETTLEMENT = 'BUILD_SETTLEMENT'¶

BUY_DEVELOPMENT_CARD = 'BUY_DEVELOPMENT_CARD'¶

DISCARD = 'DISCARD'¶

END_TURN = 'END_TURN'¶

MARITIME_TRADE = 'MARITIME_TRADE'¶

MOVE_ROBBER = 'MOVE_ROBBER'¶

PLAY_KNIGHT_CARD = 'PLAY_KNIGHT_CARD'¶

PLAY_MONOPOLY = 'PLAY_MONOPOLY'¶

PLAY_ROAD_BUILDING = 'PLAY_ROAD_BUILDING'¶

PLAY_YEAR_OF_PLENTY = 'PLAY_YEAR_OF_PLENTY'¶

ROLL = 'ROLL'¶

catanatron.models.enums.action_repr(self)¶

catanatron.models.enums.action_type_repr(self)¶

catanatron.models.map module¶

class catanatron.models.map.CatanMap(tiles: Dict[Tuple[int, int, int], Union[catanatron.models.map.LandTile, catanatron.models.map.Port, catanatron.models.map.Water]] = {}, land_tiles: Dict[Tuple[int, int, int], catanatron.models.map.LandTile] = {}, port_nodes: Dict[Optional[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]], Set[int]] = {}, land_nodes: FrozenSet[int] = frozenset({}), adjacent_tiles: Dict[int, List[catanatron.models.map.LandTile]] = {}, node_production: Dict[int, collections.Counter] = {}, tiles_by_id: Dict[int, catanatron.models.map.LandTile] = {}, ports_by_id: Dict[int, catanatron.models.map.Port] = {})¶

Bases: object

Represents a randomly initialized map.

static from_template(map_template: catanatron.models.map.MapTemplate)¶

static from_tiles(tiles: Dict[Tuple[int, int, int], Union[catanatron.models.map.LandTile, catanatron.models.map.Port, catanatron.models.map.Water]])¶

class catanatron.models.map.EdgeRef(value)¶

Bases: enum.Enum

An enumeration.

EAST = 'EAST'¶

NORTHEAST = 'NORTHEAST'¶

NORTHWEST = 'NORTHWEST'¶

SOUTHEAST = 'SOUTHEAST'¶

SOUTHWEST = 'SOUTHWEST'¶

WEST = 'WEST'¶

class catanatron.models.map.LandTile(tile_id: int, resource: Optional[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]], number: Optional[int], nodes: Dict[catanatron.models.map.NodeRef, int], edges: Dict[catanatron.models.map.EdgeRef, Tuple[int, int]])¶: Bases: object

catanatron.models.map.MINI_MAP_TEMPLATE = MapTemplate(numbers=[3, 4, 5, 6, 8, 9, 10], port_resources=[], tile_resources=['WOOD', None, 'BRICK', 'SHEEP', 'WHEAT', 'WHEAT', 'ORE'], topology={(0, 0, 0): <class 'catanatron.models.map.LandTile'>, (1, -1, 0): <class 'catanatron.models.map.LandTile'>, (0, -1, 1): <class 'catanatron.models.map.LandTile'>, (-1, 0, 1): <class 'catanatron.models.map.LandTile'>, (-1, 1, 0): <class 'catanatron.models.map.LandTile'>, (0, 1, -1): <class 'catanatron.models.map.LandTile'>, (1, 0, -1): <class 'catanatron.models.map.LandTile'>, (2, -2, 0): <class 'catanatron.models.map.Water'>, (1, -2, 1): <class 'catanatron.models.map.Water'>, (0, -2, 2): <class 'catanatron.models.map.Water'>, (-1, -1, 2): <class 'catanatron.models.map.Water'>, (-2, 0, 2): <class 'catanatron.models.map.Water'>, (-2, 1, 1): <class 'catanatron.models.map.Water'>, (-2, 2, 0): <class 'catanatron.models.map.Water'>, (-1, 2, -1): <class 'catanatron.models.map.Water'>, (0, 2, -2): <class 'catanatron.models.map.Water'>, (1, 1, -2): <class 'catanatron.models.map.Water'>, (2, 0, -2): <class 'catanatron.models.map.Water'>, (2, -1, -1): <class 'catanatron.models.map.Water'>})¶: Standard 4-player map

class catanatron.models.map.MapTemplate(numbers: List[int], port_resources: List[Union[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE], NoneType]], tile_resources: List[Union[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE], NoneType]], topology: Mapping[Tuple[int, int, int], Union[Type[catanatron.models.map.LandTile], Type[catanatron.models.map.Water], Tuple[Type[catanatron.models.map.Port], catanatron.models.coordinate_system.Direction]]])¶

Bases: object

numbers: List[int]¶

port_resources: List[Optional[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]]]¶

tile_resources: List[Optional[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]]]¶

topology: Mapping[Tuple[int, int, int], Union[Type[catanatron.models.map.LandTile], Type[catanatron.models.map.Water], Tuple[Type[catanatron.models.map.Port], catanatron.models.coordinate_system.Direction]]]¶

class catanatron.models.map.NodeRef(value)¶

Bases: enum.Enum

An enumeration.

NORTH = 'NORTH'¶

NORTHEAST = 'NORTHEAST'¶

NORTHWEST = 'NORTHWEST'¶

SOUTH = 'SOUTH'¶

SOUTHEAST = 'SOUTHEAST'¶

SOUTHWEST = 'SOUTHWEST'¶

class catanatron.models.map.Port(port_id, resource: Optional[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]], direction, nodes, edges)¶: Bases: object

class catanatron.models.map.Water(nodes: Dict[catanatron.models.map.NodeRef, int], edges: Dict[catanatron.models.map.EdgeRef, Tuple[int, int]])¶

Bases: object

edges: Dict[catanatron.models.map.EdgeRef, Tuple[int, int]]¶

nodes: Dict[catanatron.models.map.NodeRef, int]¶

catanatron.models.map.build_dice_probas()¶

catanatron.models.map.build_map(map_type: Literal[BASE, TOURNAMENT, MINI])¶

catanatron.models.map.get_edge_nodes(edge_ref)¶: returns pair of nodes at the “ends” of a given edge

catanatron.models.map.get_node_counter_production(adjacent_tiles, node_id)¶

catanatron.models.map.get_nodes_and_edges(tiles, coordinate: Tuple[int, int, int], node_autoinc)¶: Get pre-existing nodes and edges in board for given tile coordinate

catanatron.models.map.init_adjacent_tiles(land_tiles: Dict[Tuple[int, int, int], catanatron.models.map.LandTile]) → Dict[int, List[catanatron.models.map.LandTile]]¶

catanatron.models.map.init_node_production(adjacent_tiles: Dict[int, List[catanatron.models.map.LandTile]]) → Dict[int, collections.Counter]¶: Returns node_id => Counter({WHEAT: 0.123, …})

catanatron.models.map.init_port_nodes_cache(tiles: Dict[Tuple[int, int, int], Union[catanatron.models.map.LandTile, catanatron.models.map.Port, catanatron.models.map.Water]]) → Dict[Optional[Literal[WOOD, BRICK, SHEEP, WHEAT, ORE]], Set[int]]¶

Initializes board.port_nodes cache.

Parameters

tiles (Dict[Coordinate, Tile]) – initialized tiles datastructure

Returns

Mapping from FastResource to node_ids that: enable port trading. None key represents 3:1 port.

Return type

Dict[Union[FastResource, None], Set[int]]

catanatron.models.map.initialize_tiles(map_template: catanatron.models.map.MapTemplate, shuffled_numbers_param=None, shuffled_port_resources_param=None, shuffled_tile_resources_param=None) → Dict[Tuple[int, int, int], Union[catanatron.models.map.LandTile, catanatron.models.map.Port, catanatron.models.map.Water]]¶

Initializes a new random board, based on the MapTemplate.

It first shuffles tiles, ports, and numbers. Then goes satisfying the topology (i.e. placing tiles on coordinates); ensuring to “attach” these to neighbor tiles (so as to not repeat nodes or edges objects).

Parameters: map_template (MapTemplate) – Template to initialize.
Raises: ValueError – Invalid tile in topology
Returns: Coordinate to initialized Tile mapping.
Return type: Dict[Coordinate, Tile]

catanatron.models.map.number_probability(number)¶

catanatron.models.player module¶

class catanatron.models.player.Color(value)¶

Bases: enum.Enum

An enumeration.

BLUE = 'BLUE'¶

ORANGE = 'ORANGE'¶

RED = 'RED'¶

WHITE = 'WHITE'¶

class catanatron.models.player.HumanPlayer(color, is_bot=True)¶

Bases: catanatron.models.player.Player

decide(game, playable_actions)¶

Should return one of the playable_actions.

Parameters

game (Game) – complete game state. read-only.
playable_actions (Iterable[Action]) – options right now

class catanatron.models.player.Player(color, is_bot=True)¶

Bases: object

Interface to represent a player’s decision logic.

Formulated as a class (instead of a function) so that players can have an initialization that can later be serialized to the database via pickle.

decide(game, playable_actions)¶

Should return one of the playable_actions.

Parameters

game (Game) – complete game state. read-only.
playable_actions (Iterable[Action]) – options right now

reset_state()¶: Hook for resetting state between games

class catanatron.models.player.RandomPlayer(color, is_bot=True)¶

Bases: catanatron.models.player.Player

decide(game, playable_actions)¶

Should return one of the playable_actions.

Parameters

game (Game) – complete game state. read-only.
playable_actions (Iterable[Action]) – options right now

class catanatron.models.player.SimplePlayer(color, is_bot=True)¶

Bases: catanatron.models.player.Player

decide(game, playable_actions)¶

Should return one of the playable_actions.

Parameters

game (Game) – complete game state. read-only.
playable_actions (Iterable[Action]) – options right now

Module contents¶

catanatron package catanatron.players package