fplkit 1.4.2__tar.gz → 2.0.0__tar.gz

{fplkit-1.4.2 → fplkit-2.0.0}/.agents/TOOLS.md

@@ -27,8 +27,8 @@ Errors use `emit_json_error()` with `{"command", "error"}` shape.
 | `init` | Set up fpl-cli with your FPL IDs and optional features | No | General | No | direct-api |
 | `status` | Show FPL gameweek status and upcoming deadlines | Yes | General | No | direct-api |
 | `fixtures` | Show fixtures for a gameweek | Yes | General | No | direct-api |
-| `player` | Look up a player's stats, xG, ownership and fixture run. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW); panel shows `xPts` (ep_next). `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
-| `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Sortable by `ep_next`/`ep_this` (FPL predicted points); both in JSON output | Yes | General | No | direct-api |
+| `player` | Look up a player's stats, xG, ownership and fixture run. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW), emitting `null` when FPL has no projection; panel shows `xPts` (ep_next) when available, omits the segment when FPL has no projection. `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)` | Yes | General | No | direct-api |
+| `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Sortable by `ep_next`/`ep_this` (FPL predicted points); both in JSON output (emit `null` when FPL has no projection; table renders `—`). Players with no projection sort to the bottom in either direction | Yes | General | No | direct-api |
 | `history` | Show historical player performance across seasons | Yes | General | No | direct-api |
 | `league` | Show live league standings for Classic and Draft leagues | No | General | No | direct-api |
 | `fdr` | Analyse fixture difficulty - easy runs, blanks, doubles | Yes | General | No | via-agent |

