elo-system 1.0.0__tar.gz

elo_system-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan V
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elo_system-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: elo-system
+Version: 1.0.0
+Summary: Elo rating system for fantasy sports leagues (Fantrax NBA, with multi-season dynasty support).
+Author-email: Rohan V <r.vahalia@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/riders994/eloSystem
+Keywords: elo,fantasy,sports,fantrax,sleeper,rating
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: requests>=2.31
+Provides-Extra: sleeper
+Requires-Dist: sleeper>=2.0; extra == "sleeper"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"
+Requires-Dist: pyflakes>=3; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# elo-system
+
+An Elo rating system for fantasy sports leagues. It scrapes weekly scoreboards
+from a fantasy platform, converts them into per-week Elo ratings, and supports
+multi-season **dynasty** ratings with an offseason regression-to-mean
+adjustment.
+
+- **Platforms:** Fantrax (NBA, head-to-head categories) is implemented. A
+  Sleeper backend is planned.
+- **Outputs:** per-season and combined-dynasty rating frames, written to CSV
+  (a Postgres backend is scaffolded but not yet wired up).
+
+## Installation
+
+The project depends on a fork of `fantraxapi` (the PyPI release is broken for
+H2H-rotisserie leagues), so it installs from source rather than from PyPI:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .            # add [dev] for the test/lint tooling
+```
+
+`requirements.frozen` holds the exact, reproducible dependency pins (including
+the fantraxapi fork commit) used during development.
+
+## Layout
+
+```
+elo_system/
+  elo_system.py            EloSystem orchestrator (config + reader/writer wiring)
+  tools/
+    elo_league.py          EloLeague: season management + run/dynasty pipeline
+    elo_data.py            EloCSV / EloSQL persistence backends
+    basics/                LeagueBase/DataBase, Elo math, config IO, constants
+    helpers/               scraper, league, formatter, calculator, frame_manager
+```
+
+## Tests
+
+```bash
+python -m pytest          # run from the repo root
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development notes and conventions,
+and [CHANGELOG.md](CHANGELOG.md) for release history.

elo_system-1.0.0/README.md

@@ -0,0 +1,46 @@
+# elo-system
+
+An Elo rating system for fantasy sports leagues. It scrapes weekly scoreboards
+from a fantasy platform, converts them into per-week Elo ratings, and supports
+multi-season **dynasty** ratings with an offseason regression-to-mean
+adjustment.
+
+- **Platforms:** Fantrax (NBA, head-to-head categories) is implemented. A
+  Sleeper backend is planned.
+- **Outputs:** per-season and combined-dynasty rating frames, written to CSV
+  (a Postgres backend is scaffolded but not yet wired up).
+
+## Installation
+
+The project depends on a fork of `fantraxapi` (the PyPI release is broken for
+H2H-rotisserie leagues), so it installs from source rather than from PyPI:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .            # add [dev] for the test/lint tooling
+```
+
+`requirements.frozen` holds the exact, reproducible dependency pins (including
+the fantraxapi fork commit) used during development.
+
+## Layout
+
+```
+elo_system/
+  elo_system.py            EloSystem orchestrator (config + reader/writer wiring)
+  tools/
+    elo_league.py          EloLeague: season management + run/dynasty pipeline
+    elo_data.py            EloCSV / EloSQL persistence backends
+    basics/                LeagueBase/DataBase, Elo math, config IO, constants
+    helpers/               scraper, league, formatter, calculator, frame_manager
+```
+
+## Tests
+
+```bash
+python -m pytest          # run from the repo root
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development notes and conventions,
+and [CHANGELOG.md](CHANGELOG.md) for release history.

elo_system-1.0.0/elo_system/_vendor/__init__.py

@@ -0,0 +1 @@
+"""Vendored third-party packages bundled with elo_system."""

elo_system-1.0.0/elo_system/_vendor/fantraxapi/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 meisnate12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elo_system-1.0.0/elo_system/_vendor/fantraxapi/__init__.py

@@ -0,0 +1,25 @@
+# NOTE: Vendored copy of riders994/FantraxAPI (fork of meisnate12/FantraxAPI).
+# Pinned to commit ee81bea250024cba670cd0a5a1a1849150dbb38c (@stable, v1.0.1).
+# Absolute ``fantraxapi`` imports were rewritten to relative imports so the
+# package works under ``elo_system._vendor.fantraxapi``. See ./LICENSE (MIT).
+from .exceptions import FantraxException, NotLoggedIn, NotMemberOfLeague, NotTeamInLeague
+from .objs import League
+from .objs import League as FantraxAPI
+
+__version__ = "1.0.1"
+__author__ = "Nathan Taggart"
+__credits__ = "meisnate12"
+__package_name__ = "fantraxapi"
+__project_name__ = "FantraxAPI"
+__description__ = "A lightweight Python library for The Fantrax API."
+__url__ = "https://github.com/meisnate12/FantraxAPI"
+__email__ = "meisnate12@gmail.com"
+__license__ = "MIT License"
+__all__ = [
+    "FantraxAPI",
+    "FantraxException",
+    "NotLoggedIn",
+    "NotMemberOfLeague",
+    "NotTeamInLeague",
+    "League",
+]

