chore: unify linting with pre-commit in CI

Author: camodotgg

.github/workflows/ci.yml

@@ -7,6 +7,19 @@ on:
     branches: [main]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -27,14 +40,5 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras
 
-      - name: Run ruff check
-        run: uv run ruff check src/
-
-      - name: Run ruff format check
-        run: uv run ruff format --check src/
-
-      - name: Run mypy
-        run: uv run mypy src/
-
       - name: Run tests
         run: uv run pytest -v

.pre-commit-config.yaml

@@ -14,3 +14,13 @@ repos:
       - id: check-yaml
       - id: check-added-large-files
       - id: check-toml
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        pass_filenames: false
+        additional_dependencies:
+          - pydantic>=2.0.0
+          - httpx>=0.27.0
+          - pytest>=8.0.0

examples/leaderboards.py

@@ -25,9 +25,9 @@
 phase_lb = mcsrranked.leaderboards.phase()
 if phase_lb.phase.number:
     print(f"Phase {phase_lb.phase.number}")
-for player in phase_lb.users[:5]:
-    points = player.season_result.phase_point
-    print(f"{player.nickname}: {points} points")
+for phase_player in phase_lb.users[:5]:
+    points = phase_player.season_result.phase_point
+    print(f"{phase_player.nickname}: {points} points")
 print()
 
 # Record leaderboard (best times)

examples/matches.py

@@ -54,8 +54,8 @@ def format_time(ms: int) -> str:
 
 print("Elo Changes:")
 for change in match.changes:
