From 25a09586c883037777d4122bd055bbfbb4a3f57d Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 14:44:37 -0500 Subject: [PATCH 1/7] add doc instructions --- CONTRIBUTING.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe10e53..9623efa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,8 +13,18 @@ If you have an idea for a new feature or improvement, please open an issue to di ## To submit a pull request: 1. Fork the repository. 2. Create a new branch for your changes. -3. Make your changes. +3. Make your changes. Make sure all changes are documented using docstrings and use pdoc3 to generate documentation files. 4. Push your changes to your forked repository. 5. Submit a pull request to the main repository. +## Generating doucmentation +Use pdoc3 to generate documentation +``` +pip install pdoc3 +``` +In the project root directory: +``` +pdoc --html -o docs sportsbooklib +``` + ## Thank you for your contributions! From f10abc26f95308a5fbc8c00b223dd3f8f1cf5940 Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 16:39:28 -0500 Subject: [PATCH 2/7] remove invalid __all__ --- sportsbooklib/models/odds/__init__.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sportsbooklib/models/odds/__init__.py b/sportsbooklib/models/odds/__init__.py index a6ab47b..e69de29 100644 --- a/sportsbooklib/models/odds/__init__.py +++ b/sportsbooklib/models/odds/__init__.py @@ -1 +0,0 @@ -__all__ = ["echo", "surround", "reverse"] From 7810e3e7cf063ddd0482da839a6e56ad21cadc75 Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 17:22:13 -0500 Subject: [PATCH 3/7] fix module name --- sportsbooklib/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sportsbooklib/__init__.py b/sportsbooklib/__init__.py index ad41233..0854161 100644 --- a/sportsbooklib/__init__.py +++ b/sportsbooklib/__init__.py @@ -1,7 +1,7 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- -"""Top-level package for surebet.""" +"""Top-level package for sportsbooklib.""" __author__ = """Carl Zhou""" __email__ = 'dev@carlzhou.com' From 30c29cb43856282b1b517ee37f45e908182d3c1b Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 18:48:57 -0500 Subject: [PATCH 4/7] add documentation --- CONTRIBUTING.md | 2 +- docs/sportsbooklib/calculators/exceptions.md | 13 ++++++ docs/sportsbooklib/calculators/hold_calc.md | 33 ++++++++++++++ .../calculators/implied_odds_calc.md | 21 +++++++++ docs/sportsbooklib/calculators/index.md | 9 ++++ docs/sportsbooklib/index.md | 8 ++++ docs/sportsbooklib/models/index.md | 8 ++++ docs/sportsbooklib/models/odds/enums.md | 30 +++++++++++++ docs/sportsbooklib/models/odds/exceptions.md | 13 ++++++ docs/sportsbooklib/models/odds/index.md | 9 ++++ docs/sportsbooklib/models/odds/odds.md | 44 +++++++++++++++++++ docs/sportsbooklib/models/selection/index.md | 7 +++ .../models/selection/selection.md | 15 +++++++ sportsbooklib/__init__.py | 3 -- sportsbooklib/calculators/__init__.py | 3 ++ sportsbooklib/calculators/hold_calc.py | 26 +++++++++++ .../calculators/implied_odds_calc.py | 16 ++++++- sportsbooklib/models/__init__.py | 5 ++- sportsbooklib/models/odds/__init__.py | 3 ++ sportsbooklib/models/odds/enums.py | 7 +++ sportsbooklib/models/odds/odds.py | 11 +++++ sportsbooklib/models/selection/__init__.py | 3 ++ sportsbooklib/models/selection/selection.py | 11 +++++ 23 files changed, 292 insertions(+), 8 deletions(-) create mode 100644 docs/sportsbooklib/calculators/exceptions.md create mode 100644 docs/sportsbooklib/calculators/hold_calc.md create mode 100644 docs/sportsbooklib/calculators/implied_odds_calc.md create mode 100644 docs/sportsbooklib/calculators/index.md create mode 100644 docs/sportsbooklib/index.md create mode 100644 docs/sportsbooklib/models/index.md create mode 100644 docs/sportsbooklib/models/odds/enums.md create mode 100644 docs/sportsbooklib/models/odds/exceptions.md create mode 100644 docs/sportsbooklib/models/odds/index.md create mode 100644 docs/sportsbooklib/models/odds/odds.md create mode 100644 docs/sportsbooklib/models/selection/index.md create mode 100644 docs/sportsbooklib/models/selection/selection.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9623efa..63c9f74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ pip install pdoc3 ``` In the project root directory: ``` -pdoc --html -o docs sportsbooklib +pdoc -o docs sportsbooklib ``` ## Thank you for your contributions! diff --git a/docs/sportsbooklib/calculators/exceptions.md b/docs/sportsbooklib/calculators/exceptions.md new file mode 100644 index 0000000..919673f --- /dev/null +++ b/docs/sportsbooklib/calculators/exceptions.md @@ -0,0 +1,13 @@ +Module sportsbooklib.calculators.exceptions +=========================================== + +Classes +------- + +`InvalidNumberOfInputsException(*args, **kwargs)` +: Must input at least 2 odds + + ### Ancestors (in MRO) + + * builtins.Exception + * builtins.BaseException \ No newline at end of file diff --git a/docs/sportsbooklib/calculators/hold_calc.md b/docs/sportsbooklib/calculators/hold_calc.md new file mode 100644 index 0000000..dcdcc23 --- /dev/null +++ b/docs/sportsbooklib/calculators/hold_calc.md @@ -0,0 +1,33 @@ +Module sportsbooklib.calculators.hold_calc +========================================== + +Functions +--------- + + +`get_hold(odds: List[sportsbooklib.models.odds.odds.Odds]) ‑> decimal.Decimal` +: Calculate hold, given list of Odds, where length of list > 1 + + Parameters + ---------- + odds : List[Odds] + List of odds to calculate hold + + Returns + ------- + Decimal + The hold value as a Decimal + + +`get_hold_for_selections(selections: List[sportsbooklib.models.selection.selection.Selection]) ‑> decimal.Decimal` +: Calculate hold, given list of Selection's odds, where length of list > 1 + + Parameters + ---------- + odds : List[Selection] + List of Selection to calculate hold + + Returns + ------- + Decimal + The hold value as a Decimal \ No newline at end of file diff --git a/docs/sportsbooklib/calculators/implied_odds_calc.md b/docs/sportsbooklib/calculators/implied_odds_calc.md new file mode 100644 index 0000000..9323c60 --- /dev/null +++ b/docs/sportsbooklib/calculators/implied_odds_calc.md @@ -0,0 +1,21 @@ +Module sportsbooklib.calculators.implied_odds_calc +================================================== + +Functions +--------- + + +`get_implied_probability(odds: List[sportsbooklib.models.odds.odds.Odds]) ‑> Mapping[str, List[decimal.Decimal]]` +: Given list of Odds, calculate the implied probability and fair odds. + Based on https://github.com/octosport/octopy/blob/master/octopy/implied.py + + Parameters + ---------- + odds : List[Odds] + List of odds for calculation. + + Returns + ------- + Dict: + List[Decimal]: List of implied probability in the respective order of the input odds + List[Decimal]: List of fair odds in the respective order of the input odds \ No newline at end of file diff --git a/docs/sportsbooklib/calculators/index.md b/docs/sportsbooklib/calculators/index.md new file mode 100644 index 0000000..10b6b48 --- /dev/null +++ b/docs/sportsbooklib/calculators/index.md @@ -0,0 +1,9 @@ +Module sportsbooklib.calculators +================================ +The calculator submodule. + +Sub-modules +----------- +* sportsbooklib.calculators.exceptions +* sportsbooklib.calculators.hold_calc +* sportsbooklib.calculators.implied_odds_calc \ No newline at end of file diff --git a/docs/sportsbooklib/index.md b/docs/sportsbooklib/index.md new file mode 100644 index 0000000..eb81c00 --- /dev/null +++ b/docs/sportsbooklib/index.md @@ -0,0 +1,8 @@ +Module sportsbooklib +==================== +Top-level package for sportsbooklib. + +Sub-modules +----------- +* sportsbooklib.calculators +* sportsbooklib.models \ No newline at end of file diff --git a/docs/sportsbooklib/models/index.md b/docs/sportsbooklib/models/index.md new file mode 100644 index 0000000..7d95b6d --- /dev/null +++ b/docs/sportsbooklib/models/index.md @@ -0,0 +1,8 @@ +Module sportsbooklib.models +=========================== +The models submodule. + +Sub-modules +----------- +* sportsbooklib.models.odds +* sportsbooklib.models.selection \ No newline at end of file diff --git a/docs/sportsbooklib/models/odds/enums.md b/docs/sportsbooklib/models/odds/enums.md new file mode 100644 index 0000000..4d09053 --- /dev/null +++ b/docs/sportsbooklib/models/odds/enums.md @@ -0,0 +1,30 @@ +Module sportsbooklib.models.odds.enums +====================================== + +Classes +------- + +`OddsFormat(value, names=None, *, module=None, qualname=None, type=None, start=1)` +: OddsFormat: + - US - US Format (-110) + - EU - European Format (1.909) + - HK - Hong Kong Format (0.909) + - UK - UK Fractional Format (10/11) + + ### Ancestors (in MRO) + + * enum.Enum + + ### Class variables + + `EU` + : + + `HK` + : + + `UK` + : + + `US` + : \ No newline at end of file diff --git a/docs/sportsbooklib/models/odds/exceptions.md b/docs/sportsbooklib/models/odds/exceptions.md new file mode 100644 index 0000000..f338005 --- /dev/null +++ b/docs/sportsbooklib/models/odds/exceptions.md @@ -0,0 +1,13 @@ +Module sportsbooklib.models.odds.exceptions +=========================================== + +Classes +------- + +`InvalidOddsFormatException(*args, **kwargs)` +: Odds value and/or format is invalid + + ### Ancestors (in MRO) + + * builtins.Exception + * builtins.BaseException \ No newline at end of file diff --git a/docs/sportsbooklib/models/odds/index.md b/docs/sportsbooklib/models/odds/index.md new file mode 100644 index 0000000..f3da480 --- /dev/null +++ b/docs/sportsbooklib/models/odds/index.md @@ -0,0 +1,9 @@ +Module sportsbooklib.models.odds +================================ +The submodule with the Odds class. + +Sub-modules +----------- +* sportsbooklib.models.odds.enums +* sportsbooklib.models.odds.exceptions +* sportsbooklib.models.odds.odds \ No newline at end of file diff --git a/docs/sportsbooklib/models/odds/odds.md b/docs/sportsbooklib/models/odds/odds.md new file mode 100644 index 0000000..0079624 --- /dev/null +++ b/docs/sportsbooklib/models/odds/odds.md @@ -0,0 +1,44 @@ +Module sportsbooklib.models.odds.odds +===================================== + +Classes +------- + +`Odds(value: Union[int, fractions.Fraction, decimal.Decimal], format: sportsbooklib.models.odds.enums.OddsFormat)` +: The Odds Object. + + Attributes + ---------- + value : Union[int, Fraction, Decimal] + The odds value as an integer, Decimal or Fraction + format : OddsFormat + The format of the odds as OddsFormat (US, EU, HK, UK) + + ### Methods + + `convert_to_eu_odds(self)` + : + + `convert_to_hk_odds(self)` + : + + `convert_to_uk_odds(self)` + : + + `convert_to_us_odds(self)` + : + + `parse_odds_value(self)` + : + + `set_eu_odds(self)` + : + + `set_hk_odds(self)` + : + + `set_uk_odds(self)` + : + + `set_us_odds(self)` + : \ No newline at end of file diff --git a/docs/sportsbooklib/models/selection/index.md b/docs/sportsbooklib/models/selection/index.md new file mode 100644 index 0000000..a1cb0ba --- /dev/null +++ b/docs/sportsbooklib/models/selection/index.md @@ -0,0 +1,7 @@ +Module sportsbooklib.models.selection +===================================== +The selection submodule. + +Sub-modules +----------- +* sportsbooklib.models.selection.selection \ No newline at end of file diff --git a/docs/sportsbooklib/models/selection/selection.md b/docs/sportsbooklib/models/selection/selection.md new file mode 100644 index 0000000..9bee457 --- /dev/null +++ b/docs/sportsbooklib/models/selection/selection.md @@ -0,0 +1,15 @@ +Module sportsbooklib.models.selection.selection +=============================================== + +Classes +------- + +`Selection(name: str, odds: sportsbooklib.models.odds.odds.Odds)` +: The Selection Object. + + Attributes + ---------- + name : str + Name of the selection. + odds : Odds + The Odds object associated with the selection. \ No newline at end of file diff --git a/sportsbooklib/__init__.py b/sportsbooklib/__init__.py index 0854161..700c392 100644 --- a/sportsbooklib/__init__.py +++ b/sportsbooklib/__init__.py @@ -1,6 +1,3 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- - """Top-level package for sportsbooklib.""" __author__ = """Carl Zhou""" diff --git a/sportsbooklib/calculators/__init__.py b/sportsbooklib/calculators/__init__.py index e69de29..3cba922 100644 --- a/sportsbooklib/calculators/__init__.py +++ b/sportsbooklib/calculators/__init__.py @@ -0,0 +1,3 @@ +""" +The calculator submodule. +""" diff --git a/sportsbooklib/calculators/hold_calc.py b/sportsbooklib/calculators/hold_calc.py index a62a20e..5bf17cb 100644 --- a/sportsbooklib/calculators/hold_calc.py +++ b/sportsbooklib/calculators/hold_calc.py @@ -6,9 +6,35 @@ def get_hold(odds: List[Odds]) -> Decimal: + """ + Calculate hold, given list of Odds, where length of list > 1 + + Parameters + ---------- + odds : List[Odds] + List of odds to calculate hold + + Returns + ------- + Decimal + The hold value as a Decimal + """ implied_odds_result = get_implied_probability(odds) return sum(implied_odds_result['implied_probability']) - Decimal(1) def get_hold_for_selections(selections: List[Selection]) -> Decimal: + """ + Calculate hold, given list of Selection's odds, where length of list > 1 + + Parameters + ---------- + odds : List[Selection] + List of Selection to calculate hold + + Returns + ------- + Decimal + The hold value as a Decimal + """ return get_hold([selection.odds for selection in selections]) diff --git a/sportsbooklib/calculators/implied_odds_calc.py b/sportsbooklib/calculators/implied_odds_calc.py index afa59d3..4bfd10e 100644 --- a/sportsbooklib/calculators/implied_odds_calc.py +++ b/sportsbooklib/calculators/implied_odds_calc.py @@ -1,13 +1,25 @@ from decimal import Decimal -from typing import List +from typing import List, Mapping import numpy as np from sportsbooklib.calculators.exceptions import InvalidNumberOfInputsException from sportsbooklib.models.odds.odds import Odds -def get_implied_probability(odds: List[Odds]): +def get_implied_probability(odds: List[Odds]) -> Mapping[str, List[Decimal]]: ''' + Given list of Odds, calculate the implied probability and fair odds. Based on https://github.com/octosport/octopy/blob/master/octopy/implied.py + + Parameters + ---------- + odds : List[Odds] + List of odds for calculation. + + Returns + ------- + Dict: + List[Decimal]: List of implied probability in the respective order of the input odds + List[Decimal]: List of fair odds in the respective order of the input odds ''' if len(odds) < 2: raise InvalidNumberOfInputsException diff --git a/sportsbooklib/models/__init__.py b/sportsbooklib/models/__init__.py index faa18be..0c2bace 100644 --- a/sportsbooklib/models/__init__.py +++ b/sportsbooklib/models/__init__.py @@ -1,2 +1,3 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- +""" +The models submodule. +""" diff --git a/sportsbooklib/models/odds/__init__.py b/sportsbooklib/models/odds/__init__.py index e69de29..9481691 100644 --- a/sportsbooklib/models/odds/__init__.py +++ b/sportsbooklib/models/odds/__init__.py @@ -0,0 +1,3 @@ +""" +The submodule with the Odds class. +""" diff --git a/sportsbooklib/models/odds/enums.py b/sportsbooklib/models/odds/enums.py index a8d7bcf..1408d9c 100644 --- a/sportsbooklib/models/odds/enums.py +++ b/sportsbooklib/models/odds/enums.py @@ -2,6 +2,13 @@ class OddsFormat(Enum): + """ + OddsFormat: + - US - US Format (-110) + - EU - European Format (1.909) + - HK - Hong Kong Format (0.909) + - UK - UK Fractional Format (10/11) + """ US = 'US' EU = 'EU' UK = 'UK' diff --git a/sportsbooklib/models/odds/odds.py b/sportsbooklib/models/odds/odds.py index a7b8849..1006ceb 100644 --- a/sportsbooklib/models/odds/odds.py +++ b/sportsbooklib/models/odds/odds.py @@ -9,6 +9,17 @@ class Odds: + """ + The Odds Object. + + Attributes + ---------- + value : Union[int, Fraction, Decimal] + The odds value as an integer, Decimal or Fraction + format : OddsFormat + The format of the odds as OddsFormat (US, EU, HK, UK) + """ + def __init__(self, value: Union[int, Fraction, Decimal], format: OddsFormat): self.value = value self.format = format diff --git a/sportsbooklib/models/selection/__init__.py b/sportsbooklib/models/selection/__init__.py index e69de29..6b7c724 100644 --- a/sportsbooklib/models/selection/__init__.py +++ b/sportsbooklib/models/selection/__init__.py @@ -0,0 +1,3 @@ +""" +The selection submodule. +""" diff --git a/sportsbooklib/models/selection/selection.py b/sportsbooklib/models/selection/selection.py index 14c5a39..c46b063 100644 --- a/sportsbooklib/models/selection/selection.py +++ b/sportsbooklib/models/selection/selection.py @@ -2,6 +2,17 @@ class Selection: + """ + The Selection Object. + + Attributes + ---------- + name : str + Name of the selection. + odds : Odds + The Odds object associated with the selection. + """ + def __init__(self, name: str, odds: Odds): self.name = name self.odds = odds From 33e6b391b99659536e95ce49f42bbce0d376481b Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 18:54:23 -0500 Subject: [PATCH 5/7] update readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 718077f..6c89590 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,9 @@ # sportsbooklib Python module for performing sportsbook odds calculations +# Documentation +Documentation can be found in the [docs](https://github.com/carlzoo/sportsbooklib/tree/main/docs) directory + # Setup Requirements: Python >=3.6 From 3a96a29c631381327a5c4e745691692dd8dfe38a Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 18:56:54 -0500 Subject: [PATCH 6/7] fix formatting --- docs/sportsbooklib/models/odds/enums.md | 1 + sportsbooklib/models/odds/enums.py | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/sportsbooklib/models/odds/enums.md b/docs/sportsbooklib/models/odds/enums.md index 4d09053..adeb9d0 100644 --- a/docs/sportsbooklib/models/odds/enums.md +++ b/docs/sportsbooklib/models/odds/enums.md @@ -6,6 +6,7 @@ Classes `OddsFormat(value, names=None, *, module=None, qualname=None, type=None, start=1)` : OddsFormat: + - US - US Format (-110) - EU - European Format (1.909) - HK - Hong Kong Format (0.909) diff --git a/sportsbooklib/models/odds/enums.py b/sportsbooklib/models/odds/enums.py index 1408d9c..6572fc1 100644 --- a/sportsbooklib/models/odds/enums.py +++ b/sportsbooklib/models/odds/enums.py @@ -4,6 +4,7 @@ class OddsFormat(Enum): """ OddsFormat: + - US - US Format (-110) - EU - European Format (1.909) - HK - Hong Kong Format (0.909) From e657b3b9acfdff7eec0030bdea05307d0933ff54 Mon Sep 17 00:00:00 2001 From: Carl Zhou Date: Sat, 4 Feb 2023 19:04:08 -0500 Subject: [PATCH 7/7] fix newline formatting --- sportsbooklib/calculators/__init__.py | 2 +- sportsbooklib/calculators/hold_calc.py | 1 + sportsbooklib/calculators/implied_odds_calc.py | 1 + sportsbooklib/models/odds/enums.py | 3 ++- sportsbooklib/models/odds/odds.py | 1 + sportsbooklib/models/selection/selection.py | 1 + 6 files changed, 7 insertions(+), 2 deletions(-) diff --git a/sportsbooklib/calculators/__init__.py b/sportsbooklib/calculators/__init__.py index 3cba922..2d3ce1b 100644 --- a/sportsbooklib/calculators/__init__.py +++ b/sportsbooklib/calculators/__init__.py @@ -1,3 +1,3 @@ """ -The calculator submodule. +The calculators submodule. """ diff --git a/sportsbooklib/calculators/hold_calc.py b/sportsbooklib/calculators/hold_calc.py index 5bf17cb..180b5e6 100644 --- a/sportsbooklib/calculators/hold_calc.py +++ b/sportsbooklib/calculators/hold_calc.py @@ -7,6 +7,7 @@ def get_hold(odds: List[Odds]) -> Decimal: """ + Calculate hold, given list of Odds, where length of list > 1 Parameters diff --git a/sportsbooklib/calculators/implied_odds_calc.py b/sportsbooklib/calculators/implied_odds_calc.py index 4bfd10e..e96a410 100644 --- a/sportsbooklib/calculators/implied_odds_calc.py +++ b/sportsbooklib/calculators/implied_odds_calc.py @@ -7,6 +7,7 @@ def get_implied_probability(odds: List[Odds]) -> Mapping[str, List[Decimal]]: ''' + Given list of Odds, calculate the implied probability and fair odds. Based on https://github.com/octosport/octopy/blob/master/octopy/implied.py diff --git a/sportsbooklib/models/odds/enums.py b/sportsbooklib/models/odds/enums.py index 6572fc1..efd2ff7 100644 --- a/sportsbooklib/models/odds/enums.py +++ b/sportsbooklib/models/odds/enums.py @@ -3,7 +3,8 @@ class OddsFormat(Enum): """ - OddsFormat: + + The following are valid values for OddsFormat: - US - US Format (-110) - EU - European Format (1.909) diff --git a/sportsbooklib/models/odds/odds.py b/sportsbooklib/models/odds/odds.py index 1006ceb..e128bc0 100644 --- a/sportsbooklib/models/odds/odds.py +++ b/sportsbooklib/models/odds/odds.py @@ -10,6 +10,7 @@ class Odds: """ + The Odds Object. Attributes diff --git a/sportsbooklib/models/selection/selection.py b/sportsbooklib/models/selection/selection.py index c46b063..6773687 100644 --- a/sportsbooklib/models/selection/selection.py +++ b/sportsbooklib/models/selection/selection.py @@ -3,6 +3,7 @@ class Selection: """ + The Selection Object. Attributes