elo_system-1.0.0/elo_system/_vendor/fantraxapi/api.py

@@ -0,0 +1,135 @@
+from datetime import date
+from json.decoder import JSONDecodeError
+from typing import TYPE_CHECKING, ParamSpec
+
+from requests import Session
+
+from .exceptions import FantraxException, NotLoggedIn, NotMemberOfLeague
+
+if TYPE_CHECKING:
+    from .objs import League
+
+
+Param: ParamSpec = ParamSpec("Param")
+default_session: Session = Session()
+
+debug: bool = False
+
+
+class Method:
+    def __init__(self, name: str, **kwargs: Param.kwargs) -> None:
+        self.name: str = name
+        self.kwargs: dict = kwargs
+        self.response: dict | None = None
+
+    def msg_block(self, league_id: str) -> dict[str, str]:
+        output_data = {"leagueId": league_id}
+        for key, value in self.kwargs.items():
+            if value is not None:
+                if isinstance(value, date):
+                    output_data[key] = value.strftime("%Y-%m-%d")
+                else:
+                    output_data[key] = str(value)
+        return {"method": self.name, "data": output_data}
+
+
+def request(league: "League", methods: list[Method] | Method) -> dict:
+    return _request(league.league_id, methods, session=league.session)
+
+
+def _request(league_id: str, methods: list[Method] | Method, session: Session | None = None) -> list[dict] | dict:
+    if not isinstance(methods, list):
+        methods = [methods]
+    json_data = {"msgs": [m.msg_block(league_id) for m in methods]}
+    if session is None:
+        session = default_session
+    if debug:
+        print(f"{'_' * 100} Request JSON  {'_' * 100}")
+        print(json_data)
+    response = session.post("https://www.fantrax.com/fxpa/req", params={"leagueId": league_id}, json=json_data)
+    try:
+        response_json = response.json()
+    except JSONDecodeError as e:
+        raise FantraxException(f"Invalid JSON Response to {methods}: {e}\nData: {json_data}")
+    if debug:
+        print(f"{'-' * 100} Response JSON {'-' * 100}")
+        print("-" * 100)
+        print(response_json)
+        print("^" * 215)
+    if response.status_code >= 400:
+        raise FantraxException(f"({response.status_code} [{response.reason}]) {response_json}")
+    if "pageError" in response_json:
+        if "code" in response_json["pageError"]:
+            match response_json["pageError"]["code"]:
+                case "WARNING_NOT_LOGGED_IN":
+                    raise NotLoggedIn("Not Logged in")
+                case "NOT_MEMBER_OF_LEAGUE":
+                    raise NotMemberOfLeague("Not Member of League")
+                case "UNEXPECTED_ERROR":
+                    raise FantraxException(f"{response_json['pageError']['title']}")
+                case _:
+                    raise FantraxException(f"{response_json}")
+
+    return response_json["responses"][0]["data"] if len(methods) == 1 else [r["data"] for r in response_json["responses"]]
+
+
+def get_init_info(league: "League") -> dict:
+    return request(
+        league,
+        [
+            Method("getFantasyLeagueInfo"),
+            Method("getRefObject", type="FantasyItemStatus"),
+            Method("getLiveScoringStats", newView=True),
+            Method("getTeamRosterInfo", view="GAMES_PER_POS"),
+            Method("getTeamRosterInfo", view="STATS"),
+        ],
+    )
+
+
+def get_pending_transactions(league: "League") -> dict:
+    return request(league, Method("getPendingTransactions"))
+
+
+def get_standings(league: "League", views: list[str] | str | None = None, **kwargs: Param.kwargs) -> dict:
+    if "view" in kwargs and views is None:
+        views = kwargs.pop("view")
+    if "view" in kwargs:
+        del kwargs["view"]
+    if not isinstance(views, list):
+        views = [views]
+    response = request(league, [Method("getStandings", view=v, **kwargs) for v in views])
+    responses = response if isinstance(response, list) else [response]
+    for res in responses:
+        if "fantasyTeamInfo" in res:
+            league._update_teams(res["fantasyTeamInfo"])
+    return response
+
+
+def get_trade_blocks(league: "League") -> dict:
+    return request(league, Method("getTradeBlocks"))["tradeBlocks"]
+
+
+def get_team_roster_position_counts(league: "League", team_id: str, scoring_period_number: int | None = None) -> dict:
+    response = request(league, Method("getTeamRosterInfo", teamId=team_id, scoringPeriod=scoring_period_number, view="GAMES_PER_POS"))
+    league._update_teams(response["fantasyTeams"])
+    return response
+
+
+def get_team_roster_info(league: "League", team_id: str, period_number: int | None = None) -> dict:
+    responses = request(
+        league,
+        [
+            Method("getTeamRosterInfo", teamId=team_id, period=period_number, view="STATS"),
+            Method("getTeamRosterInfo", teamId=team_id, period=period_number, view="SCHEDULE_FULL"),
+        ],
+    )
+    league._update_teams(responses[0]["fantasyTeams"])
+    return responses
+
+
+def get_transaction_history(league: "League", per_page_results: int = 100) -> dict:
+    return request(league, Method("getTransactionDetailsHistory", maxResultsPerPage=str(per_page_results)))
+
+
+def get_live_scoring_stats(league: "League", scoring_date: date | None = None) -> dict:
+    return request(league, Method("getLiveScoringStats", date=scoring_date, newView=True, period="1", playerViewType="1", sppId="-1", viewType="1"))

