Skip to content

Commit

Permalink
Merge pull request #24 from carlzoo/docs/pydocs
Browse files Browse the repository at this point in the history
Add Documentation
  • Loading branch information
carlzoo authored Feb 5, 2023
2 parents b2cf7e1 + e657b3b commit 6967bed
Show file tree
Hide file tree
Showing 24 changed files with 313 additions and 10 deletions.
12 changes: 11 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -o docs sportsbooklib
```

## Thank you for your contributions!
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions docs/sportsbooklib/calculators/exceptions.md
Original file line number Diff line number Diff line change
@@ -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
33 changes: 33 additions & 0 deletions docs/sportsbooklib/calculators/hold_calc.md
Original file line number Diff line number Diff line change
@@ -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
21 changes: 21 additions & 0 deletions docs/sportsbooklib/calculators/implied_odds_calc.md
Original file line number Diff line number Diff line change
@@ -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:
<implied_probability> List[Decimal]: List of implied probability in the respective order of the input odds
<fair_odds> List[Decimal]: List of fair odds in the respective order of the input odds
9 changes: 9 additions & 0 deletions docs/sportsbooklib/calculators/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Module sportsbooklib.calculators
================================
The calculator submodule.

Sub-modules
-----------
* sportsbooklib.calculators.exceptions
* sportsbooklib.calculators.hold_calc
* sportsbooklib.calculators.implied_odds_calc
8 changes: 8 additions & 0 deletions docs/sportsbooklib/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Module sportsbooklib
====================
Top-level package for sportsbooklib.

Sub-modules
-----------
* sportsbooklib.calculators
* sportsbooklib.models
8 changes: 8 additions & 0 deletions docs/sportsbooklib/models/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Module sportsbooklib.models
===========================
The models submodule.

Sub-modules
-----------
* sportsbooklib.models.odds
* sportsbooklib.models.selection
31 changes: 31 additions & 0 deletions docs/sportsbooklib/models/odds/enums.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
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`
:
13 changes: 13 additions & 0 deletions docs/sportsbooklib/models/odds/exceptions.md
Original file line number Diff line number Diff line change
@@ -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
9 changes: 9 additions & 0 deletions docs/sportsbooklib/models/odds/index.md
Original file line number Diff line number Diff line change
@@ -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
44 changes: 44 additions & 0 deletions docs/sportsbooklib/models/odds/odds.md
Original file line number Diff line number Diff line change
@@ -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)`
:
7 changes: 7 additions & 0 deletions docs/sportsbooklib/models/selection/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Module sportsbooklib.models.selection
=====================================
The selection submodule.

Sub-modules
-----------
* sportsbooklib.models.selection.selection
15 changes: 15 additions & 0 deletions docs/sportsbooklib/models/selection/selection.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 1 addition & 4 deletions sportsbooklib/__init__.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Top-level package for surebet."""
"""Top-level package for sportsbooklib."""

__author__ = """Carl Zhou"""
__email__ = 'dev@carlzhou.com'
Expand Down
3 changes: 3 additions & 0 deletions sportsbooklib/calculators/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
"""
The calculators submodule.
"""
27 changes: 27 additions & 0 deletions sportsbooklib/calculators/hold_calc.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,36 @@


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])
17 changes: 15 additions & 2 deletions sportsbooklib/calculators/implied_odds_calc.py
Original file line number Diff line number Diff line change
@@ -1,13 +1,26 @@
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:
<implied_probability> List[Decimal]: List of implied probability in the respective order of the input odds
<fair_odds> List[Decimal]: List of fair odds in the respective order of the input odds
'''
if len(odds) < 2:
raise InvalidNumberOfInputsException
Expand Down
5 changes: 3 additions & 2 deletions sportsbooklib/models/__init__.py
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
The models submodule.
"""
4 changes: 3 additions & 1 deletion sportsbooklib/models/odds/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
__all__ = ["echo", "surround", "reverse"]
"""
The submodule with the Odds class.
"""
9 changes: 9 additions & 0 deletions sportsbooklib/models/odds/enums.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@


class OddsFormat(Enum):
"""
The following are valid values for 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'
Expand Down
12 changes: 12 additions & 0 deletions sportsbooklib/models/odds/odds.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,18 @@


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
Expand Down
3 changes: 3 additions & 0 deletions sportsbooklib/models/selection/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
"""
The selection submodule.
"""
Loading

0 comments on commit 6967bed

Please sign in to comment.