Site Import Plugins

Hand History Converters

(Work in Progress)


This page is a description of the Hand History Converter interface provided by FPDB.


There are two main elements: the Hand class (which currently may be a Stud, Draw or Holdem Hand), and the HandHistoryConverter, which is subclassed for each site or history format.

The HHC is subclassed for each site and exposes a number of methods such as readBlinds and readStacks which parse the hand text for specific bits of information. They invoke methods on the Hand to add the information.

The Hand stores the details of the hand, which it gets by making calls on the HHC to parse the history text.

Hand (Base Class)

You should never actually need to modify this class, though you may want to add some debug messages to it once in a while.

The Hand class is site-independent, and consists of :
- data structures to hold the elements of the hand such as the players' names, seats and stacks, and their actions on each betting round
- methods to add the information; we prefer this mediated access because it allows us to greatly simplify the access to and modification of the internal data structures and log the call for debugging.
- a method to write the hand history in a pseudo-PokerStars 'interlingua' format that is good enough for the legacy stars importer
- methods (or at least, occasional functionality..) to infer missing information from badly written history formats. For example, 1) not all sites report the amount of rake taken, so this is calculated by the difference between the amount of money that went in the pot(s) and the amount taken out as winnings, which are always(?) reported post-rake and 2) not all sites report when a player is 'all in', and so this is also checked for with all chip-moving actions (betting, raising, calling, blinding, anteing, bringing in).
The Hand will soon be directly insertable into and selectable from the database.


The HoldemOmaha subclass has methods and data specific to holdem-like games.
It is responsible for writing a pseudo-stars Holdem or Omaha history.

It calls the methods


The Stud subclass has methods and data specific to stud games. Stud games involve open and/or closed cards dealt on each street.
It is responsible for writing a stud-hand pseudo-Stars history.


The draw subclass deals with Badugi, 5-card-draw type games — methods for discarding cards and so on.

HandHistoryConverter (Base Class)

The HHC is the class which can be specialised to implement parsing of a sites hand history.

HHC Methods

HHC defines the following functions but does not implement them. Each converter must define these methods

determineGameType(self, handText):

determineGameType is the first inspection of the HH (which is in the handText variable) by the plugin. It must first determine that the HH is compatible with the plugin, that is, a PokerStars HH is atually being read by the PokerStars plugin. If determineGameType determines that the HH is not compatible with the plugin, it should return None.

Secondly, the determineGameType method inspects the HH to determine the game type and returns a dict of game type information. The dict is defined as:

gametype = {'type': game_type, 'limitType': limit, 'base': game_base, 'category': game}
game_type in ['ring', 'tour']
limit in ['nl', 'pl', 'fl']
game_base in ['hold', 'stud', 'draw']
category in ['Hold'em, 'Omaha', 'Omaha Hi/Lo', 'Razz', '7 Card Stud',
             '7 Card Stud Hi/Lo', 'Badugi', 'Triple Draw 2-7 Lowball']

web analytics

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License