elo_system-1.0.0/elo_system/_vendor/fantraxapi/exceptions.py

@@ -0,0 +1,39 @@
+from datetime import date, datetime
+
+
+class FantraxException(Exception):
+    """Base class for all FantraxAPI exceptions."""
+
+    pass
+
+
+class DateNotInSeason(FantraxException):
+    """Exception thrown when trying to query with a date not in the Season"""
+
+    def __init__(self, error_date: str | date | datetime) -> None:
+        super().__init__(f"Date: {error_date if isinstance(error_date, str) else error_date.strftime('%Y-%m-%d')} not in the Season.")
+
+
+class NotLoggedIn(FantraxException):
+    """Exception thrown when accessing a private endpoint without being Logged In"""
+
+    pass
+
+
+class NotMemberOfLeague(FantraxException):
+    """Exception thrown when accessing an endpoint without being part of that League"""
+
+    pass
+
+
+class NotTeamInLeague(FantraxException):
+    """Exception thrown when trying to query for a Team not part of that League"""
+
+    pass
+
+
+class PeriodNotInSeason(FantraxException):
+    """Exception thrown when trying to query with a period not in the Season"""
+
+    def __init__(self, error_date: str | int) -> None:
+        super().__init__(f"Period: {error_date} not in the Season.")

elo_system-1.0.0/elo_system/_vendor/fantraxapi/objs/__init__.py

@@ -0,0 +1,36 @@
+from .game import Game
+from .league import League
+from .player import LivePlayer, Player
+from .position import Position, PositionCount
+from .roster import Roster, RosterRow
+from .scoring_period import Matchup, ScoringPeriod, ScoringPeriodResult
+from .standings import Record, Standings
+from .status import Status
+from .team import Team
+from .trade import Trade, TradeDraftPick, TradePlayer
+from .trade_block import TradeBlock
+from .transaction import Transaction, TransactionPlayer
+
+__all__ = [
+    "TradeDraftPick",
+    "Game",
+    "League",
+    "LivePlayer",
+    "Matchup",
+    "Player",
+    "Position",
+    "PositionCount",
+    "Record",
+    "Roster",
+    "RosterRow",
+    "ScoringPeriod",
+    "ScoringPeriodResult",
+    "Standings",
+    "Status",
+    "Team",
+    "Trade",
+    "TradeBlock",
+    "TradePlayer",
+    "Transaction",
+    "TransactionPlayer",
+]

elo_system-1.0.0/elo_system/_vendor/fantraxapi/objs/_parse.py

