max-pf 1.0.0__py3-none-any.whl

max_pf/__init__.py

@@ -0,0 +1,41 @@
+"""max_pf -- "max points for" methodology for 9-cat fantasy basketball.
+
+Top-level entry point: ``max_pf.run(login, ...)`` takes a platform login dict and
+returns the season report. See :mod:`max_pf.app`.
+"""
+from __future__ import annotations
+
+from .app import build_platform, load_login, parse_weeks, run
+from .categories import CATEGORIES, CATEGORY_KEYS, Category
+from .estimators import estimate_attempts
+from .metric import CategoryResult, DeltaResult, catwins, compute_delta
+from .models import PlayerDay, PlayerLine, RosterDay, aggregate
+from .report import TeamSeason, render_csv, render_markdown, render_table
+
+__version__ = "0.0.1"
+
+__all__ = [
+    # entry point
+    "run",
+    "build_platform",
+    "load_login",
+    "parse_weeks",
+    "TeamSeason",
+    "render_table",
+    "render_csv",
+    "render_markdown",
+    # primitives
+    "CATEGORIES",
+    "CATEGORY_KEYS",
+    "Category",
+    "estimate_attempts",
+    "CategoryResult",
+    "DeltaResult",
+    "catwins",
+    "compute_delta",
+    "PlayerLine",
+    "PlayerDay",
+    "RosterDay",
+    "aggregate",
+    "__version__",
+]

max_pf/__main__.py

