Reference

pycatan

A python module for holding the game state and performing game logic for games of The Settlers of Catan.

pycatan.Game

class pycatan.Game(board, num_players=4)

A game of Catan. Holds all the game state and game logic for interacting with the board, players and decks.

Parameters

board (Board) – The board to use in the Catan game
num_players (Optional[int]) – The number of players to start the game with. Defaults to 4

board

The Catan board being used in this game

Type: Board

players

The players in the game, ordered by (recommended) turn order

Type: List[Player]

longest_road_owner

The player who has the longest road token, or None if no players have a road of at least 5 length

Type: Player

largest_army_owner

The player how has the largest army, or None if no players have played at least 3 knight cards

Type: Player

development_card_deck

The deck of development cards

Type: List[DevelopmentCard]

build_settlement(player, coords, cost_resources=True, ensure_connected=True)

Build a settlement by the player given in the coords given, or raises an error if the input is invalid.

Parameters

player (Player) – The player who is building the settlement
coords (Coords) – The coordinates to build the settlement at
cost_resources (Optional[bool]) – Whether to remove the resources required to build a settlement from the player’s hands, and raise an error if they don’t have them. Defaults to True
ensure_connection – Whether to raise an error if the settlement would not be connected to a road owned by the same player. Defaults to True

Raises

NotEnoughResourcesError – If check_resources is True and the player does not have enough resources
NotConnectedError – If check_connection is True and the settlement would not be connected to any roads owned by the player

build_road(player, path_coords, cost_resources=True, ensure_connected=True)

Build a road.

Parameters

player (Player) – The player who is building the road
path_coords (Set[Coords]) – The coordinates of the path to build a road on. Should be two valid connected intersection coordinates (i.e. {(1, 0), (1, -1)})
cost_resources (Optional[bool]) – Whether to remove resources from the player’s hand to build the road, and raise an error if they don’t have enough
ensure_connected (Optional[bool]) – Whether to ensure that the road is connected to another road, settlement or city

Raises

NotEnoughResourcesError – If check_resources is True and the player doesn’t have the cards to build the road
NotConnectedError – If check_connection is True and the road is not connected to anything
ValueError – If path_coords is not a set of two valid intersection coordinates
CoordsBlockedError – If the position is already blocked by another road/other path building

upgrade_settlement_to_city(player, coords, cost_resources=True)

Build a city from a settlement.

Parameters

player (Player) – The player who is building the city
coords (Coords) – Where to build the city
cost_resources (Optional[bool]) – Whether to remove the resources from the player’s hand

Raises

NotEnoughResourcesError – If cost_resources is true and the player doesn’t have enough resources
ValueError – If coords is not a valid intersection
RequiresSettlementError – If there is not a valid settlement at the intersection to upgrade

add_yield_for_roll(roll)

Add the resources to the player’s hands for the dice roll given.

Parameters: roll (int) – The number that was rolled

add_yield(roll_yield)

Add the yield provided to the player’s hands.

Parameters: roll_yield (Dict[Player, RollYield]) – The yield provided by Board.get_yield_for_roll. A dictionary of RollYields mapped by the player who gets that yield

move_robber(coords)

Move the robber to the coords specified.

Parameters: coords (Coords) – The coordinates of the hex to move the robber to
Raises: ValueError – If the coordinates are not a valid hex

build_development_card(player)

Build a development card and place it in the player’s hand.

Parameters: player (Player) – The player building the development card
Raises: NotEnoughResourcesError – If the player cannot afford to build a development card
Return type: DevelopmentCard
Returns: The card that the player built and has been added to their hand

play_development_card(player, card)

Play a development card.

Do not actually change the game state to play the card. Mainly just keep track of how many knight cards each player has played and may change who has the largest army

Parameters

player (Player) – The player playing a development card
card (DevelopmentCard) – The development card thay are playing

Raises

ValueError – If the player does not have the card

get_victory_points(player)

Get the number of victory points the player has.

Parameters: player (Player) – The player to get the victory points for
Returns: The number of victory points

pycatan.Player

class pycatan.Player

A Player in a Catan game.

resources

How many of each resource this player has

Type: Dict[Resource, int]

development_cards

How many of each development card this player has

Type: Dict[DevelopmentCard, int]

connected_harbors