-    player = next((p for p in match.players if p.uuid == change.uuid), None)
-    name = player.nickname if player else change.uuid
+    found_player = next((p for p in match.players if p.uuid == change.uuid), None)
+    name = found_player.nickname if found_player else change.uuid
     change_str = (
         f"+{change.change}"
         if change.change and change.change > 0
@@ -67,6 +67,6 @@ def format_time(ms: int) -> str:
 if match.timelines:
     print("Timeline:")
     for event in match.timelines[:10]:
-        player = next((p for p in match.players if p.uuid == event.uuid), None)
-        name = player.nickname if player else event.uuid[:8]
+        found_player = next((p for p in match.players if p.uuid == event.uuid), None)
+        name = found_player.nickname if found_player else event.uuid[:8]
         print(f"  {format_time(event.time)} - {name}: {event.type}")

examples/versus.py

@@ -30,8 +30,8 @@ def format_time(ms: int) -> str:
 total = ranked.get("total", 0)
 for uuid, wins in ranked.items():
     if uuid != "total":
-        player = next((p for p in stats.players if p.uuid == uuid), None)
-        name = player.nickname if player else uuid[:8]
+        found_player = next((p for p in stats.players if p.uuid == uuid), None)
+        name = found_player.nickname if found_player else uuid[:8]
         print(f"  {name}: {wins} wins")
 print(f"  Total matches: {total}")
 print()
@@ -42,17 +42,17 @@ def format_time(ms: int) -> str:
 total = casual.get("total", 0)
 for uuid, wins in casual.items():
     if uuid != "total":
-        player = next((p for p in stats.players if p.uuid == uuid), None)
-        name = player.nickname if player else uuid[:8]
+        found_player = next((p for p in stats.players if p.uuid == uuid), None)
+        name = found_player.nickname if found_player else uuid[:8]
         print(f"  {name}: {wins} wins")
 print(f"  Total matches: {total}")
 print()
 
 # Display elo changes
 print("Total Elo Changes:")
 for uuid, change in stats.changes.items():
-    player = next((p for p in stats.players if p.uuid == uuid), None)
-    name = player.nickname if player else uuid[:8]
+    found_player = next((p for p in stats.players if p.uuid == uuid), None)
+    name = found_player.nickname if found_player else uuid[:8]
     sign = "+" if change > 0 else ""
     print(f"  {name}: {sign}{change}")
 print()

pyproject.toml

@@ -77,6 +77,7 @@ quote-style = "double"
 indent-style = "space"
 
 [tool.mypy]
+files = ["src", "tests", "examples"]
 python_version = "3.11"
 strict = true
 warn_return_any = true

src/mcsrranked/types/user.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Any
+
 from pydantic import BaseModel, Field, model_validator
 
 from mcsrranked.types.shared import Achievement
@@ -48,7 +50,7 @@ class MatchTypeStats(BaseModel):
     model_config = {"populate_by_name": True}
 
 
-def _pivot_stats(data: dict) -> dict:
+def _pivot_stats(data: dict[str, Any]) -> dict[str, Any]:
     """Transform API format {stat: {mode: val}} to {mode: {stat: val}}.
 
     The API returns statistics grouped by stat type first (e.g., wins.ranked),
@@ -65,8 +67,8 @@ def _pivot_stats(data: dict) -> dict:
             return data
 
     # Pivot from {wins: {ranked: X, casual: Y}} to {ranked: {wins: X}, casual: {wins: Y}}
-    ranked: dict = {}
-    casual: dict = {}
+    ranked: dict[str, Any] = {}
+    casual: dict[str, Any] = {}
 
     field_mapping = {
         # API key -> model field name
@@ -107,7 +109,7 @@ class SeasonStats(BaseModel):
 
     @model_validator(mode="before")
     @classmethod
-    def pivot_stats(cls, data: dict) -> dict:
+    def pivot_stats(cls, data: dict[str, Any]) -> dict[str, Any]:
         """Transform API stat-first format to mode-first format."""
         return _pivot_stats(data)
 
@@ -126,7 +128,7 @@ class TotalStats(BaseModel):
 
     @model_validator(mode="before")
     @classmethod
-    def pivot_stats(cls, data: dict) -> dict:
+    def pivot_stats(cls, data: dict[str, Any]) -> dict[str, Any]:
         """Transform API stat-first format to mode-first format."""
         return _pivot_stats(data)
 

tests/conftest.py

@@ -1,7 +1,9 @@
 """Pytest configuration and fixtures."""
 
 import json
+from collections.abc import Generator
 from pathlib import Path
+from typing import Any
 
 import pytest
 import respx
@@ -11,10 +13,11 @@
 FIXTURES_DIR = Path(__file__).parent / "fixtures"
 
 
-def load_fixture(name: str) -> dict | list:
+def load_fixture(name: str) -> dict[str, Any] | list[Any]:
     """Load a JSON fixture file."""
     with open(FIXTURES_DIR / name) as f:
-        return json.load(f)
+        data: dict[str, Any] | list[Any] = json.load(f)
+        return data
 
 
 @pytest.fixture
@@ -24,79 +27,103 @@ def client() -> MCSRRanked:
 
 
 @pytest.fixture
-def mock_api() -> respx.MockRouter:
+def mock_api() -> Generator[respx.MockRouter, None, None]:
     """Create a mock API router."""
     with respx.mock(base_url="https://api.mcsrranked.com") as respx_mock:
         yield respx_mock
 
 
 @pytest.fixture
-def user_fixture() -> dict:
+def user_fixture() -> dict[str, Any]:
     """Load user.json fixture (Feinberg's profile)."""
-    return load_fixture("user.json")
+    result = load_fixture("user.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def user_matches_fixture() -> list:
+def user_matches_fixture() -> list[Any]:
     """Load user_matches.json fixture (Feinberg's recent matches)."""
-    return load_fixture("user_matches.json")
+    result = load_fixture("user_matches.json")
+    assert isinstance(result, list)
+    return result
 
 
 @pytest.fixture
-def user_seasons_fixture() -> dict:
+def user_seasons_fixture() -> dict[str, Any]:
     """Load user_seasons.json fixture (Feinberg's season history)."""
-    return load_fixture("user_seasons.json")
+    result = load_fixture("user_seasons.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def versus_fixture() -> dict:
+def versus_fixture() -> dict[str, Any]:
     """Load versus.json fixture (Feinberg vs Couriway stats)."""
-    return load_fixture("versus.json")
+    result = load_fixture("versus.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def versus_matches_fixture() -> list:
+def versus_matches_fixture() -> list[Any]:
     """Load versus_matches.json fixture (Feinberg vs Couriway matches)."""
-    return load_fixture("versus_matches.json")
+    result = load_fixture("versus_matches.json")
+    assert isinstance(result, list)
+    return result
 
 
 @pytest.fixture
-def matches_fixture() -> list:
+def matches_fixture() -> list[Any]:
     """Load matches.json fixture (recent ranked matches)."""
-    return load_fixture("matches.json")
+    result = load_fixture("matches.json")
+    assert isinstance(result, list)
+    return result
 
 
 @pytest.fixture
-def match_detail_fixture() -> dict:
+def match_detail_fixture() -> dict[str, Any]:
     """Load match_detail.json fixture (single match details)."""
-    return load_fixture("match_detail.json")
+    result = load_fixture("match_detail.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def leaderboard_fixture() -> dict:
+def leaderboard_fixture() -> dict[str, Any]:
     """Load leaderboard.json fixture (elo leaderboard)."""
-    return load_fixture("leaderboard.json")
+    result = load_fixture("leaderboard.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def phase_leaderboard_fixture() -> dict:
+def phase_leaderboard_fixture() -> dict[str, Any]:
     """Load phase_leaderboard.json fixture."""
-    return load_fixture("phase_leaderboard.json")
+    result = load_fixture("phase_leaderboard.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def record_leaderboard_fixture() -> dict:
+def record_leaderboard_fixture() -> list[Any]:
     """Load record_leaderboard.json fixture."""
-    return load_fixture("record_leaderboard.json")
+    result = load_fixture("record_leaderboard.json")
+    assert isinstance(result, list)
+    return result
 
 
 @pytest.fixture
-def live_fixture() -> dict:
+def live_fixture() -> dict[str, Any]:
     """Load live.json fixture (live matches)."""
-    return load_fixture("live.json")
+    result = load_fixture("live.json")
+    assert isinstance(result, dict)
+    return result
 
 
 @pytest.fixture
-def weekly_race_fixture() -> dict:
+def weekly_race_fixture() -> dict[str, Any]:
     """Load weekly_race.json fixture."""
-    return load_fixture("weekly_race.json")
+    result = load_fixture("weekly_race.json")
+    assert isinstance(result, dict)
+    return result

tests/test_client.py

@@ -1,3 +1,4 @@
+# mypy: disable-error-code="no-untyped-def,misc"
 """Tests for the client module."""
 
 import httpx

tests/test_field_coverage.py

@@ -1,3 +1,6 @@
+# mypy: disable-error-code="no-untyped-def"
+"""Field coverage tests with isinstance() checks."""
+
 from mcsrranked.types.leaderboard import (
     EloLeaderboard,
     LeaderboardSeasonResult,
@@ -131,6 +134,7 @@ def test_season_result_all_fields(self, user_fixture):
     def test_last_season_state_all_fields(self, user_fixture):
         """Verify all LastSeasonState fields."""
         user = User.model_validate(user_fixture)
+        assert user.season_result is not None
         last = user.season_result.last
 
         assert last.elo_rate is None or isinstance(last.elo_rate, int)
@@ -504,7 +508,7 @@ class TestVodInfoFieldCoverage:
     def test_vod_info_structure(self):
         """Test VodInfo can be constructed with all fields."""
         # VodInfo is rare in the fixtures, so test the model directly
-        vod = VodInfo(uuid="abc123", url="https://twitch.tv/example", startsAt=12345)
+        vod = VodInfo(uuid="abc123", url="https://twitch.tv/example", starts_at=12345)
 
         assert isinstance(vod.uuid, str)
         assert isinstance(vod.url, str)
@@ -530,7 +534,7 @@ class TestPhaseResultFieldCoverage:
     def test_phase_result_structure(self):
         """Test PhaseResult can be constructed with all fields."""
         # Phases are often empty, so test the model directly
-        phase = PhaseResult(phase=1, eloRate=1500, eloRank=100, point=50)
+        phase = PhaseResult(phase=1, elo_rate=1500, elo_rank=100, point=50)
 
         assert isinstance(phase.phase, int)
         assert isinstance(phase.elo_rate, int)