@@ -0,0 +1,57 @@
+"""Command-line season report: ``python -m max_pf <login-file>``.
+
+The login file is a JSON or YAML mapping naming the platform and its details::
+
+    {"platform": "fantrax", "league_id": "wserh14rmbbpqtcg"}
+
+Computes the max-points-for season summary for every team, prints it, and writes
+``<out>.csv`` and ``<out>.md``.
+
+    python -m max_pf league.json
+    python -m max_pf league.yaml --weeks 1-6 --out reports/half1
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .app import load_login, run
+from .report import render_csv, render_markdown, render_table
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="max_pf", description="9-cat max-points-for season report")
+    parser.add_argument("login", help="path to a JSON or YAML login file (platform + details)")
+    parser.add_argument("--weeks", default=None,
+                        help='one week or a selection, e.g. "5", "1-6", "1,2,5"; default: season to date')
+    parser.add_argument("--out", default="season_report", help="output path prefix (writes .csv and .md)")
+    parser.add_argument("--methodology", choices=["expected", "hindsight"], default="expected",
+                        help="expected = season-to-date box-score projections; "
+                             "hindsight = realized box scores (both use basketball-reference)")
+    parser.add_argument("--objective", choices=["catwins", "zscore", "raw"], default="catwins",
+                        help="catwins = Objective A (opponent-aware category wins); "
+                             "zscore = Objective B (max total z-value lineup); "
+                             "raw = Objective C (max raw output lineup)")
+    parser.add_argument("--no-boxscores", action="store_true",
+                        help="use the platform's built-in estimator instead of box scores (expected only)")
+    args = parser.parse_args(argv)
+
+    login = load_login(args.login)
+    rows = run(
+        login, weeks=args.weeks, methodology=args.methodology,
+        objective=args.objective, boxscores=not args.no_boxscores,
+    )
+
+    print(render_table(rows))
+
+    out = Path(args.out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    csv_path, md_path = out.with_suffix(".csv"), out.with_suffix(".md")
+    csv_path.write_text(render_csv(rows))
+    md_path.write_text("# Max Points For — Season Report\n\n" + render_markdown(rows) + "\n")
+    print(f"\nwrote {csv_path} and {md_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

max_pf/_vendor/NOTICE.md

@@ -0,0 +1,18 @@
+# Vendored dependencies
+
+Third-party code bundled into `max_pf` to keep PyPI installs free of direct
+VCS/URL references. Each package keeps its original license alongside its source.
+
+## fantraxapi
+
+- **Source:** https://github.com/riders994/FantraxAPI (the `@stable` fork)
+- **Upstream:** https://github.com/meisnate12/FantraxAPI
+- **Pinned commit:** `4f98fa66b2c28505de3f0fa4b274d14feccc7577` (tag `stable`)
+- **Version:** 1.0.1 (fork)
+- **License:** MIT — see `fantraxapi/LICENSE`
+- **Runtime deps:** `requests` (declared in `max_pf`'s dependencies)
+
+Imported as `max_pf._vendor.fantraxapi`. To refresh: re-copy the package source
+from the fork at the desired commit, drop `__pycache__`, keep `LICENSE`, and
+update the commit hash above. The source is unmodified (all imports are already
+package-relative, so no patching is required).

max_pf/_vendor/__init__.py

@@ -0,0 +1,7 @@
+"""Vendored third-party packages.
+
+Bundled here (rather than declared as dependencies) so ``max_pf`` installs from
+PyPI without a direct VCS/URL reference, which PyPI rejects. See NOTICE for
+sources, versions, and licenses. Import vendored code via
+``max_pf._vendor.<pkg>`` — never the top-level name.
+"""

max_pf/_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.

max_pf/_vendor/fantraxapi/__init__.py

@@ -0,0 +1,26 @@
+import importlib.metadata
+
+from .exceptions import FantraxException, NotLoggedIn, NotMemberOfLeague, NotTeamInLeague
+from .objs import League
+from .objs import League as FantraxAPI
+
+try:
+    __version__ = importlib.metadata.version("fantraxapi")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = ""
+__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",
+]

max_pf/_vendor/fantraxapi/api.py

@@ -0,0 +1,135 @@
+from datetime import date
+from json.decoder import JSONDecodeError
+from typing import TYPE_CHECKING, cast
+
+from requests import Session
+
+from .exceptions import FantraxException, NotLoggedIn, NotMemberOfLeague
+
+if TYPE_CHECKING:
+    from .objs import League
+
+
+default_session: Session = Session()
+
+debug: bool = False
+
+
+class Method:
+    def __init__(self, name: str, **kwargs: object) -> None:
+        self.name: str = name
+        self.kwargs: dict = kwargs
+        self.response: dict | None = None
+
+    def msg_block(self, league_id: str) -> dict[str, 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:
+    # _request returns a list only for multi-Method calls; the few callers that pass a
+    # list index the result positionally, so the single-Method dict shape is the contract.
+    return _request(league.league_id, methods, session=league.session)  # type: ignore[return-value]
+
+
+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: object) -> dict:
+    if "view" in kwargs and views is None:
+        views = cast("list[str] | str", kwargs.pop("view"))
+    if "view" in kwargs:
+        del kwargs["view"]
+    view_list: list[str | None] = [v for v in views] if isinstance(views, list) else [views]
+    response = request(league, [Method("getStandings", view=v, **kwargs) for v in view_list])
+    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", max_results_per_page: int = 100, page_number: int = 1) -> dict:
+    return request(league, Method("getTransactionDetailsHistory", maxResultsPerPage=str(max_results_per_page), pageNumber=str(page_number)))
+
+
+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"))

max_pf/_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.")

max_pf/_vendor/fantraxapi/objs/__init__.py

@@ -0,0 +1,40 @@
+from .game import Game
+from .league import League
+from .player import LivePlayer, Player, ScoringCategory
+from .position import Position, PositionCount
+from .roster import CapHitPenalty, Roster, RosterDraftPick, RosterRow, SalaryInfo
+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__ = [
+    "CapHitPenalty",
+    "TradeDraftPick",
+    "Game",
+    "League",
+    "LivePlayer",
+    "Matchup",
+    "Player",
+    "Position",
+    "PositionCount",
+    "Record",
+    "Roster",
+    "RosterDraftPick",
+    "RosterRow",
+    "SalaryInfo",
+    "ScoringCategory",
+    "ScoringPeriod",
+    "ScoringPeriodResult",
+    "Standings",
+    "Status",
+    "Team",
+    "Trade",
+    "TradeBlock",
+    "TradePlayer",
+    "Transaction",
+    "TransactionPlayer",
+]

max_pf/_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))

max_pf/_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__()

max_pf/_vendor/fantraxapi/objs/game.py

@@ -0,0 +1,93 @@
+from datetime import date, datetime, time
+from typing import TYPE_CHECKING
+
+from ..exceptions import DateNotInSeason
+from .base import FantraxBaseObject
+from .player import Player
+
+if TYPE_CHECKING:
+    from .league import League
+
+_WEEKDAYS = {"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"}
+
+
+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): Short Name of the opponent.
+        time (time): Start time of the (first) game if it hasn't been played yet.
+        times (list[time]): All start times on this date; more than one for a doubleheader.
+        home (bool): Is Player Home?
+        away (bool): Is Player Away?
+
+    """
+
+    _data: dict
+
+    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
+        league_start = self.league.start_date.date()
+        league_end = self.league.end_date.date()
+        # The game date carries no year; seasons span a year boundary, so try the start
+        # year then the end year. Parsing is wrapped because a date like Feb 29 raises
+        # ValueError against a non-leap candidate year before the other year is tried.
+        self.date: date | None = None
+        for year in (self.league.start_date.year, self.league.end_date.year):
+            try:
+                candidate = datetime.strptime(f"{game_date} {year}", "%a %m/%d %Y").date()
+            except ValueError:
+                continue
+            if league_start <= candidate <= league_end:
+                self.date = candidate
+                break
+        if self.date is None:
+            raise DateNotInSeason(game_date)
+
+        self.time: time | None = None
+        self.times: list[time] = []
+        parts = data["content"].removesuffix(" F").split("\u003cbr/\u003e")
+        if ":" in parts[1]:
+            # Single game: parts == ["<opp>", "<Weekday> <Time>"]. Doubleheader (baseball):
+            # parts == ["<opp> <Weekday>", "<Time1>", "<Time2>"] -- the weekday moves into
+            # parts[0] and each later part is one start time.
+            opponent = parts[0].strip()
+            tokens = opponent.split(" ")
+            if len(tokens) > 1 and tokens[-1] in _WEEKDAYS:
+                opponent = " ".join(tokens[:-1])
+            self.opponent: str = opponent
+            if self.opponent.startswith("@"):
+                # "@OPP": the player's team is visiting, so the opponent is the home team.
+                self.opponent = self.opponent[1:]
+                home = self.opponent
+            else:
+                # "OPP": the player's team is hosting.
+                home = self.player.team_short_name
+
+            # The time is the last whitespace token of each part that carries one.
+            self.times = [datetime.strptime(part.split(" ")[-1], "%I:%M%p").time() for part in parts[1:] if ":" in part]
+            self.time = self.times[0] if self.times else None
+        else:
+            # Played game "<away> <score><br/>@<home> <score>": the "@" side (parts[1]) is home.
+            away_team = "".join(i for i in parts[0] if not i.isdigit() and i not in [" ", "@"])
+            home = "".join(i for i in parts[1] if not i.isdigit() and i not in [" ", "@"])
+            self.opponent = away_team 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: object) -> bool:
+        if not isinstance(other, Game):
+            return NotImplemented
+        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 ''}]"