The harbors this player is connected to. Used to determine the valid trades

Type: Set[Harbor]

has_resources(resources)

Check if the player has the resources given.

Parameters: resources (Dict[Resource, int]) – The resources to check that the player has
Returns: True if the player has the resources, false otherwise
Return type: bool

remove_resources(resources)

Remove the given resources from the player’s hand.

Parameters: resources (Dict[Resource, int]) – The resources to remove
Raises: NotEnoughResourcesError – If the player does not have the resources

add_resources(resources)

Add some resources to this player’s hand.

Parameters: resources (Dict[Resource, int]) – The resources to add

get_possible_trades()

Get a list of the possible trades for this player.

Return type: List[Dict[Resource, int]]
Returns: The possible trades for this player. Negative numbers mean the player would give away those resources, positive numbers mean the player would receive those resources

play_development_card(card)

Mark a development card as played.

i.e. remove it from the player’s hand

Parameters: card (DevelopmentCard) – The card to play
Raises: ValueError – If the player does not have the card

get_random_resource()

Get a random resource from this player.

Weighs the different resources depending on how many the player has in their hand. This is equavalent to randomly picking a resource out of the player’s hand, i.e. when stealing a card via a knight card or rolling a 7.

Return type: Optional[Resource]
Returns: The resource, or None if the player has no resources

pycatan.Resource

class pycatan.Resource(value)

A type of resource in a game of Catan.

LUMBER = 0: The lumber resource

BRICK = 1: The brick resource

WOOL = 2: The wool resource

GRAIN = 3: The grain resource

ORE = 4: The ore resource

pycatan.DevelopmentCard

class pycatan.DevelopmentCard(value)

A development card in a game of Catan.

KNIGHT = 0: The knight card

YEAR_OF_PLENTY = 1: The year of plenty card

ROAD_BUILDING = 2: The road building card

MONOPOLY = 3: The monopoly card

VICTORY_POINT = 4: Generic type to represent the victory point cards (i.e. library)

static get_required_resources()

Get the resources required to build a development card.

Return type: Dict[Resource, int]
Returns: How many of each resource is required to build a development card

pycatan.RollYield

class pycatan.RollYield

A utility class to represent what each player gets from a roll of the dice.

Contains information about where the resources came from as well.

total_yield

The total yield from this dice roll

Type: Dict[Resource, int]

all_yields

The sources where the resources came from

Type: Set[RollYieldSource]

add_yield(resource, amount, source)

Add a yield to the RollYield.

Also updates total_yield. Use this method instead of directly changing all_yields.

Parameters

resource (Resource) – The resource the player has received
amount (int) – The amount of the resource the player has received

Return type

None

pycatan.board

Submodule that is used to hold the board state.

pycatan.board.Board

class pycatan.board.Board(hexes, harbors={}, robber=None)

An interface for holding the state of Catan boards.

Uses a triangular grid to hold the tiles, intersections and paths. The Board constructor will automatically generate the intersections and paths from a dict of hexes, assuming all the hexes tile correctly.

Parameters

hexes (Set[Hex]) – The hexes on the board, keyed by their coordinates
harbors (Set[Harbor]) – The harbors on the board
robber (Optional[Coords]) – The inital coordinates of the robber. If None, then will automatically place the robber on the first desert hex it can find, and raise an error if there are non

hexes

The hexes on this catan board, keyed by their coordinates

Type: Dict[Coord, Hex]

intersections: (Dict[Coords, Intersection]): The intersections on the board, keyed by their coordinates

paths

The paths on the board, keyed by the coordinates of the two intersections they connect

Type: Dict[frozenset[Coords], Path]

harbors

The harbors on the board, keyed by the coords of the path they are attached to

Type: Dict[frozenset[Coords], Harbor]

robber

The location of the robber

Type: Set[Coords]

add_path_building(player, building_type, path_coords, ensure_connected=True)

Add an path building to the board.

Do not check if the player has enough resources, or any other checks other than the building’s location being valid.

Parameters

player (Player) – The player adding the building
building_type (BuildingType) – The building_type of the building being added
path_coords (Set[Coords]) – The coordinates the path to build the building on (i.e. the coordinates of the two intersections the path connects)
ensure_connected (Optional[bool]) – Whetehr to ensure that the path building is connected to another building. Defaults to True