{fplkit-1.4.2 → fplkit-2.0.0}/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [1.4.2] - 2026-05-24
+
+### Bug Fixes
+
+- feat(scout): bind player clubs to current-season reference (#40)
+- feat(sell-prices refresh): Add retry logic to /api/me/ polling with hydration race handling (#39)
+
+### Scout
+
+- enforce player_reference as a strict allowlist (#41)
+
 ## [1.4.1] - 2026-05-17
 
 ### Refactoring
@@ -114,3 +125,4 @@ All notable changes to this project will be documented in this file.
 ### Features
 
 - CI pipeline and PyPI publish for v1.0.0 (#1)
+

{fplkit-1.4.2 → fplkit-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fplkit
-Version: 1.4.2
+Version: 2.0.0
 Summary: CLI tool for Fantasy Premier League analysis - classic and draft formats
 Project-URL: Homepage, https://github.com/rossgroomio/fpl-cli
 Project-URL: Repository, https://github.com/rossgroomio/fpl-cli

{fplkit-1.4.2 → fplkit-2.0.0}/docs/command-reference.md

@@ -379,7 +379,7 @@ The FPL API provides gameweek point predictions for every player:
 | **ep_next** | FPL's predicted points for the next gameweek. Shown as `xPts` on the Points/PPG panel line. Available as a `--sort` field in `fpl stats`. |
 | **ep_this** | FPL's predicted points for the current gameweek (freezes after GW deadline, enabling predicted-vs-actual comparison with `event_points`). JSON only - not shown in the panel. |
 
-Both fields default to `0.0` for unavailable/injured players. In JSON output, they appear under `info.ep_next` and `info.ep_this` for `fpl player`, and as top-level record fields in `fpl stats --format json`.
+Both fields are `None` on the `Player` model when FPL provides no projection (e.g. unavailable/injured players, end of season). The Rich panel for `fpl player` omits the `xPts` segment of the Points line in that case, and the `fpl stats` table renders the cell as `—`. JSON output emits `null` when FPL provides no projection, so consumers can distinguish missing data from a genuine `0.0` projection — `info.ep_next`/`info.ep_this` for `fpl player`, and the top-level `ep_next`/`ep_this` record fields in `fpl stats --format json`.
 
 #### Player Detail Flags
 

{fplkit-1.4.2 → fplkit-2.0.0}/fpl_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.2'
-__version_tuple__ = version_tuple = (1, 4, 2)
+__version__ = version = '2.0.0'
+__version_tuple__ = version_tuple = (2, 0, 0)
 
 __commit_id__ = commit_id = None

{fplkit-1.4.2 → fplkit-2.0.0}/fpl_cli/cli/_helpers.py

@@ -268,5 +268,9 @@ def _format_sort_value(field: str, value) -> str:
     if fmt == "pct":
         return f"{value:.1f}%"
     if field in _PLAYERS_FLOAT_FIELDS:
-        return f"{value:.1f}"
+        # Missing-data UX: render em dash. A table column can't be omitted
+        # per-row, so we substitute a visible placeholder. The Rich panel
+        # in `fpl player` drops the whole segment instead — different
+        # surface, different right answer.
+        return f"{value:.1f}" if value is not None else "—"
     return str(value)

{fplkit-1.4.2 → fplkit-2.0.0}/fpl_cli/cli/player.py

@@ -288,8 +288,8 @@ def player_command(
                                 "form": float(p.form),
                                 "total_points": p.total_points,
                                 "points_per_game": float(p.points_per_game),
-                                "ep_next": float(p.ep_next),
-                                "ep_this": float(p.ep_this),
+                                "ep_next": p.ep_next,
+                                "ep_this": p.ep_this,
                                 "goals_scored": p.goals_scored,
                                 "assists": p.assists,
                                 "expected_assists": float(p.expected_assists),
@@ -423,11 +423,19 @@ def player_command(
 
                     # Build panel lines conditionally
                     is_gk = p.position_name == "GK"
+                    # Missing-data UX: drop the xPts segment entirely. The panel is
+                    # a single-row free-form layout, so removing the label reads cleaner
+                    # than rendering "xPts: —". The stats table takes the opposite
+                    # approach (em dash) because per-row column omission isn't an option.
                     lines = [
                         f"[bold]{p.web_name}[/bold] ({p.full_name})",
                         f"Team: {team_name} | Position: {p.position_name}",
                         f"Price: £{p.price:.1f}m | Form: {p.form:.1f}",
-                        f"Points: {p.total_points} | PPG: {p.points_per_game:.1f} | xPts: {p.ep_next:.1f}",
+                        (
+                            f"Points: {p.total_points} | PPG: {p.points_per_game:.1f} | xPts: {p.ep_next:.1f}"
+                            if p.ep_next is not None
+                            else f"Points: {p.total_points} | PPG: {p.points_per_game:.1f}"
+                        ),
                     ]
                     rv, rc = rolling_scores.get(p.id, (None, None))
                     if rv is not None:

{fplkit-1.4.2 → fplkit-2.0.0}/fpl_cli/cli/stats.py

@@ -280,6 +280,8 @@ def stats_command(
                 effective_sort = "total_points"
 
             # Sort
+            # Null-scored players sort to bottom regardless of direction
+            bottom = float("-inf") if not reverse else float("inf")
             if effective_sort in _VALUE_SORT_FIELDS:
                 if effective_sort == "rolling_pts_per_m":
                     rolling_score_map: dict[int, float | None] = {
@@ -290,8 +292,6 @@ def stats_command(
                     score_map = quality_map
                 else:
                     score_map = value_map
-                # Null-scored players sort to bottom regardless of direction
-                bottom = float("-inf") if not reverse else float("inf")
 
                 def _value_key(p: Player) -> float:
                     v = score_map.get(p.id)
@@ -300,7 +300,12 @@ def stats_command(
                 filtered.sort(key=_value_key, reverse=not reverse)
             else:
                 attr = _SORT_FIELD_ALIASES.get(effective_sort, effective_sort)
-                filtered.sort(key=lambda p: getattr(p, attr), reverse=not reverse)
+
+                def _attr_key(p: Player) -> float:
+                    v = getattr(p, attr)
+                    return v if v is not None else bottom
+
+                filtered.sort(key=_attr_key, reverse=not reverse)
 
             # Limit
             filtered = filtered[:limit]
@@ -366,8 +371,8 @@ def stats_command(
                             "defensive_contribution_per_90": float(p.defensive_contribution_per_90),
                             "form_per_m": float(p.value_form),
                             "pts_per_m": float(p.value_season),
-                            "ep_next": float(p.ep_next),
-                            "ep_this": float(p.ep_this),
+                            "ep_next": p.ep_next,
+                            "ep_this": p.ep_this,
                             **(
                                 {
                                     "quality_score": quality_map.get(p.id),

{fplkit-1.4.2 → fplkit-2.0.0}/fpl_cli/models/player.py

@@ -90,8 +90,8 @@ class Player(BaseModel):
     expected_goals_conceded: float = Field(default=0.0, alias="expected_goals_conceded")
 
     # FPL predicted points
-    ep_next: float = 0.0
-    ep_this: float = 0.0
+    ep_next: float | None = None
+    ep_this: float | None = None
 
     # Defensive
     defensive_contribution: int = 0

{fplkit-1.4.2 → fplkit-2.0.0}/tests/test_cli_format_suppression.py

@@ -248,8 +248,8 @@ class TestPlayerFormatSuppression:
         player.direct_freekicks_order = None
         player.defensive_contribution_per_90 = 0.0
         player.penalties_saved = 0
-        player.ep_next = 0.0
-        player.ep_this = 0.0
+        player.ep_next = None
+        player.ep_this = None
         return player
 
     def _mock_team(self):

{fplkit-1.4.2 → fplkit-2.0.0}/tests/test_cli_player.py

@@ -729,6 +729,50 @@ class TestPlayerQualityValueScores:
         assert "xPts: 8.5" in result.output
         assert "ep_this" not in result.output
 
+    def test_rich_panel_omits_ep_next_when_none(self):
+        client, fixture_agent, ratings_svc = _make_mocks()
+        client.get_players = AsyncMock(return_value=[
+            make_player(id=308, web_name="Salah", first_name="Mohamed",
+                        second_name="Salah", team_id=1,
+                        position=PlayerPosition.MIDFIELDER,
+                        ep_next=None),
+        ])
+        result = _run([], client, fixture_agent, ratings_svc)
+        assert result.exit_code == 0, result.output
+        assert "xPts" not in result.output
+        # Rest of the Points line must still render — confirms only the xPts
+        # segment was dropped, not the entire row.
+        assert "Points:" in result.output
+        assert "PPG:" in result.output
+
+    def test_rich_panel_shows_ep_next_when_zero(self):
+        # Guards against a future `if p.ep_next:` regression that would
+        # swallow genuine 0.0 projections (distinct from None).
+        client, fixture_agent, ratings_svc = _make_mocks()
+        client.get_players = AsyncMock(return_value=[
+            make_player(id=308, web_name="Salah", first_name="Mohamed",
+                        second_name="Salah", team_id=1,
+                        position=PlayerPosition.MIDFIELDER,
+                        ep_next=0.0),
+        ])
+        result = _run([], client, fixture_agent, ratings_svc)
+        assert result.exit_code == 0, result.output
+        assert "xPts: 0.0" in result.output
+
+    def test_json_ep_next_none_serialises_as_null(self):
+        client, fixture_agent, ratings_svc = _make_mocks()
+        client.get_players = AsyncMock(return_value=[
+            make_player(id=308, web_name="Salah", first_name="Mohamed",
+                        second_name="Salah", team_id=1,
+                        position=PlayerPosition.MIDFIELDER,
+                        ep_next=None, ep_this=None),
+        ])
+        result = _run_json([], client, fixture_agent, ratings_svc)
+        assert result.exit_code == 0, result.output
+        info = json.loads(result.output)["data"][0]["info"]
+        assert info["ep_next"] is None
+        assert info["ep_this"] is None
+
     def test_gk_uses_without_xgi_weights(self):
         """GK quality_score should differ from MID due to without_xgi path."""
         client, fixture_agent, ratings_svc = _make_mocks()

{fplkit-1.4.2 → fplkit-2.0.0}/tests/test_cli_stats.py

@@ -235,6 +235,47 @@ class TestPlayersSort:
         assert result.exit_code == 0, result.output
         assert result.output.index("Fit") < result.output.index("Injured")
 
+    def test_sort_ep_next_none_sorts_to_bottom(self):
+        players = [
+            make_player(id=1, web_name="HasValue", team_id=1, ep_next=5.0),
+            make_player(id=2, web_name="NullEp", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next"], client=client)
+        assert result.exit_code == 0, result.output
+        assert result.output.index("HasValue") < result.output.index("NullEp")
+
+    def test_sort_ep_next_all_none_does_not_crash(self):
+        players = [
+            make_player(id=1, web_name="Alpha", team_id=1, ep_next=None),
+            make_player(id=2, web_name="Beta", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next"], client=client)
+        assert result.exit_code == 0, result.output
+
+    def test_sort_ep_next_none_sorts_to_bottom_in_ascending(self):
+        # --reverse activates the float("inf") sentinel branch of the sort
+        players = [
+            make_player(id=1, web_name="HasValue", team_id=1, ep_next=5.0),
+            make_player(id=2, web_name="NullEp", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next", "--reverse"], client=client)
+        assert result.exit_code == 0, result.output
+        assert result.output.index("HasValue") < result.output.index("NullEp")
+
+    def test_sort_ep_next_none_renders_em_dash_in_table(self):
+        # Exercises the _format_sort_value None -> "—" branch
+        players = [
+            make_player(id=1, web_name="HasValue", team_id=1, ep_next=5.0),
+            make_player(id=2, web_name="NullEp", team_id=1, ep_next=None),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--sort", "ep_next"], client=client)
+        assert result.exit_code == 0, result.output
+        assert "—" in result.output
+
 
 class TestPlayersErrors:
     def test_invalid_team_shows_valid_options(self):
@@ -294,6 +335,21 @@ class TestPlayersJsonFormat:
         assert "Salah" in result.output
         assert result.output.strip()[0] != "["
 
+    def test_json_ep_next_none_serialises_as_null(self):
+        players = [
+            make_player(
+                id=1, web_name="NullEp", team_id=1,
+                position=PlayerPosition.MIDFIELDER,
+                ep_next=None, ep_this=None,
+            ),
+        ]
+        client = _make_client(players, _sample_teams())
+        result = _run(["--format", "json"], client=client)
+        assert result.exit_code == 0, result.output
+        record = json.loads(result.output)["data"][0]
+        assert record["ep_next"] is None
+        assert record["ep_this"] is None
+
 
 class TestStatsDraftOwnership:
     """Tests for auto-enabled draft ownership column based on format."""