endplay.types

Collection of bridge-related types based on the binary format used by Bo Haglund’s DDS library but with a more Pythonic interface. These types are used by all the submodules in the endplay library.

Classes:

`AlternateRank`(value)	Encodes the rank of a suit using the values 2-14.
`Bid`(name[, alertable, announcement])	Base class representing an auction call.
`Board`([deal, auction, play, board_num, vul, ...])	Class representing a deal along with the play, auction and other table information
`Card`([name, suit, rank])	Immutabale class representing a card with suit and rank read-only attributes
`Contract`([data, level, denom, declarer, ...])	Class representing a specific contract
`ContractBid`(level, denom[, alertable, ...])	Class representing a call that names a contract, i.e. has a level and strain.
`Deal`([pbn, first, trump, complete_deal])	Class representing a bridge deal.
`Denom`(value)	Encoding for suits and contract denomination
`Hand`([data])	Class allowing manipulations of cards in the hand of a single player
`Penalty`(value)	Encodes a penalty
`PenaltyBid`(penalty[, alertable, announcement])	Class representing a call that does not name a contract, i.e. pass, double or redouble.
`Player`(value)	Encoding for player seat
`Rank`(value)	Encodes the rank of a suit.
`SuitHolding`([data, idx])
`Vul`(value)	Encodes the vulnerability

class endplay.types.AlternateRank(value)

Bases: IntEnum

Encodes the rank of a suit using the values 2-14. Used for internal functions, for APIs use the Rank class.

Attributes:

`R2`
`R3`
`R4`
`R5`
`R6`
`R7`
`R8`
`R9`
`RA`
`RJ`
`RK`
`RQ`
`RT`
`abbr`

Methods:

`find`(value)
`to_standard`()

R2 = 2

R3 = 3

R4 = 4

R5 = 5

R6 = 6

R7 = 7

R8 = 8

R9 = 9

RA = 14

RJ = 11

RK = 13

RQ = 12

RT = 10

property abbr: str

static find(value: str) → AlternateRank

to_standard() → Rank

class endplay.types.Bid(name: str, alertable: bool = False, announcement: Optional[str] = None)

Bases: object

Base class representing an auction call. This class provides a convenience constructor from a string, but upon construction will automatically donwcast its type to one of ContractBid or PenaltyBid depending on the type of the call.

Variables:

alertable (bool) – Flag indicating whether the bid is alertable
announcement (Optional[str]) – String transcription of the announcement for this bid

class endplay.types.Board(deal: Optional[Deal] = None, auction: Optional[Iterable[Bid]] = None, play: Optional[Iterable[Card]] = None, board_num: Optional[int] = None, *, vul: Optional[Vul] = None, dealer: Optional[Player] = None, contract: Optional[Contract] = None, claimed: bool = False, **kwargs)

Bases: object

Class representing a deal along with the play, auction and other table information

Variables:

deal (Deal) – The deal at the table
auction (list[Bid]) – The auction at the table
contract (Contract) – The contract at the table
play (list[Card]) – The play history at the table
board_num (int) – The board number of this deal
vul (Vul) – The board vulnerability. If this isn’t defined (i.e. set to None) then it is deduced from board_num
dealer (Player) – The board dealer. Similarly to vul this can be deduced from board_num
claimed (bool) – Flag indicating whether the play ended as a result of a claim
info –
A dictionary which contains arbitrary extra information about the board. The dictionary type used provided case-insensitive dot-access as a convenience (i.e. board.info.event and board.info.Event refer to the same object, but board.info[“event”] and board.info[“Event”] would be considered different). Tabular data can be stored here, any key ending with (but not equal to) table is treated as a table and its value should be a dictionary containing two keys: headers with a list of column names, and rows with a list of the rows. The column names can either be plain strings, or dictionaries with the keys
- ordering: Either “+”, “-” or None depending of if the table is sorted
  ascending, descending or unsorted with respect to this column
- name: A string value with the name of the column
- minwidth: The minimum width that values in this column should be
- alignment: “L” or “R” depending on if this column should be left or right
  aligned. Ignored unless minwidth is defined

Classes:

Info

Dictionary-like class which alows for case-insensitive dot-access, for example.

Attributes:

`contract`	The contract the board was played in.
`dealer`	Dealer of the board.
`vul`	Vulnerability of the board.

class Info

Bases: dict

Dictionary-like class which alows for case-insensitive dot-access, for example:

info["Event"] = "WBF 2017"
print(info.event) # WBF 2017

Methods:

_find_key(key)

_find_key(key: str)

property contract: Optional[Contract]: The contract the board was played in. If not provided, then attempts to calculate based on the auction and play history.

property dealer: Optional[Player]: Dealer of the board. If not defined, then attempts to calculate based on the value of board_num

property vul: Optional[Vul]: Vulnerability of the board. If not defined, then attempts to calculate based on the value of board_num

class endplay.types.Card(name: Optional[str] = None, *, suit: Optional[Denom] = None, rank: Optional[Rank] = None)

Bases: object

Immutabale class representing a card with suit and rank read-only attributes

Variables:

suit (Denom) – The suit of the card
rank (Rank) – The rank of the card

Attributes:

`rank`
`suit`

rank: Rank

suit: Denom

class endplay.types.Contract(data: Optional[Union[contractType, str]] = None, *, level: Optional[int] = None, denom: Optional[Denom] = None, declarer: Optional[Player] = None, penalty: Optional[Penalty] = None, result: Optional[int] = None)

Bases: object

Class representing a specific contract

Attributes:

`_pat`
`declarer`	The declarer of the contract
`denom`	The denomination of the contract
`level`	The level of the contract
`result`	The number of tricks over or under the contract made

Methods:

`copy`()	Return a copy of this contract object
`from_auction`(dealer, auction)	Construct a contract from a bidding sequence
`is_passout`()	Returns true if the contract represents a passout
`score`(vul)	The number of points the contract would score for the declarer

_pat = re.compile('^([1-7])((?:NT?)|S|H|D|C)([NSEW]?)((?:XX|X|D|R)?)((?:=|(?:[+-]\\d+))?)$')

copy() → Contract: Return a copy of this contract object

property declarer: Player: The declarer of the contract

property denom: Denom: The denomination of the contract

static from_auction(dealer: Player, auction: Sequence[Bid]): Construct a contract from a bidding sequence

is_passout() → bool: Returns true if the contract represents a passout

property level: int: The level of the contract

property result: int: The number of tricks over or under the contract made

score(vul: Vul) → int: The number of points the contract would score for the declarer

class endplay.types.ContractBid(level: int, denom: Denom, alertable: bool = False, announcement: Optional[str] = None)

Bases: Bid

Class representing a call that names a contract, i.e. has a level and strain

Variables:

level (int) – The level of the call (between 1 and 7)
denom – The strain of the call
alertable (bool) – Flag indicating whether the bid is alertable
announcement (Optional[str]) – String transcription of the announcement for this bid

class endplay.types.Deal(pbn: Optional[str] = None, first: Player = Player.north, trump: Denom = Denom.nt, *, complete_deal: bool = False)

Bases: object

Class representing a bridge deal. The class keeps track of the four hands at the table, as well as

The player on initial lead to the current trick in Deal.first
The trump suit the deal is played in in Deal.trump
The cards played to the current trick in Deal.curtrick

Methods:

`clear`()	Clear all hands and the cards in the current trick
`compare`(other[, hands_only])
`complete_deal`()	If there is a player with no cards, deal any cards which do not appear in anyone else's hand to that player
`copy`()	Return a new copy of this deal
`from_json`(json)
`from_lin`(lin[, complete_deal])	Construct a deal from a LIN format deal string.
`from_pbn`(pbn)	Clear all hands and the current trick, and replace with the cards in a PBN string
`play`(card[, fromHand])	Play a card to the current trick.
`pprint`([board_no, exclude, stream, vul, dealer])	Print the deal in a hand diagram format.
`rotate`(n)	Rotate clockwise by n quarter-turns, e.g.
`swap`(player_a, player_b)	Swap the specified hands
`to_LaTeX`([board_no, exclude, ddtable])	Return a LaTeX representation of the hand
`to_hand`()	Return a new hand containing the contents of all four hands in the deal
`to_json`([indent])	Encode the data as a JSON string
`to_lin`([dealer, complete_deal])	Convert a deal to LIN representation as used by BBO
`to_pbn`()	Return a PBN string representation of the deal
`unplay`([toHand])	Unplay the last card played to the current trick.

Attributes:

`curhand`	The hand of the curplayer
`curplayer`	The player to play the next card to the current trick
`curtrick`	Return a list of cards played to the current trick
`east`	The east hand
`first`	The player to lead the first card to the current trick
`north`	The north hand
`south`	The south hand
`trump`	The trump suit the deal is being played in
`west`	The west hand

