Odds Conversion Utilities#

This submodule provides a simple and reliable way to convert betting odds from different common formats into a standardized Decimal format.

Since most analytical functions in penaltyblog expect odds to be in decimal format, this utility is a crucial first step for working with data from various sources.

Supported Odds Formats#

The converter understands the three most common odds formats used worldwide.

  • Decimal Odds (e.g., ``2.50``, ``1.80``): Represents the total amount returned for a 1-unit stake, including the original stake. A stake of £10 at 2.50 odds returns £25 (£15 profit + £10 stake). This is typically the standard format in Europe, Australia, and Canada.

  • American (Moneyline) Odds (e.g., ``+150``, ``-200``): A positive number shows how much profit you win for a 100-unit stake (e.g., +150 means you win £150 profit for a £100 stake). A negative number shows how much you must stake to win 100 units of profit (e.g., -200 means you must stake £200 to win £100 profit).

  • Fractional Odds (e.g., ``”5/2”``, ``”2/1”``): Shows the profit relative to the stake. The first number is the profit, the second is the stake. For example, 5/2 (read “five to two”) means you win £5 profit for every £2 you stake. This format is common in the UK and Ireland.

The convert_odds Function#

This is the primary, easy-to-use function for all conversions. It takes a list of odds in a specified format and returns them as a list of decimal odds.

penaltyblog.betting.convert_odds(
    odds: List[Union[float, str]],
    odds_format: Union[str, OddsFormat],
    market_names: List[str] = None,
) -> List[float]

Parameters#

  • odds (List[Union[float, str]]): The list of odds you want to convert. This can be numbers for Decimal/American or strings for Fractional.

  • odds_format (str | OddsFormat): The format of the odds you are providing. This can be a string (e.g., "american", "fractional") or an OddsFormat enum member.

  • market_names (List[str], optional): Optional names for each market outcome; this parameter is included for API consistency but is not used in the conversion calculation.

Returns#

List[float]: A new list containing the odds converted to the Decimal format.

Usage Examples#

Converting American Odds to Decimal#

import penaltyblog as pb

american_odds = [+170, +130, -110]

decimal_odds = pb.betting.convert_odds(american_odds, "american")

print(f"American: {american_odds}")
print(f"Decimal:  {decimal_odds}")

American: [170, 130, -110]
Decimal:  [2.7, 2.3, 1.9090909090909092]

Converting Fractional Odds to Decimal#

import penaltyblog as pb

fractional_odds = ['7/4', '13/10', '7/2']

decimal_odds = pb.betting.convert_odds(fractional_odds, "fractional")

print(f"Fractional: {fractional_odds}")
print(f"Decimal:    {decimal_odds}")

Fractional: ['7/4', '13/10', '7/2']
Decimal:    [2.75, 2.3, 4.5]