@@ -0,0 +1,85 @@
+"""Small parsing helpers shared across the data-model classes.
+
+These centralise the brittle string/number parsing that Fantrax responses
+require (comma thousands separators, bracketed date ranges, trailing period
+numbers) so the same idioms aren't repeated, and so malformed data raises a
+clear :class:`~fantraxapi.exceptions.FantraxException` instead of an opaque
+``AttributeError``/``IndexError``.
+"""
+
+import re
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+
+from ..exceptions import FantraxException
+
+# Characters that wrap a date range caption, e.g. "(Oct 12/24 - Oct 18/24)".
+_RANGE_WRAPPERS = "()[] "
+_PERIOD_SUFFIX = re.compile(r"(\d+)$")
+
+
+def parse_float(value: object, default: float = 0.0) -> float:
+    """Parse a float from a Fantrax cell value.
+
+    Handles ``None``, blank/``"-"`` placeholders and comma thousands
+    separators, falling back to ``default`` when the value can't be parsed.
+    """
+    if value is None:
+        return default
+    text = str(value).strip().replace(",", "")
+    if not text or text == "-":
+        return default
+    try:
+        return float(text)
+    except ValueError:
+        return default
+
+
+def parse_decimal(value: object, default: Decimal = Decimal("0")) -> Decimal:
+    """Parse a :class:`~decimal.Decimal` from a Fantrax cell value.
+
+    Like :func:`parse_float` but preserves exact decimal scores.
+    """
+    if value is None:
+        return default
+    text = str(value).strip().replace(",", "")
+    if not text or text == "-":
+        return default
+    try:
+        return Decimal(text)
+    except InvalidOperation:
+        return default
+
+
+def parse_date_range(caption: str, fmt: str) -> tuple[date, date]:
+    """Parse a ``"(<start> - <end>)"`` caption into ``(start, end)`` dates.
+
+    Args:
+        caption: Bracketed caption such as ``"(Oct 12/24 - Oct 18/24)"``.
+        fmt: ``datetime.strptime`` format for each side of the range.
+
+    Raises:
+        FantraxException: When the caption doesn't contain a parseable range.
+    """
+    parts = caption.strip(_RANGE_WRAPPERS).split(" - ")
+    if len(parts) != 2:
+        raise FantraxException(f"Could not parse date range from caption: {caption!r}")
+    try:
+        return (
+            datetime.strptime(parts[0], fmt).date(),
+            datetime.strptime(parts[1], fmt).date(),
+        )
+    except ValueError as e:
+        raise FantraxException(f"Could not parse date range from caption: {caption!r}: {e}")
+
+
+def period_number(caption: str) -> int:
+    """Extract the trailing period number from a caption.
+
+    Raises:
+        FantraxException: When the caption has no trailing number.
+    """
+    match = _PERIOD_SUFFIX.search(caption)
+    if match is None:
+        raise FantraxException(f"Could not find a period number in caption: {caption!r}")
+    return int(match.group(1))

elo_system-1.0.0/elo_system/_vendor/fantraxapi/objs/base.py

@@ -0,0 +1,13 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .league import League
+
+
+class FantraxBaseObject:
+    def __init__(self, league: "League", data: dict | list[dict]) -> None:
+        self.league: "League" = league
+        self._data: dict | list[dict] = data
+
+    def __repr__(self) -> str:
+        return self.__str__()

elo_system-1.0.0/elo_system/_vendor/fantraxapi/objs/game.py

@@ -0,0 +1,67 @@
+from datetime import date, datetime, time
+from typing import TYPE_CHECKING, Self
+
+from ..exceptions import DateNotInSeason
+from .base import FantraxBaseObject
+from .player import Player
+
+if TYPE_CHECKING:
+    from .league import League
+
+
+class Game(FantraxBaseObject):
+    """Represents a single Game.
+
+    Attributes:
+        league (League): The League instance this object belongs to.
+        id (str): Game ID.
+        player (Player): Player to view this game from.
+        date (date): The date this game is played.
+        opponent (str): NHL Short Name of the opponent.
+        time (time): Time of the game start if it hasn't been played yet.
+        home (bool): Is Player Home?
+        away (bool): Is Player Away?
+
+    """
+
+    def __init__(self, league: "League", player: Player, game_date: str, data: dict) -> None:
+        super().__init__(league, data)
+        self.id: str = self._data["eventId"]
+        self.player: Player = player
+        start = datetime.strptime(f"{game_date} {self.league.start_date.year}", "%a %m/%d %Y").date()
+        end = datetime.strptime(f"{game_date} {self.league.end_date.year}", "%a %m/%d %Y").date()
+        league_start = self.league.start_date.date()
+        league_end = self.league.end_date.date()
+        if league_end >= start >= league_start:
+            self.date: date = start
+        elif league_end >= end >= league_start:
+            self.date: date = end
+        else:
+            raise DateNotInSeason(game_date)
+
+        self.time: time | None = None
+        parts = data["content"].removesuffix(" F").split("\u003cbr/\u003e")
+        if ":" in parts[1]:
+            self.opponent: str = parts[0]
+            if self.opponent.startswith("@"):
+                self.opponent = self.opponent[1:]
+                home = self.player.team_short_name
+            else:
+                home = self.opponent
+
+            self.time = datetime.strptime(parts[1].split(" ")[1], "%I:%M%p").time()
+        else:
+            home = "".join(i for i in parts[0] if not i.isdigit() and i not in [" ", "@"])
+            away = "".join(i for i in parts[1] if not i.isdigit() and i not in [" ", "@"])
+            self.opponent = away if home == self.player.team_short_name else home
+        self.home: bool = home == self.player.team_short_name
+        self.away: bool = home != self.player.team_short_name
+
+    def __eq__(self, other: Self) -> bool:
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(("Game", self.id))
+
+    def __str__(self) -> str:
+        return f"[{self.id}:{f'{self.opponent} @{self.player.team_short_name}' if self.home else f'{self.player.team_short_name} @{self.opponent}'}{f' {self.time}' if self.time else ''}]"