clear() → None: Clear all hands and the cards in the current trick

compare(other: Deal, hands_only: bool = False) → bool

complete_deal() → None: If there is a player with no cards, deal any cards which do not appear in anyone else’s hand to that player

copy() → Deal: Return a new copy of this deal

property curhand: Hand: The hand of the curplayer

property curplayer: Player: The player to play the next card to the current trick

property curtrick: list[endplay.types.card.Card]: Return a list of cards played to the current trick

property east: Hand: The east hand

property first: Player: The player to lead the first card to the current trick

static from_json(json: Union[str, dict])

static from_lin(lin: str, complete_deal: bool = True)

Construct a deal from a LIN format deal string.

Parameters:: complete_deal – If True, then add remaining cards to the last hand if it is omitted from the input string (which is done by default for files downloaded from BBO)

static from_pbn(pbn: str) → Deal

Clear all hands and the current trick, and replace with the cards in a PBN string

Parameters:: pbn – A PBN string, e.g. “N:974.AJ3.63.AK963 K83.K9752.7.8752 AQJ5.T864.KJ94.4 T62.Q.AQT852.QJT”

property north: Hand: The north hand

play(card: Card, fromHand: bool = True) → None

Play a card to the current trick. If the played card completes the trick then the entire trick is cleared and first is set to the played who won the trick using trump as the trumps suit

Parameters:

card – The cad to be played
fromHand – If true then the card will be removed from the hand of the player who is to play to the trick next and throw a RuntimeError if they do not hold this card.

pprint(board_no: ~typing.Optional[int] = None, exclude: list[endplay.types.player.Player] = [], stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, *, vul: ~typing.Optional[~endplay.types.vul.Vul] = None, dealer: ~typing.Optional[~endplay.types.player.Player] = None) → None

Print the deal in a hand diagram format.

Parameters:: board_no – If provided, the hand diagram will display the board number, vulnerability and dealer in the top-left corner

rotate(n: int) → None: Rotate clockwise by n quarter-turns, e.g. with n=1 NESW -> WNES

property south: Hand: The south hand

swap(player_a: Player, player_b: Player) → None: Swap the specified hands

to_LaTeX(board_no: Optional[int] = None, exclude: Iterable[Player] = [], ddtable: bool = False) → str: Return a LaTeX representation of the hand

to_hand() → Hand: Return a new hand containing the contents of all four hands in the deal

to_json(indent: Optional[int] = None) → str: Encode the data as a JSON string

to_lin(dealer: Optional[Player] = None, complete_deal: bool = False) → str

Convert a deal to LIN representation as used by BBO

Parameters:

dealer – If provided, append the dealer (in LIN format) to the returned string
complete_deal – If False, omit the last hand from the string. This is the default for files created by BBO.

to_pbn() → str: Return a PBN string representation of the deal

property trump: Denom: The trump suit the deal is being played in

unplay(toHand: bool = True) → Card

Unplay the last card played to the current trick. Throws a RuntimeError if the current trick is empty

Parameters:: toHand – If true then the card is returned to the hand of the player who played it to the trick
Returns:: The card that was picked up

property west: Hand: The west hand

class endplay.types.Denom(value)

Bases: IntEnum

Encoding for suits and contract denomination

Attributes:

`abbr`	return: A short identifier for the denomination
`clubs`
`diamonds`
`hearts`
`nt`
`spades`

Methods:

`bidorder`()	return: An iterator over all the denominations in the order they appera in a bidding box
`find`(name)	Convert a string value into a Denom object
`is_major`()	return: True if the denomination is spades or hearts
`is_minor`()	return: True if the denomination is diamonds or clubs
`is_suit`()	return: True if the denomination is not notrumps
`suits`([reverse])	Iterate over the suits, excluding notrumps

property abbr: str

Returns:: A short identifier for the denomination

static bidorder() → Iterator[Denom]

Returns:: An iterator over all the denominations in the order they appera in a bidding box

clubs = 3

diamonds = 2

static find(name: str) → Denom: Convert a string value into a Denom object

hearts = 1

is_major() → bool

Returns:: True if the denomination is spades or hearts

is_minor() → bool

Returns:: True if the denomination is diamonds or clubs

is_suit() → bool

Returns:: True if the denomination is not notrumps