Raises

ValueError – If the path_coords are not valid
CoordsBlockedError – If there is already a building on the path
NotConnectedError – If check_connection is true and the building is not connected to anything

assert_valid_road_coords(player, path_coords, ensure_connected=True)

Assert that a given edge is a valid place for the player to build a road.

Parameters

player (Player) – The player
path_coords (Set[Coords]) – The coordinates of the two intersections connected by the path
ensure_connected (Optional[bool]) – Whether to assert that the path is connected to the player’s existing roads or settlements

add_intersection_building(player, coords, building_type, ensure_connected=True)

Add an intersection building to the board.

Parameters

player (Player) – The player who owns the settlement
coords (Coords) – The coords to put the building
ensure_connected (Optional[bool]) – Whether to ensure that the building is connected to the player’s roads. Defaults to True

Raises

InvalidCoordsError – If coords is not a valid intersection
TooCloseToBuildingError – If the building is too close to another building
PositionAlreadyTakenError – If the position is already taken

assert_valid_settlement_coords(coords, player, ensure_connected)

Check whether the coordinates given are a valid place to build a settlement.

Does not return anything, but raises an error if the coordinates are not valid.

Parameters

coords (Coords) – The coordinates to check
player (Player) – The player building the settlement
ensure_connected (Optional[bool]) – Whether the check if the settlement will be connected by road

Raises

TooCloseToBuildingError – If the building is too close to another building
PositionAlreadyTakenError – If the position is already taken
NotConnectedError – If check_connection is True and the settlement is not connected

Return type

None

assert_valid_city_coords(player, coords)

Check whether the coordinates given are a valid place to build a city by the player given.

Parameters

player (Player) – The player building the city
coords (Coords) – Where to build the city

is_valid_settlement_coords(player, coords, ensure_connected)

Check whether the given coordinates are a valid place for the player to build a settlement.

Parameters

player (Player) – The player
coords (Coords) – The coordinates to check
ensure_connected (Optional[bool]) – Whetehr to ensure that the settlement will be connected to the player’s roads

Return type

bool

Returns

Whether the coordinates are a valid settlement location for the player

is_valid_city_coords(player, coords)

Check whether the coordinates given are valid city coordinates.

Parameters

player (Player) – The player
coords (Coords) – The coordinates to check

Return type

bool

Returns

Whether the coords are a valid place for the player to build a city

is_valid_road_coords(player, path_coords, ensure_connected=True)

Check whether the path coordinates given are valid road coordinate for the player given.

Parameters

player (Player) – The player
path_coords (Set[Coords]) – The coordinates of the path
ensure_connected (Optional[bool]) – Whether to ensure that the road is connected to the player’s existing roads/buildings. Defaults to True

Return type

bool

Returns

Whether the player can build a road on this path

get_valid_settlement_coords(player, ensure_connected=True)

Get all the valid settlement coordinates for the player to build a settlement.

Parameters

player (Player) – The player to check for valid settlement coordinates
ensure_connected (Optional[bool]) – Whether to ensure the coordinates are connected to the player’s roads

Return type

Set[Coords]

Returns

The coordinates of all the valid settlement intersections

get_valid_city_coords(player)

Get all the valid city coordinates for the player to build a city.

Parameters: player (Player) – The player building the city

Returns: The coordinates of all the valid city locations

Return type: Set[Coords]

get_valid_road_coords(player, ensure_connected=True, connected_intersection=None)

Get all the valid coordinates for the player to build a road.

Parameters

player (Player) – The player building the road
ensure_connected (Optional[bool]) – Whether to only return the path coordinates that are connected to the player’s existing roads/settlements. Defaults to True
connected_intersection (Optional[Coords]) – The coords of an intersection that the potential road must be attached to. Defaults to None

Return type

Set[FrozenSet[Coords]]

Returns

The coordinates of all the paths where the player can build a road.

get_intersection_connected_intersections(intersection)

Get all the intersections connected to the intersection given by an path.

Parameters: intersection (Intersection) – The intersection to get the connected intersections for
Return type: Set[Intersection]
Returns: The intersections that are connected to the intersection given

get_connected_hex_intersections(hex)

Get all of the intersections that are connected to the hex.

