diff --git a/changelog.rst b/changelog.rst new file mode 100644 index 0000000..cca0559 --- /dev/null +++ b/changelog.rst @@ -0,0 +1,19 @@ +Changelog +========= + +Version 0.0.1 (September 19, 2024) +---------------------------------- + +**Added** + +- Optional fields: ``venue``, ``time_zone_abbreviation``, ``winnings``, ``currency_symbol``. + +**Changed** + +- Improved description of showdown actions. +- Add ``String`` native TOML type as valid type for ``hand`` and ``table`` optional fields. + +Version 0.0.0 (April 5, 2024) +----------------------------- + +**Initial Release** diff --git a/conf.py b/conf.py index cd92d66..8f06a07 100644 --- a/conf.py +++ b/conf.py @@ -9,7 +9,7 @@ project = 'Poker Hand History File Format Specification' copyright = '2024, Juho Kim' author = 'Juho Kim' -release = '0.0.0' +release = '0.0.1' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/index.rst b/index.rst index 5b2e8e0..d0e6628 100644 --- a/index.rst +++ b/index.rst @@ -23,6 +23,7 @@ discussion conclusion contributing + changelog Indices and tables ================== diff --git a/optional.rst b/optional.rst index 248c29c..8da5ac2 100644 --- a/optional.rst +++ b/optional.rst @@ -3,34 +3,38 @@ Optional Fields The optional fields may be left unspecified by the annotator. The complete list of optional fields and their TOML native types are tabulated below. -============================================================== ======================== =========================== -Field Name TOML Native Type -============================================================== ======================== =========================== -Annotator full name or mononym ``author`` String -Event name ``event`` String -Event or organizer URL ``url`` String -Venue street-level address ``address`` String -Venue city ``city`` String -Venue region, state, or province ``region`` String -Venue postal code ``postal_code`` String -Venue country ``country`` String -Timestamp at the start of the hand ``time`` Local time -`IANA time zone `_ ``time_zone`` String -Event day ``day`` Integer -Event month ``month`` Integer -Event year ``year`` Integer -Hand number ``hand`` Integer -Tournament level ``level`` Integer -Players' seat numbers ``seats`` Array of integers -The number of seats ``seat_count`` Integer -Table number ``table`` Integer -Player full names or mononyms ``players`` Array of strings -Final stacks ``finishing_stacks`` Array of integers or floats -`ISO 4127 `_ currency ``currency`` String -Ante uniformity ``ante_trimming_status`` Boolean -Allocated time per action ``time_limit`` Integer or float -Time banks at the beginning of the hand ``time_banks`` Array of integers or floats -============================================================== ======================== =========================== +============================================================== ========================== =========================== +Field Name TOML Native Type +============================================================== ========================== =========================== +Annotator full name or mononym ``author`` String +Event name ``event`` String +Event or organizer URL ``url`` String +Venue ``venue`` String +Venue street-level address ``address`` String +Venue city ``city`` String +Venue region, state, or province ``region`` String +Venue postal code ``postal_code`` String +Venue country ``country`` String +Timestamp at the start of the hand ``time`` Local time +`IANA time zone `_ ``time_zone`` String +Time zone abbreviation ``time_zone_abbreviation`` String +Event day ``day`` Integer +Event month ``month`` Integer +Event year ``year`` Integer +Hand name or number ``hand`` String or integer +Tournament level ``level`` Integer +Players' seat numbers ``seats`` Array of integers +The number of seats ``seat_count`` Integer +Table name or number ``table`` String or integer +Player full names or mononyms ``players`` Array of strings +Final stacks ``finishing_stacks`` Array of integers or floats +Winnings ``winnings`` Array of integers or floats +`ISO 4127 `_ currency ``currency`` String +Currency symbol ``currency_symbol`` String +Ante uniformity ``ante_trimming_status`` Boolean +Allocated time per action ``time_limit`` Integer or float +Time banks at the beginning of the hand ``time_banks`` Array of integers or floats +============================================================== ========================== =========================== Author ------ @@ -52,6 +56,11 @@ URL The ``url`` field contains a string URL relevant to the event. This field is particularly important for online poker hands where the venue might not be a physical location. Still, the annotator may choose to specify a relevant URL to the organizer's website or tournament website for physical poker hands, as well. The link should be prefixed with substrings like ``http://`` or ``https://`` to denote the internet communication protocol. +Venue +^^^^^ + +The ``venue`` field contains a string value that may or may not include the name of the venue in which the hand was played (e.g. online poker rooms). + Address ^^^^^^^ @@ -82,13 +91,18 @@ Time The ``time`` field should contain the approximate time the hand began as a TOML native local time without the timezone information. -If the ``time_zone`` field is defined, the time is assumed to be of that time zone. Otherwise, if every one of the following three fields -- ``city,`` ``region,`` and ``country`` -- are defined, it is assumed that the time is in the local time zone of the location of the hand. If the two previous conditions are not satisfied, the time is assumed to be in Coordinated Universal Time (UTC). +If the ``time_zone`` and/or ``time_zone_abbreviation`` field(s) is/are defined, the time is assumed to be of that/those. Otherwise, if every one of the following three fields -- ``city,`` ``region,`` and ``country`` -- are defined, it is assumed that the time is in the local time zone of the location of the hand. If the two previous conditions are not satisfied, the time is assumed to be in Coordinated Universal Time (UTC). Time Zone ^^^^^^^^^ The ``time_zone`` field contains a value of type string and must represent an IANA time zone in the latest version of the `IANA time zone `_ database available like ``America/Toronto``. +Time Zone Abbreviation +^^^^^^^^^^^^^^^^^^^^^^ + +The ``time_zone_abbreviation`` field contains a value of type string and must represent a time zone abbreviation like ``EDT`` or ``UTC``. + Day ^^^ @@ -133,7 +147,7 @@ The ``seat_count`` field denotes the number of seats and must have an integer va Table ^^^^^ -The ``table`` field denotes the table number the hand is played in, as an integer value. Typically, these are counted from ``1``. +The ``table`` field denotes the table name or number the hand is played in, as a string or an integer value. If numbered, these are typically counted from ``1``. Miscellaneous Fields -------------------- @@ -150,11 +164,21 @@ The ``finishing_stacks`` field denotes the final stacks as an array of non-negat The description of finishing stacks is helpful as the parser may not be aware of the granularity of the currency the chips are in or the rake applied in the end. For example, dollars can be broken down to cents whereas Japanese Yen must be of an integral value. On top of this, in a physical setting where chips are used, depending on the denominations, odd chip situations may arise where the player out of position is given the extra odd chip that cannot be broken further. It is, of course, infeasible to describe all the different chip values each player has in a poker hand history format. These inaccuracies are inherent drawbacks of using purely numerical representations to describe the stack values. It is worth noting that the inconsistencies caused by such circumstances only lead to extremely minor ambiguities in the final stack sizes that should not significantly impact the expected value calculations. +Winnings +^^^^^^^^ + +The ``winnings`` field denotes the winnings (i.e. collected pots) as an array of non-negative integers or floats. It may also be specified for a non-terminal hand history file, which can be interpreted as the winnings after all the action notations are applied (not very useful since winnings are zeros while the hand is ongoing). If rakes are applied the winnings should denote the post-rake values. + Currency ^^^^^^^^ The ``currency`` field denotes what currency the chips are in. The value must be of string and be one of three letter currency values in the `ISO 4127 `_ standard. +Currency Symbol +^^^^^^^^^^^^^^^ + +The ``currency_symbol`` field denotes the symbol of the currency the chips are in. The value must be a single-character string like ``"$"``. + Ante Trimming Status ^^^^^^^^^^^^^^^^^^^^ diff --git a/required.rst b/required.rst index a21166c..93b42d6 100644 --- a/required.rst +++ b/required.rst @@ -146,7 +146,7 @@ The ``min_bet`` field, a positive integer or a float, denotes the minimum bet in Starting Stacks ^^^^^^^^^^^^^^^ -The ``starting_stacks`` field denotes the starting stacks of each player and is an array of positive integers or floats of length equal to the number of players. All stack sizes must strictly be non-zero. Unknown stack values can be denoted as ``null``. +The ``starting_stacks`` field denotes the starting stacks of each player and is an array of positive integers or floats of length equal to the number of players. All stack sizes must strictly be non-zero. Unknown stack values can be denoted as ``inf`` (i.e. an infinite value). State Progression ----------------- @@ -237,7 +237,7 @@ This action represents completion, betting, or raising to a positive integral or Showing/Mucking Hole Cards ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The showdown action is performed at the end of the hand or after all players go all-in. It represents showing of the hole cards to try to win the pot or after an all-in, or mucking of the hole cards. This action accepts an optional argument of cards which, if supplied, must all be known. The omission of this field represents mucking while the inclusion represents showing. +The showdown action is performed at the end of the hand or after all players go all-in. It represents either the showing of the hole cards to try to win the pot, after an all-in, or after all other players fold or the mucking of the hole cards signifying the player's forfeiture on his or her stake of the pot. This action accepts an optional argument of cards. The omission of this argument represents mucking while the inclusion represents showing. If a hand is part of a tournament and the player elects to show, all his/her hole cards must be known (note that in all-in situations, active players are forced to show their hand). If it is a cash-game, then some or all of the cards in the argument may be unknown (e.g. ``??Ad``) to denote that the player chose to both not muck their hand and not show their hole cards (partially or completely). No-operations ^^^^^^^^^^^^^ diff --git a/spec.rst b/spec.rst index 063811d..b537152 100644 --- a/spec.rst +++ b/spec.rst @@ -5,43 +5,47 @@ The PHH format is a derivative of the `Tom's Obvious, Minimal Language (TOML) fo The PHH format puts restrictions on the naming and types of the key/values, with which the poker games are described. These definitions, named "fields", fall under two classifications. The first involves state construction and progression and must be specified. The second describes various miscellaneous information about the game and may be omitted by the annotator. The full fields are described below. -============================================================== ======================== ================================== ======== -Field Name TOML Native Type Required -============================================================== ======================== ================================== ======== -Variant code ``variant`` String yes -Antes ``antes`` Array of integers or floats yes -Blinds/Straddles ``blinds_or_straddles`` Array of integers or floats yes -Bring-in ``bring_in`` Integer or float yes -Small bet ``small_bet`` Integer or float yes -Big bet ``big_bet`` Integer or float yes -Min bet ``min_bet`` Integer or float yes -Starting stacks ``starting_stacks`` Array of integers, floats, or null yes -Actions ``actions`` Array of strings yes -Annotator full name or mononym ``author`` String no -Event name ``event`` String no -Event or organizer URL ``url`` String no -Venue street-level address ``address`` String no -Venue city ``city`` String no -Venue region, state, or province ``region`` String no -Venue postal code ``postal_code`` String no -Venue country ``country`` String no -Timestamp at the start of the hand ``time`` Local time no -`IANA time zone `_ ``time_zone`` String no -Event day ``day`` Integer no -Event month ``month`` Integer no -Event year ``year`` Integer no -Hand number ``hand`` Integer no -Tournament level ``level`` Integer no -Players' seat numbers ``seats`` Array of integers no -The number of seats ``seat_count`` Integer no -Table number ``table`` Integer no -Player full names or mononyms ``players`` Array of strings no -Final stacks ``finishing_stacks`` Array of integers or floats no -`ISO 4127 `_ currency ``currency`` String no -Ante uniformity ``ante_trimming_status`` Boolean no -Allocated time per action ``time_limit`` Integer or float no -Time banks at the beginning of the hand ``time_banks`` Array of integers or floats no -============================================================== ======================== ================================== ======== +============================================================== ========================== ================================== ======== +Field Name TOML Native Type Required +============================================================== ========================== ================================== ======== +Variant code ``variant`` String yes +Antes ``antes`` Array of integers or floats yes +Blinds/Straddles ``blinds_or_straddles`` Array of integers or floats yes +Bring-in ``bring_in`` Integer or float yes +Small bet ``small_bet`` Integer or float yes +Big bet ``big_bet`` Integer or float yes +Min bet ``min_bet`` Integer or float yes +Starting stacks ``starting_stacks`` Array of integers, floats, or null yes +Actions ``actions`` Array of strings yes +Annotator full name or mononym ``author`` String no +Event name ``event`` String no +Event or organizer URL ``url`` String no +Venue ``venue`` String no +Venue street-level address ``address`` String no +Venue city ``city`` String no +Venue region, state, or province ``region`` String no +Venue postal code ``postal_code`` String no +Venue country ``country`` String no +Timestamp at the start of the hand ``time`` Local time no +`IANA time zone `_ ``time_zone`` String no +Time zone abbreviation ``time_zone_abbreviation`` String no +Event day ``day`` Integer no +Event month ``month`` Integer no +Event year ``year`` Integer no +Hand name or number ``hand`` String or integer no +Tournament level ``level`` Integer no +Players' seat numbers ``seats`` Array of integers no +The number of seats ``seat_count`` Integer no +Table name or number ``table`` String or integer no +Player full names or mononyms ``players`` Array of strings no +Final stacks ``finishing_stacks`` Array of integers or floats no +Winnings ``winnings`` Array of integers or floats no +`ISO 4127 `_ currency ``currency`` String no +Currency symbol ``currency_symbol`` String no +Ante uniformity ``ante_trimming_status`` Boolean no +Allocated time per action ``time_limit`` Integer or float no +Time banks at the beginning of the hand ``time_banks`` Array of integers or floats no +============================================================== ========================== ================================== ======== Objective ---------