nt = 4

spades = 0

static suits(reverse: bool = False) → Iterator[Denom]

Iterate over the suits, excluding notrumps

Parameters:: reverse – If true, return suits in the order clubs -> spades
Returns:: An iterator over the four suits

class endplay.types.Hand(data: Union[str, Array[c_uint]] = '...')

Bases: object

Class allowing manipulations of cards in the hand of a single player

Methods:

`add`(card)	Adds a card to the hand
`clear`()	Remove all cards from the hand
`copy`()
`extend`(cards)	Add multiple cards to the hand
`from_lin`(lin)	Construct a Hand from a LIN string
`from_pbn`(pbn)	Construct a Hand from a PBN string
`pprint`([vertical, stream])	Print the suits in the hand using suit symbols
`remove`(card)	Remove a card from the hand
`to_LaTeX`([vertical, ten_as_letter])	Create a LaTeX representation of the hand.
`to_lin`()	Convert a Hand to a LIN string
`to_pbn`()	return: A PBN representation of the hand

Attributes:

`clubs`	The club holding of the hand
`diamonds`	The diamond holding of the hand
`hearts`	The heart holding of the hand
`spades`	The spade holding of the hand

add(card: Card) → bool

Adds a card to the hand

Parameters:: card – The card to be added to the hand
Returns:: False if the card was already in the hand, True otherwise

clear() → None: Remove all cards from the hand

property clubs: SuitHolding: The club holding of the hand

copy() → Hand

property diamonds: SuitHolding: The diamond holding of the hand

extend(cards: Iterable[Card]) → int

Add multiple cards to the hand

Parameters:: cards – An iterable of the cards to add
Returns:: The number of cards successfully added

static from_lin(lin: str) → Hand

Construct a Hand from a LIN string

Parameters:: lin – A LIN string for a hand, e.g. “SQT62HDAQT852CQJT”

static from_pbn(pbn: str) → Hand

Construct a Hand from a PBN string

Parameters:: pbn – A PBN string for a hand, e.g. “QT62..AQT852.QJT”

property hearts: SuitHolding: The heart holding of the hand