Parameters: hex (Hex) – The hex
Return type: Set[Intersection]
Returns: All 6 intersections that are around this hex

get_hexes_connected_to_intersection(intersection_coords)

Get all the hexes’ coordinates that are connected to the intersection with the coordinates provided.

Parameters: intersection_coords (Coords) – The coords of an intersection
Return type: Set[Coords]
Returns: The hexes connected to the intersection

get_yield_for_roll(roll)

Calculate the resources given out for a particular roll.

Parameters: roll (int) – The number rolled
Return type: Dict[Player, RollYield]
Returns: The RollYield object containing the information for what each player gets, keyed by the player

is_valid_hex_coords(coords)

Check whether the coordinates given are valid hex coordinates.

Parameters: coords (Coords) – The coordinates
Return type: bool
Returns: Whether there is a hex at those coordinates

calculate_player_longest_road(player)

Calculate the length of the longest road segment for the player given.

Parameters: player (Player) – The player to calculate the longest road for
Return type: int
Returns: The length of the ongest road segment

get_paths_for_intersection_coords(coords)

Get all the paths who that connected to the intersection given.

Parameters: coords (Coords) – The coordinates of the intersection
Return type: Set[Path]
Returns: A set of the paths attached to that intersection

get_hex_resources_for_intersection(coords)

Get the associated resources for the hexes around the intersection at the coords given.

Parameters: coords (Coords) – The coordinates of an intersection
Return type: Dict[Resource, int]
Returns: The amounts of resources from the hexes around this intersection

get_players_on_hex(coords)

Get all the players who have a building on the edge of the given hex.

Parameters: coords (Coords) – The coords of the hex
Return type: Set[Player]
Returns: The players with a building on the edge of the hex

pycatan.board.Hex

class pycatan.board.Hex(coords, hex_type, token_number=None)

A hex on a Catan board.

Parameters

coords (Coords) – The coordinates of this hex
hex_type (HexType) – The type of this hex
token_number (Optional[int]) – The number of the token on this hex, or None if the hex is a desert

CONNECTED_POINTS_OFFSETS

The offsets of the connected points from a hex’s coordinates

Type: Set[Coords]

coords

The coordinates of this hex

Type: Coords

hex_type

The type of this hex

Type: HexType

token_number

The number of the token on this hex

Type: int

pycatan.board.HexType

class pycatan.board.HexType(value)

The different types of hexes in the game.

FOREST = 0: The forest hex type

HILLS = 1: The hills hex type

PASTURE = 2: The pasture hex type

FIELDS = 3: The fields hex type

MOUNTAINS = 4: The mountains hex type

DESERT = 5: The desert hex type

get_resource()

Get the resource the player receives when a hex of this type is activated.

Returns: The resource the player would get None: If the player would not get a resource (i.e. a desert hex)
Return type: Resource

pycatan.board.Intersection

class pycatan.board.Intersection(coords, building=None)

A intersection on the Catan board.

Parameters

coords (Coords) – The coordinates of the intersection.
building (Optional[IntersectionBuilding]) – The building on the intersection.

CONNECTED_CORNER_OFFSETS

The offsets of the intersections that are connected by an path. i.e. to get the connected intersections, add a intersection’s coords to these values, and then filter for which coords are valid intersection coords.

Type: Set[Coords]

coords

The coordinates of the intersection.

Type: Coords

building

The building on the intersection.

Type: IntersectionBuilding, optional

pycatan.board.Path

class pycatan.board.Path(path_coords, building=None)

A path on a Catan board.

Parameters

path_coords (Set[Coords]) – The coordinates of the two intersections that the path connects.
building (Optional[PathBuilding]) – The building on this path.

path_coords

The coordinates of the two intersections that the path connects.

Type: set(Coords, Coords)

building

The building on this path.

Type: PathBuilding, optional

other_intersection(coords)

Given one of the intersection coords for this path, returns the other one.

Parameters: coords (Coords) – The intersection coords
Return type: Coords

pycatan.board.Coords

class pycatan.board.Coords(q, r)

A class used to represent coordinates on the Catan board.

Stores a coordinate on a triangular grid, so that each hex and point both has a unique coord.

Parameters

q (int) – The q coordinate
r (int) – The r coordinate

pycatan.board.Building

class pycatan.board.Building(owner, building_type)

A building on the Catan board.

owner

The player who owns this building

Type: Player

building_type

The type of building this is

Type: BuildingType

Parameters

owner (Player) – The player who owns this building
building_type (BuildingType) – The type of building this is

pycatan.board.BuildingType

class pycatan.board.BuildingType(value)

A type of building in a Catan game.

ROAD = 0: The roads

SETTLEMENT = 1: The settlements

CITY = 2: The cities

get_required_resources()

Get the resources required to build this building.

Returns: The amount of each resource required to build this building
Return type: Dict[Resource, int]

pycatan.board.PathBuilding

class pycatan.board.PathBuilding(owner, building_type, path_coords)

A building that is built on an path. In the base game, only roads.

owner

The player who owns this building

Type: Player

building_type

The type of building this is

Type: BuildingType

path_coords

The coordinates of the two intersections the building is connecting

Type: Set[Coords]

Parameters

owner (Player) – The player who owns this building
building_type (BuildingType) – The type of building this is
path_coords (Set[Coords]) – The coordinates of the two intersections the building is connecting

pycatan.board.IntersectionBuilding

class pycatan.board.IntersectionBuilding(owner, building_type, coords)

A building that is built on a intersection. In the base game, a settlement or a city.

owner

The player who owns this building

Type: Player

building_type

The type of building this is

Type: BuildingType

coords

The coords the building is at

Type: Coords

Parameters

owner (Player) – The player who owns this building
building_type (BuildingType) – The type of building this is
coords (Coords) – The coords the building is at

pycatan.board.BeginnerBoard

class pycatan.board.BeginnerBoard: The beginner board, as outlined in the Catan rules.

pycatan.board.RandomBoard

class pycatan.board.RandomBoard: A board where the hexes, numbered tokens and harbors are all shuffled randomly.

pycatan.board.BoardRenderer

class pycatan.board.BoardRenderer(board, player_color_map={}, hex_color_map={<HexType.FIELDS: 3>: '#ffea29', <HexType.FOREST: 0>: '#005e09', <HexType.PASTURE: 2>: '#52ff62', <HexType.HILLS: 1>: '#cc1f0c', <HexType.MOUNTAINS: 4>: '#7a7a7a', <HexType.DESERT: 5>: '#ffe5a3'}, resource_color_map={<Resource.GRAIN: 3>: '#ffea29', <Resource.LUMBER: 0>: '#005e09', <Resource.WOOL: 2>: '#52ff62', <Resource.BRICK: 1>: '#cc1f0c', <Resource.ORE: 4>: '#7a7a7a'})

Class for rendering a board in the terminal and configuring its appearance.

Parameters

board (Board) – The board to render
player_color_map (Optional[Dict[Player, str]]) – A map of which colors to use for which players. Colors are string hex codes (i.e. ‘#FF0000’)
hex_color_map (Optional[Dict[HexType, str]]) – A map of which colors to use for the different types of hexes. Colors are string hex codes (i.e. ‘#FF00000’)
resource_color_map (Optional[Dict[Resource, str]]) – A map of which colors to use for the different resource harbors. Colors are string hex codes (i.e. ‘#FF00000’)

get_coords_as_xy(coords)

Get the coordinates given as x, y position.

Parameters: coords (Coords) – The coordinates
Return type: Tuple
Returns: The (x, y) position

get_board_as_string(hex_labels={}, intersection_labels={}, path_labels={})

Get the board as a large, multiline string that includes colors.

Parameters

hex_labels (Optional[Dict[Hex, str]]) – A dictionary of labels to put on the hexes instead of the numbered tokens
intersection_labels (Optional[Dict[Intersection, str]]) – A dictionary of labels to put on the points
path_labels (Optional[Dict[Path, str]]) – A dictionary of labels to put on the paths

Returns

The board as a string

Return type

str

render_board(hex_labels={}, intersection_labels={}, path_labels={})

Render the board into the terminal.

Parameters

hex_labels (Optional[Dict[Hex, str]]) – A dictionary of labels to put on the hexes instead of the numbered tokens
intersection_labels (Optional[Dict[Intersection, str]]) – A dictionary of labels to put on the points
path_labels (Optional[Dict[Path, str]]) – A dictionary of labels to put on the paths