pprint(vertical: bool = True, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → None: Print the suits in the hand using suit symbols

remove(card: Card) → bool

Remove a card from the hand

Parameters:: card – The card to be added to the hand, can be a string representation e.g. “CQ”
Returns:: False if the card wasn’t in the hand, True otherwise

property spades: SuitHolding: The spade holding of the hand

to_LaTeX(vertical: bool = True, ten_as_letter: bool = False) → str

Create a LaTeX representation of the hand.

Parameters:

vertical – If True uses vhand, else hhand layout
title – The hand title. If vertical is False this is ignored

to_lin() → str: Convert a Hand to a LIN string

to_pbn() → str

Returns:: A PBN representation of the hand

class endplay.types.Penalty(value)

Bases: IntEnum

Encodes a penalty

Attributes:

`abbr`
`doubled`
`passed`
`redoubled`

Methods:

find(name)

property abbr: str

doubled = 2

static find(name: str)

passed = 1

redoubled = 4

class endplay.types.PenaltyBid(penalty: Penalty, alertable: bool = False, announcement: Optional[str] = None)

Bases: Bid

Class representing a call that does not name a contract, i.e. pass, double or redouble

Variables:

penalty (Penalty) – The type of the call
alertable (bool) – Flag indicating whether the bid is alertable
announcement (Optional[str]) – String transcription of the announcement for this bid

class endplay.types.Player(value)

Bases: IntEnum

Encoding for player seat

Attributes:

`abbr`	return: A single character string for the player name
`east`
`lho`	return: The player on the current player's left
`north`
`partner`	return: The player opposite the current player
`rho`	return: The player to the current player's right
`south`
`west`

Methods:

`enumerate`(iterable[, step])	Return an iterator whose next method returns a tuple containing a Player (starting from this player) and the values obtained from iterating over iterable, where the player increments each time by step rotations clockwise
`find`(name)	Convert a string into a Player object
`from_board`(n)	Return the player who is the dealer of the corresponding board
`from_lin`(n)	Convert a BBO LIN representation of a player into a Player object.
`is_vul`(vul)
`iter_from`()	Iterate over all four players, clockwise, starting from this player
`iter_order`(order)	Iterate over a sequence of players in a given order
`next`([n])	return: The player who is n places left of the current player
`prev`([n])	return: The player who is n places right of the current player
`to_lin`()
`turns_to`(other)	Return the number of positions clockwise other is from self

property abbr: str

Returns:: A single character string for the player name

east = 1

enumerate(iterable: Iterable, step: int = 1) → Iterator: Return an iterator whose next method returns a tuple containing a Player (starting from this player) and the values obtained from iterating over iterable, where the player increments each time by step rotations clockwise

static find(name: str) → Player: Convert a string into a Player object

static from_board(n: int) → Player: Return the player who is the dealer of the corresponding board

static from_lin(n: int) → Player: Convert a BBO LIN representation of a player into a Player object. The conversion is determined by 1=S, 2=W, 3=N, 4=E

is_vul(vul: Vul) → bool

iter_from() → Iterator[Player]

Iterate over all four players, clockwise, starting from this player

Returns:: An iterator over all four players in play order

static iter_order(order: str) → Iterator[Player]

Iterate over a sequence of players in a given order

Parameters:: order – The specified order as a four-character string or list of strings
Returns:: An iterator over the players in the specified order

property lho: Player

Returns:: The player on the current player’s left

next(n: int = 1) → Player

Returns:: The player who is n places left of the current player

north = 0

property partner: Player

Returns:: The player opposite the current player

prev(n: int = 1) → Player

Returns:: The player who is n places right of the current player

property rho: Player

Returns:: The player to the current player’s right

south = 2

to_lin() → int

turns_to(other: Player) → int: Return the number of positions clockwise other is from self

west = 3

class endplay.types.Rank(value)

Bases: IntEnum

Encodes the rank of a suit. The standard values use powers of two, however some internal functions use an alternative encoding AlternateRank using the values 2-14.

Attributes:

`R2`
`R3`
`R4`
`R5`
`R6`
`R7`
`R8`
`R9`
`RA`
`RJ`
`RK`
`RQ`
`RT`
`abbr`

Methods:

`find`(value)
`to_alternate`()

R2 = 4

R3 = 8

R4 = 16

R5 = 32

R6 = 64

R7 = 128

R8 = 256

R9 = 512

RA = 16384

RJ = 2048

RK = 8192

RQ = 4096

RT = 1024

property abbr: str

static find(value: str) → Rank

to_alternate() → AlternateRank

class endplay.types.SuitHolding(data: Union[c_uint_Array_4, str] = '', idx: Optional[int] = None)

Bases: object

Methods:

`add`(rank)	Add a rank to the suit holding
`clear`()	Removes all cards from the holding
`copy`()
`extend`(ranks)	Add multiple ranks to the suit holding
`from_pbn`(pbn)	Construct a SuitHolding object from a PBN string
`remove`(rank)	Remove a rank from the suit holding
`to_pbn`()	Create a PBN representation of the suit holding

add(rank: Union[Rank, str]) → bool

Add a rank to the suit holding

Parameters:: rank – The rank to add
Returns:: False if the rank was already in the holding, True otherwise

clear() → None: Removes all cards from the holding

copy() → SuitHolding

extend(ranks: Iterable[Rank]) → int

Add multiple ranks to the suit holding

Parm ranks:: An iterable of the ranks to add
Returns:: The number of ranks successfully added

static from_pbn(pbn: str) → SuitHolding: Construct a SuitHolding object from a PBN string

remove(rank: Rank) → bool

Remove a rank from the suit holding

Parameters:: rank – The rank to remove
Returns:: False if the rank wasn’t in the holding, True otherwise

to_pbn() → str: Create a PBN representation of the suit holding

class endplay.types.Vul(value)

Bases: IntEnum

Encodes the vulnerability

Attributes:

`abbr`	A short string representation of the vulnerability
`both`
`ew`
`none`
`ns`

Methods:

`find`(name)	Convert a string into a Vul object
`from_board`(board_no)	return: The vulnerability of the specified board
`from_lin`(s)	Convert a BBO LIN string of vulnerability into a Vul object.
`to_lin`()

property abbr: str: A short string representation of the vulnerability

both = 1

ew = 3

static find(name: str) → Vul: Convert a string into a Vul object

static from_board(board_no: int) → Vul

Returns:: The vulnerability of the specified board

static from_lin(s: str) → Vul: Convert a BBO LIN string of vulnerability into a Vul object. The conversion is determined by o=none, e=ew, n=ns, b=both

none = 0

ns = 2

to_lin() → str