pearatings 0.2.0__tar.gz

pearatings-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PEARatings
+
+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.

pearatings-0.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pearatings
+Version: 0.2.0
+Summary: Python client for the PEARatings college baseball and softball data API
+Author-email: PEARatings <pearatings@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pearatings.com
+Project-URL: Pricing, https://api.pearatings.com/billing
+Project-URL: Documentation, https://api.pearatings.com/docs
+Project-URL: Source, https://github.com/pearatings/pear-api
+Keywords: college baseball,college softball,ratings,sports analytics,api,ncaa,naia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: pandas>=1.3
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# pearatings
+
+Python client for the [PEARatings](https://pearatings.com) data API: college baseball (D1, D2, D3, NAIA)
+and softball (D1, D2, D3) ratings, projections, player stats, history, Lookup and tournament simulations.
+Tables come back as pandas DataFrames.
+
+## Install
+
+```bash
+pip install pearatings
+```
+
+## Get a key
+
+Pick a tier at **https://api.pearatings.com/billing**. Your key is shown once: copy it.
+
+| Tier | Price | API calls per month | Per minute |
+|---|---|---|---|
+| Free | $0 | 500 | 10 |
+| Starter | $1.99/month | 1,000 | 30 |
+| Plus | $4.99/month | 5,000 | 60 |
+| Pro | $9.99/month | 20,000 | 120 |
+| Max | $19.99/month | 50,000 | 120 |
+
+Every request is one call; `players()` fetches a full leaderboard 200 rows per call. Calls reset on the 1st
+(UTC). `pear.account()` shows your tier and calls used this month; `pear.billing_portal()` changes tier or cancels.
+
+## Set your key
+
+```bash
+export PEAR_API_KEY='your-key'        # single quotes if the key has a ! in it
+```
+or pass it: `Pear(api_key="your-key")`.
+
+## Quick start
+
+```python
+from pearatings import Pear
+
+pear = Pear()
+
+ratings = pear.ratings()                               # D1 baseball, current
+ratings.attrs["date"]                                  # when the ratings were updated
+pear.ratings(sport="softball", division="d2")
+
+pear.preseason(2027)                                   # preseason ratings
+pear.stats(2025)                                       # team stats + end-of-season ratings for 2025
+
+pear.games("2026-04-18")                               # that day's games with PEAR's line and win probability
+pear.matchup("LSU", "Florida", neutral=True)           # any two teams
+pear.team_schedule("LSU", 2026)["schedule"]            # every game of a team's season
+
+pear.players(2026)                                     # full hitting leaderboard (every page)
+pear.players(2026, side="pitching", conferences=["SEC"], limit=50)
+roster = pear.roster("LSU", 2026)
+pear.player(roster["player_id"].iloc[0])["games"]      # one player's game-by-game lines
+
+pear.history("LSU")                                    # end-of-season numbers, every season
+pear.tournament_outlook()                              # projected NCAA field
+pear.simulate_bracket(seed=7)                          # one simulated tournament
+
+open("lsu.png", "wb").write(pear.logo("LSU"))
+```
+
+Every method takes keyword-only `sport` (`"baseball"` default, or `"softball"`) and `division` (`"d1"`
+default, `"d2"`, `"d3"`, `"naia"`) unless it exists for one division only. Use `help(pear.games)` for any
+method's details.
+
+## What comes back
+
+- **One table** → a `DataFrame`; the rest of the response (data date, season, totals) is in `df.attrs`.
+- **Anything else** → a `dict`, where every list of records is a `DataFrame`.
+- Nested fields are flattened to dotted columns: `record.wins`, `stats.PA`.
+- `pear.get("baseball/d1/ratings")` / `pear.post(path, body)` return the raw JSON of any endpoint.
+
+## Methods
+
+| Area | Methods |
+|---|---|
+| Your account | `account`, `billing_portal` |
+| Teams and ratings | `ratings`, `preseason`, `stats`, `teams`, `team`, `team_conferences`, `conferences`, `conference_standings`, `records`, `pcr_ranks`, `combined_ratings`, `logo`, `conference_logo` |
+| Projections | `games`, `matchup`, `team_schedule`, `simulate_wins`, `season_projection`, `conference_projections` |
+| Players | `players`, `roster`, `player` |
+| History | `history`, `tournament_history`, `historical_table` |
+| Lookup | `lookup_fields`, `lookup_options`, `lookup` |
+| Tournaments | `tournament_outlook`, `tournament_regionals`, `tournament_team`, `simulate_bracket`, `conference_tournament_probs`, `d2_simulate_cary`, `naia_simulate_regional`, `naia_simulate_ws`, `naia_ws_odds` |
+
+## Lookup
+
+Find games or player games that meet conditions. Field keys come from `pear.lookup_fields()`.
+
+```python
+pear.lookup_fields()                                   # kind, key, label, group, unit
+
+# games where a team scored 25+ in 2026
+pear.lookup(2026, conditions=[{"kind": "team", "field": "R", "op": ">=", "value": 25, "scope": "either"}])
+
+# 3-homer games, 2021-2026
+pear.lookup(2021, 2026, mode="players", role="bat",
+            conditions=[{"kind": "player", "field": "HR", "op": ">=", "value": 3}], limit=200)
+```
+Up to 200 rows per call; `df.attrs["total"]` is the full count, page with `offset=`.
+
+## Errors
+
+All errors subclass `pearatings.PearError` and carry `.status_code`:
+`AuthenticationError` (bad or missing key, or a lapsed subscription), `NotFoundError` (unknown team / season),
+`InvalidRequestError` (bad parameters), `RateLimitError` (over your tier's limit; `.retry_after` says how many
+seconds to wait), `APIError` (anything else, e.g. data not available out of season).
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest                                                    # offline tests
+PEAR_API_KEY='...' PEAR_API_URL=http://127.0.0.1:8001 pytest -m live   # every method against a running API
+```
+`PEAR_API_URL` (or `Pear(base_url=...)`) points the client at another server; the default is
+`https://api.pearatings.com`.

pearatings-0.2.0/README.md

@@ -0,0 +1,119 @@
+# pearatings
+
+Python client for the [PEARatings](https://pearatings.com) data API: college baseball (D1, D2, D3, NAIA)
+and softball (D1, D2, D3) ratings, projections, player stats, history, Lookup and tournament simulations.
+Tables come back as pandas DataFrames.
+
+## Install
+
+```bash
+pip install pearatings
+```
+
+## Get a key
+
+Pick a tier at **https://api.pearatings.com/billing**. Your key is shown once: copy it.
+
+| Tier | Price | API calls per month | Per minute |
+|---|---|---|---|
+| Free | $0 | 500 | 10 |
+| Starter | $1.99/month | 1,000 | 30 |
+| Plus | $4.99/month | 5,000 | 60 |
+| Pro | $9.99/month | 20,000 | 120 |
+| Max | $19.99/month | 50,000 | 120 |
+
+Every request is one call; `players()` fetches a full leaderboard 200 rows per call. Calls reset on the 1st
+(UTC). `pear.account()` shows your tier and calls used this month; `pear.billing_portal()` changes tier or cancels.
+
+## Set your key
+
+```bash
+export PEAR_API_KEY='your-key'        # single quotes if the key has a ! in it
+```
+or pass it: `Pear(api_key="your-key")`.
+
+## Quick start
+
+```python
+from pearatings import Pear
+
+pear = Pear()
+
+ratings = pear.ratings()                               # D1 baseball, current
+ratings.attrs["date"]                                  # when the ratings were updated
+pear.ratings(sport="softball", division="d2")
+
+pear.preseason(2027)                                   # preseason ratings
+pear.stats(2025)                                       # team stats + end-of-season ratings for 2025
+
+pear.games("2026-04-18")                               # that day's games with PEAR's line and win probability
+pear.matchup("LSU", "Florida", neutral=True)           # any two teams
+pear.team_schedule("LSU", 2026)["schedule"]            # every game of a team's season
+
+pear.players(2026)                                     # full hitting leaderboard (every page)
+pear.players(2026, side="pitching", conferences=["SEC"], limit=50)
+roster = pear.roster("LSU", 2026)
+pear.player(roster["player_id"].iloc[0])["games"]      # one player's game-by-game lines
+
+pear.history("LSU")                                    # end-of-season numbers, every season
+pear.tournament_outlook()                              # projected NCAA field
+pear.simulate_bracket(seed=7)                          # one simulated tournament
+
+open("lsu.png", "wb").write(pear.logo("LSU"))
+```
+
+Every method takes keyword-only `sport` (`"baseball"` default, or `"softball"`) and `division` (`"d1"`
+default, `"d2"`, `"d3"`, `"naia"`) unless it exists for one division only. Use `help(pear.games)` for any
+method's details.
+
+## What comes back
+
+- **One table** → a `DataFrame`; the rest of the response (data date, season, totals) is in `df.attrs`.
+- **Anything else** → a `dict`, where every list of records is a `DataFrame`.
+- Nested fields are flattened to dotted columns: `record.wins`, `stats.PA`.
+- `pear.get("baseball/d1/ratings")` / `pear.post(path, body)` return the raw JSON of any endpoint.
+
+## Methods
+
+| Area | Methods |
+|---|---|
+| Your account | `account`, `billing_portal` |
+| Teams and ratings | `ratings`, `preseason`, `stats`, `teams`, `team`, `team_conferences`, `conferences`, `conference_standings`, `records`, `pcr_ranks`, `combined_ratings`, `logo`, `conference_logo` |
+| Projections | `games`, `matchup`, `team_schedule`, `simulate_wins`, `season_projection`, `conference_projections` |
+| Players | `players`, `roster`, `player` |
+| History | `history`, `tournament_history`, `historical_table` |
+| Lookup | `lookup_fields`, `lookup_options`, `lookup` |
+| Tournaments | `tournament_outlook`, `tournament_regionals`, `tournament_team`, `simulate_bracket`, `conference_tournament_probs`, `d2_simulate_cary`, `naia_simulate_regional`, `naia_simulate_ws`, `naia_ws_odds` |
+
+## Lookup
+
+Find games or player games that meet conditions. Field keys come from `pear.lookup_fields()`.
+
+```python
+pear.lookup_fields()                                   # kind, key, label, group, unit
+
+# games where a team scored 25+ in 2026
+pear.lookup(2026, conditions=[{"kind": "team", "field": "R", "op": ">=", "value": 25, "scope": "either"}])
+
+# 3-homer games, 2021-2026
+pear.lookup(2021, 2026, mode="players", role="bat",
+            conditions=[{"kind": "player", "field": "HR", "op": ">=", "value": 3}], limit=200)
+```
+Up to 200 rows per call; `df.attrs["total"]` is the full count, page with `offset=`.
+
+## Errors
+
+All errors subclass `pearatings.PearError` and carry `.status_code`:
+`AuthenticationError` (bad or missing key, or a lapsed subscription), `NotFoundError` (unknown team / season),
+`InvalidRequestError` (bad parameters), `RateLimitError` (over your tier's limit; `.retry_after` says how many
+seconds to wait), `APIError` (anything else, e.g. data not available out of season).
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest                                                    # offline tests
+PEAR_API_KEY='...' PEAR_API_URL=http://127.0.0.1:8001 pytest -m live   # every method against a running API
+```
+`PEAR_API_URL` (or `Pear(base_url=...)`) points the client at another server; the default is
+`https://api.pearatings.com`.

pearatings-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pearatings"
+dynamic = ["version"]
+description = "Python client for the PEARatings college baseball and softball data API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "PEARatings", email = "pearatings@gmail.com" }]
+keywords = ["college baseball", "college softball", "ratings", "sports analytics", "api", "ncaa", "naia"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.25", "pandas>=1.3"]
+
+[project.urls]
+Homepage = "https://pearatings.com"
+Pricing = "https://api.pearatings.com/billing"
+Documentation = "https://api.pearatings.com/docs"
+Source = "https://github.com/pearatings/pear-api"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.dynamic]
+version = { attr = "pearatings.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = ["live: calls a running PEARatings API (needs PEAR_API_KEY and PEAR_API_URL)"]

pearatings-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pearatings-0.2.0/src/pearatings/__init__.py

@@ -0,0 +1,14 @@
+"""PEARatings data API client for college baseball and softball.
+
+    from pearatings import Pear
+    pear = Pear()                      # reads PEAR_API_KEY
+    pear.ratings()                     # D1 baseball ratings as a DataFrame
+"""
+__version__ = "0.2.0"
+
+from .client import Pear  # noqa: E402
+from .errors import (APIError, AuthenticationError, InvalidRequestError, NotFoundError, PearError,  # noqa: E402
+                     RateLimitError)
+
+__all__ = ["Pear", "PearError", "AuthenticationError", "NotFoundError", "InvalidRequestError", "RateLimitError",
+           "APIError", "__version__"]

pearatings-0.2.0/src/pearatings/client.py

@@ -0,0 +1,393 @@
+"""The `Pear` client: one method per PEARatings data API endpoint (baseball and softball).
+
+Return values follow two rules:
+- An endpoint that returns one table comes back as a pandas DataFrame. Everything else in the response
+  (the data date, season, totals, ...) is in `df.attrs`.
+- Anything else comes back as a dict, in which every list of records is a DataFrame. Nested fields are
+  flattened to dotted column names (`record.wins`, `stats.PA`).
+"""
+import datetime as _dt
+import os
+from typing import Any, Dict, Iterable, List, Optional, Union
+from urllib.parse import quote
+
+import pandas as pd
+import requests
+
+from . import __version__
+from .errors import (APIError, AuthenticationError, InvalidRequestError, NotFoundError, PearError,
+                     RateLimitError)
+
+DEFAULT_BASE_URL = "https://api.pearatings.com"
+DIVISIONS = {"baseball": ("d1", "d2", "d3", "naia"), "softball": ("d1", "d2", "d3")}
+_ERRORS = {400: InvalidRequestError, 401: AuthenticationError, 403: AuthenticationError, 404: NotFoundError,
+           422: InvalidRequestError, 429: RateLimitError}
+_PAGE = 200  # the API's largest page for the player leaderboard and Lookup
+
+Date = Union[str, _dt.date]
+
+
+def _records(rows) -> pd.DataFrame:
+    return pd.json_normalize(rows) if rows else pd.DataFrame()
+
+
+def _frames(obj):
+    """Every list of records (dicts) inside a response becomes a DataFrame; dicts are walked recursively."""
+    if isinstance(obj, list) and obj and all(isinstance(x, dict) for x in obj):
+        return _records(obj)
+    if isinstance(obj, dict):
+        return {k: _frames(v) for k, v in obj.items()}
+    return obj
+
+
+def _table(data: dict, key: str) -> pd.DataFrame:
+    """data[key] as a DataFrame, with the rest of the response in .attrs."""
+    df = _records(data.get(key))
+    df.attrs = {k: v for k, v in data.items() if k != key}
+    return df
+
+
+def _drop_none(d: Optional[dict]) -> Optional[dict]:
+    return None if d is None else {k: v for k, v in d.items() if v is not None}
+
+
+def _csv(values: Union[None, str, Iterable[str]]) -> Optional[str]:
+    return values if values is None or isinstance(values, str) else ",".join(values)
+
+
+def _seg(text: str) -> str:
+    """A team / conference / player name as one URL path segment."""
+    return quote(str(text), safe="")
+
+
+class Pear:
+    """PEARatings data API client.
+
+        from pearatings import Pear
+        pear = Pear()                         # key from the PEAR_API_KEY environment variable
+        pear = Pear(api_key="...")            # or pass it
+
+    Every method takes keyword-only `sport` ("baseball" | "softball", default "baseball") and `division`
+    ("d1" | "d2" | "d3" | "naia", default "d1") unless it exists for one division only.
+    The API address comes from `base_url`, else the PEAR_API_URL environment variable, else
+    https://api.pearatings.com.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 60):
+        self.api_key = api_key or os.environ.get("PEAR_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError("No API key: pass Pear(api_key=...) or set the PEAR_API_KEY environment variable")
+        self.base_url = (base_url or os.environ.get("PEAR_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"X-API-Key": self.api_key, "User-Agent": f"pearatings-python/{__version__}"})
+
+    def __repr__(self):
+        return f"Pear(base_url={self.base_url!r})"
+
+    # ------------------------------------------------------------------ plumbing
+
+    def _request(self, method: str, path: str, params: Optional[dict] = None, json: Optional[dict] = None):
+        try:
+            r = self.session.request(method, f"{self.base_url}/v1/{path}", params=_drop_none(params),
+                                     json=_drop_none(json), timeout=self.timeout)
+        except requests.RequestException as e:
+            raise PearError(f"Could not reach {self.base_url}: {e}") from e
+        if r.status_code >= 400:
+            try:
+                detail = r.json().get("detail", r.text)
+            except ValueError:
+                detail = r.text or r.reason
+            if r.status_code == 429:
+                after = r.headers.get("Retry-After")
+                raise RateLimitError(f"429: {detail}", status_code=429,
+                                     retry_after=int(after) if after and after.isdigit() else None)
+            raise _ERRORS.get(r.status_code, APIError)(f"{r.status_code}: {detail}", status_code=r.status_code)
+        return r
+
+    def get(self, path: str, **params) -> Any:
+        """Raw GET of any /v1 path (without the /v1/ prefix); returns the JSON as is.
+        Example: pear.get("baseball/d1/ratings")."""
+        return self._request("GET", path, params=params).json()
+
+    def post(self, path: str, body: Optional[dict] = None) -> Any:
+        """Raw POST of any /v1 path (without the /v1/ prefix); returns the JSON as is."""
+        return self._request("POST", path, json=body or {}).json()
+
+    @staticmethod
+    def _div(sport: str, division: str) -> str:
+        sport, division = sport.lower(), division.lower()
+        if division not in DIVISIONS.get(sport, ()):
+            raise ValueError(f"Unknown sport/division {sport}/{division}; choose from {DIVISIONS}")
+        return f"{sport}/{division}"
+
+    def _only(self, allowed, sport: str, division: str) -> str:
+        path = self._div(sport, division)
+        if path not in allowed:
+            raise ValueError(f"Only available for {', '.join(allowed)}")
+        return path
+
+    # ------------------------------------------------------------------ your account
+
+    def account(self) -> dict:
+        """Your key's tier, its limits (calls per month and per minute), calls used this month (UTC; resets on the
+        1st) and subscription status."""
+        return self.get("account")
+
+    def billing_portal(self, open_browser: bool = True) -> str:
+        """A one-time link to Stripe's customer portal (change tier, cancel, change card, download invoices). Opens it
+        in your browser unless open_browser=False; returns the link either way. Paid tiers only."""
+        url = self.post("account/portal")["url"]
+        if open_browser:
+            import webbrowser
+            webbrowser.open(url)
+        return url
+
+    # ------------------------------------------------------------------ teams and ratings
+
+    def ratings(self, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Current Team Strength Ratings (TSR) and PCR for every team. attrs: date."""
+        return _table(self.get(f"{self._div(sport, division)}/ratings"), "teams")
+
+    def preseason(self, season: int, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """A season's preseason ratings: the projection the season started from. D1 baseball has them back to
+        2001; other divisions from 2026."""
+        return _table(self.get(f"{self._div(sport, division)}/preseason", season=season), "teams")
+
+    def stats(self, season: Optional[int] = None, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Every team's calculated stats and ratings for a season (default: current). For a finished season these
+        are the end-of-season ratings. attrs: date, season, columnMetadata."""
+        return _table(self.get(f"{self._div(sport, division)}/stats", season=season), "stats")
+
+    def teams(self, season: Optional[int] = None, *, sport: str = "baseball", division: str = "d1") -> List[str]:
+        """Team names, in the exact spelling every other method expects."""
+        return self.get(f"{self._div(sport, division)}/teams", season=season)["teams"]
+
+    def team(self, team: str, *, sport: str = "baseball", division: str = "d1") -> dict:
+        """One team: its ratings row (`team`), `upcoming_games` and `recent_games` with projections, `date`."""
+        return _frames(self.get(f"{self._div(sport, division)}/team/{_seg(team)}"))
+
+    def team_conferences(self, season: Optional[int] = None, *, sport: str = "baseball",
+                         division: str = "d1") -> Dict[str, str]:
+        """{team: conference}."""
+        return self.get(f"{self._div(sport, division)}/team-conferences", season=season)["team_conferences"]
+
+    def conferences(self, season: Optional[int] = None, *, sport: str = "baseball", division: str = "d1") -> List[str]:
+        """Conference names."""
+        return self.get(f"{self._div(sport, division)}/conferences", season=season)["conferences"]
+
+    def conference_standings(self, conference: str, *, division: str = "d1") -> pd.DataFrame:
+        """Current standings of one baseball conference. attrs: conference, date."""
+        return _table(self.get(f"{self._div('baseball', division)}/conference/{_seg(conference)}"), "teams")
+
+    def records(self, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Current W-L, conference W-L, PCR and PCR score for every team, one row per team (in season only)."""
+        records = self.get(f"{self._div(sport, division)}/current-records")["records"]
+        return pd.DataFrame.from_dict(records, orient="index").rename_axis("Team").reset_index()
+
+    def pcr_ranks(self, *, sport: str = "baseball", division: str = "d1") -> Dict[str, int]:
+        """{team: PCR rank}."""
+        return self.get(f"{self._div(sport, division)}/team-pcrs")["team_pcrs"]
+
+    def combined_ratings(self) -> pd.DataFrame:
+        """Every baseball team (D1, D2, D3, NAIA) on one rating scale."""
+        return _records(self.get("baseball/combined-ratings"))
+
+    def logo(self, team: str, *, sport: str = "baseball", division: str = "d1", variant: Optional[str] = None) -> bytes:
+        """A team's logo as PNG bytes. `variant="dark"` gives the version drawn for dark backgrounds where there
+        is one. Save it with open("logo.png", "wb").write(pear.logo("LSU"))."""
+        return self._request("GET", f"{self._div(sport, division)}/logo/{_seg(team)}",
+                             params={"variant": variant}).content
+
+    def conference_logo(self, conference: str) -> bytes:
+        """A conference's logo as PNG bytes."""
+        return self._request("GET", f"conference-logo/{_seg(conference)}").content
+
+    # ------------------------------------------------------------------ projections
+
+    def games(self, date: Optional[Date] = None, *, team: Optional[str] = None, conference: Optional[str] = None,
+              season: Optional[int] = None, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Games on a date (default: today, or the next day with games) with PEAR's line, win probability and
+        game quality (GQI); final scores once played. Filter by `team` or `conference`. `season` defaults to the
+        date's year. attrs: date, count, min_date, max_date (the season's first and last game dates)."""
+        if isinstance(date, _dt.date):
+            date = date.isoformat()
+        if date and season is None:
+            season = int(date[:4])
+        return _table(self.get(f"{self._div(sport, division)}/games", date=date, team=team, conference=conference,
+                               season=season), "games")
+
+    def matchup(self, away: str, home: str, *, neutral: bool = False, season: Optional[int] = None,
+                sport: str = "baseball", division: str = "d1") -> dict:
+        """Projected line and win probabilities for any two teams: spread, formatted_spread, home_win_prob and
+        away_win_prob (percent, 0-100; games() gives 0-1), game_quality, home_pr, away_pr."""
+        return self.post(f"{self._div(sport, division)}/matchup",
+                         {"away_team": away, "home_team": home, "neutral": neutral, "season": season})
+
+    def team_schedule(self, team: str, season: Optional[int] = None, *, sport: str = "baseball",
+                      division: str = "d1") -> dict:
+        """A team's full season: `schedule` (every game with its projection or result), `metrics` (ranks),
+        `resume_path` (D1 baseball), `head_coach`, `data_date`."""
+        return _frames(self.post(f"{self._div(sport, division)}/team-schedule", {"team_name": team, "season": season}))
+
+    def simulate_wins(self, team: str, *, rating: Optional[float] = None, num_simulations: Optional[int] = None,
+                      conference_only: bool = False, sport: str = "baseball", division: str = "d1") -> dict:
+        """Simulate the rest of a team's season: expected_wins, min/max, and the `distribution` of final win
+        totals. Pass `rating` to see the effect of a different team rating."""
+        return _frames(self.post(f"{self._div(sport, division)}/simulate-wins",
+                                 {"team_name": team, "rating": rating, "num_simulations": num_simulations,
+                                  "conference_only": conference_only}))
+
+    def season_projection(self, *, sport: str = "baseball", division: str = "d1") -> dict:
+        """The whole projected season: `projected_pcr` (final PCR projection), `tournament_outlook` (projected
+        field) and `team_simulated_results` ({team: projected games})."""
+        return _frames(self.get(f"{self._div(sport, division)}/season-projection"))
+
+    def conference_projections(self, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """One row per team: current and projected overall / conference records, PCR, TSR. attrs: date."""
+        data = self.get(f"{self._div(sport, division)}/conference-view")
+        df = _records([t for conf in data["conferences"] for t in conf["teams"]])
+        df.attrs = {"date": data.get("date")}
+        return df
+
+    # ------------------------------------------------------------------ players
+
+    def players(self, season: Optional[int] = None, *, side: str = "hitting", sort: Optional[str] = None,
+                order: Optional[str] = None, conferences: Union[None, str, Iterable[str]] = None,
+                positions: Union[None, str, Iterable[str]] = None, search: Optional[str] = None,
+                limit: Optional[int] = None, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Player leaderboard for a season: `side` "hitting" or "pitching", sorted by `sort` (a stat column;
+        default PRV) in `order` ("asc" | "desc"). Filters: `conferences`, `positions` (hitting: C, IF, OF, UT,
+        DH), `search` (player or team name). Returns every matching player unless you set `limit`.
+        attrs: total, season, side, sort, and the filter values."""
+        path = f"{self._div(sport, division)}/players"
+        params = {"season": season, "side": side, "sort": sort, "order": order, "conferences": _csv(conferences),
+                  "pos": _csv(positions), "q": search}
+        pages, offset = [], 0
+        while True:
+            page = min(_PAGE, limit - offset) if limit else _PAGE
+            data = self.get(path, **params, offset=offset, limit=page)
+            pages.extend(data["players"])
+            offset += len(data["players"])
+            if not data["players"] or offset >= data["total"] or (limit and offset >= limit):
+                break
+        data["players"] = pages
+        return _table(data, "players")
+
+    def roster(self, team: str, season: Optional[int] = None, *, sport: str = "baseball",
+               division: str = "d1") -> pd.DataFrame:
+        """A team's players for a season with their season stats (hitting, pitching `p_*`, fielding `f_*`) and
+        roster details. Before a season starts: next season's roster with each player's status.
+        attrs: team, season, platform (where the stats came from), returning."""
+        return _table(self.get(f"{self._div(sport, division)}/roster", team=team, season=season), "players")
+
+    def player(self, player_id: str, *, sport: str = "baseball") -> dict:
+        """One player by id (the `player_id` column of `roster` / `players`): bio, `seasons` (season lines) and
+        `games` (game-by-game lines)."""
+        if sport not in DIVISIONS:
+            raise ValueError(f"Unknown sport {sport}")
+        return _frames(self.get(f"{sport}/player/{_seg(player_id)}"))
+
+    # ------------------------------------------------------------------ history
+
+    def history(self, team: str, *, division: str = "d1") -> pd.DataFrame:
+        """A baseball team's end-of-season rating, rank, PCR and RPI for every season on record. attrs: team."""
+        return _table(self.get(f"{self._div('baseball', division)}/history", team=team), "history")
+
+    def tournament_history(self, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Past national tournament results by year (not NAIA)."""
+        return _table(self.get(f"{self._div(sport, division)}/tournament-history"), "years")
+
+    def historical_table(self) -> pd.DataFrame:
+        """D1 baseball: every team's end-of-season numbers for every season since 1999."""
+        return _table(self.get("baseball/d1/historical-table"), "data")
+
+    # ------------------------------------------------------------------ lookup
+
+    def lookup_options(self, *, sport: str = "baseball", division: str = "d1") -> dict:
+        """What Lookup can search: `seasons`, `fields` by kind (game, team, bat, pit) and `scopes`."""
+        return _frames(self.get(f"{self._div(sport, division)}/lookup-options"))
+
+    def lookup_fields(self, *, sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Every Lookup field in one table: kind (game | team | bat | pit), key (what a condition's `field`
+        takes), label, group, unit."""
+        fields = self.get(f"{self._div(sport, division)}/lookup-options")["fields"]
+        return _records([dict(f, kind=kind) for kind, rows in fields.items() for f in rows])
+
+    def lookup(self, season_from: int, season_to: Optional[int] = None, *, mode: str = "games", role: str = "bat",
+               conditions: Optional[List[dict]] = None, match: str = "all", team: Optional[str] = None,
+               sort: Optional[str] = None, desc: bool = True, limit: int = 50, offset: int = 0,
+               sport: str = "baseball", division: str = "d1") -> pd.DataFrame:
+        """Search games (`mode="games"`) or player games (`mode="players"`, `role` "bat" | "pit") that meet
+        `conditions` (all of them with match="all", any with "any"). Each condition is a dict:
+            {"kind": "team", "field": "R", "op": ">=", "value": 20, "scope": "either"}   # a team scored 20+
+            {"kind": "game", "field": "innings", "op": ">=", "value": 12}                 # 12+ innings
+            {"kind": "player", "field": "HR", "op": ">=", "value": 3}                     # mode="players"
+        `op` is ">=", "<=" or "="; `field` is a key from lookup_fields(); team conditions need a `scope`
+        (either, both, total, winner, loser, home, away, team, opp). `team` limits the search to teams whose
+        name contains it. Up to 200 rows per call; page with `offset`. attrs: total, columns."""
+        return _table(self.post(f"{self._div(sport, division)}/lookup", {
+            "mode": mode, "role": role, "season_from": season_from, "season_to": season_to or season_from,
+            "conditions": conditions or [], "match": match, "team": team, "sort": sort, "desc": desc,
+            "limit": limit, "offset": offset}), "rows")
+
+    # ------------------------------------------------------------------ tournaments
+
+    def tournament_outlook(self, *, sport: str = "baseball", division: str = "d1") -> dict:
+        """The projected national tournament field (the actual bracket once it is set): regionals (D2:
+        regions), bubble lists, automatic qualifiers, multi-bid conferences, team ratings."""
+        return _frames(self.get(f"{self._div(sport, division)}/tournament/outlook"))
+
+    def tournament_regionals(self, season: Optional[int] = None) -> dict:
+        """D1 baseball, once the tournament starts (default: current season): regionals, every regional / super
+        regional / CWS game with its projection or result, regional winners, the CWS bracket."""
+        return _frames(self.get("baseball/d1/tournament/regionals", season=season))
+
+    def tournament_team(self, team: str, *, sport: str = "baseball", division: str = "d1") -> dict:
+        """One tournament team's numbers: rating and rank, PCR, record, Q1 record, regional win probability
+        (D1 baseball, D1 softball, D3 baseball)."""
+        path = self._only(("baseball/d1", "softball/d1", "baseball/d3"), sport, division)
+        return self.get(f"{path}/tournament/team", team=team)
+
+    def simulate_bracket(self, outlook: Optional[dict] = None, *, seed: Optional[int] = None,
+                         sport: str = "baseball", division: str = "d1") -> dict:
+        """Simulate the national tournament once: regional winners through the champion. D1 baseball, D1
+        softball and D3 baseball use `outlook` (from tournament_outlook(); fetched when omitted); D2 baseball
+        needs no outlook. Same `seed` = same result."""
+        path = self._only(("baseball/d1", "softball/d1", "baseball/d3", "baseball/d2"), sport, division)
+        if path == "baseball/d2":
+            body = {"seed": seed}
+        else:
+            outlook = outlook or self.get(f"{path}/tournament/outlook")
+            regionals = outlook["regionals"]
+            if isinstance(regionals, pd.DataFrame):
+                regionals = regionals.to_dict("records")
+            body = {"regionals": regionals, "ratings": outlook["ratings"], "seed": seed}
+        return _frames(self.post(f"{path}/tournament/simulate-bracket", body))
+
+    def d2_simulate_cary(self, teams: List[str], *, seed: Optional[int] = None) -> dict:
+        """D2 baseball: simulate the 8-team finals in Cary from the 8 regional winners, best PCR first."""
+        return _frames(self.post("baseball/d2/tournament/simulate-cary", {"teams": teams, "seed": seed}))
+
+    def naia_simulate_regional(self, seeds: List[str], *, format: str = "5team", seed: Optional[int] = None) -> dict:
+        """NAIA: simulate one opening-round regional (`format` "4team" or "5team", seeds in order)."""
+        return _frames(self.post("baseball/naia/tournament/simulate-regional",
+                                 {"seeds": seeds, "format": format, "seed": seed}))
+
+    def naia_simulate_ws(self, teams: Optional[List[str]] = None, *, regional_picks: Optional[dict] = None,
+                         seed: Optional[int] = None, n: Optional[int] = None) -> dict:
+        """NAIA: simulate the World Series. With no `teams`, one winner per regional is drawn first."""
+        return _frames(self.post("baseball/naia/tournament/simulate-ws",
+                                 {"teams": teams or [], "regional_picks": regional_picks or {}, "seed": seed, "n": n}))
+
+    def naia_ws_odds(self, teams: List[str]) -> dict:
+        """NAIA: each team's chance to win the World Series from its 10 seeds (exact, not simulated)."""
+        return _frames(self.post("baseball/naia/tournament/ws-champion-odds", {"teams": teams}))
+
+    def conference_tournament_probs(self, conference: str, *, locked_matchups: Optional[List[dict]] = None) -> dict:
+        """D1 baseball: each team's chance to reach every round of its conference tournament and win it.
+        `locked_matchups` fixes results already decided: [{"winner": "LSU", "loser": "Florida"}, ...]."""
+        if locked_matchups:
+            return _frames(self.post("baseball/d1/conference-tournament/probs-with-picks",
+                                     {"conference": conference, "locked_matchups": locked_matchups}))
+        return _frames(self.post("baseball/d1/conference-tournament/probs", {"conference": conference}))

pearatings-0.2.0/src/pearatings/errors.py

@@ -0,0 +1,34 @@
+"""Errors raised by the PEARatings client. Catch `PearError` to handle all of them."""
+
+
+class PearError(Exception):
+    """Base class. `status_code` is the HTTP status (None when no request was made)."""
+
+    def __init__(self, message, status_code=None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(PearError):
+    """No API key, the API doesn't know it (HTTP 401), or it is no longer active: revoked or the subscription
+    lapsed (HTTP 403)."""
+
+
+class NotFoundError(PearError):
+    """Unknown team, player, season or division, or no data for it yet (HTTP 404)."""
+
+
+class InvalidRequestError(PearError):
+    """The API rejected the parameters (HTTP 400 / 422)."""
+
+
+class RateLimitError(PearError):
+    """Over your tier's per-minute or monthly limit (HTTP 429). `retry_after` is the seconds to wait (or None)."""
+
+    def __init__(self, message, status_code=None, retry_after=None):
+        super().__init__(message, status_code)
+        self.retry_after = retry_after
+
+
+class APIError(PearError):
+    """Any other error from the API (HTTP 5xx, or data not available right now, e.g. 503 out of season)."""

pearatings-0.2.0/src/pearatings.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pearatings
+Version: 0.2.0
+Summary: Python client for the PEARatings college baseball and softball data API
+Author-email: PEARatings <pearatings@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pearatings.com
+Project-URL: Pricing, https://api.pearatings.com/billing
+Project-URL: Documentation, https://api.pearatings.com/docs
+Project-URL: Source, https://github.com/pearatings/pear-api
+Keywords: college baseball,college softball,ratings,sports analytics,api,ncaa,naia
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: pandas>=1.3
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# pearatings
+
+Python client for the [PEARatings](https://pearatings.com) data API: college baseball (D1, D2, D3, NAIA)
+and softball (D1, D2, D3) ratings, projections, player stats, history, Lookup and tournament simulations.
+Tables come back as pandas DataFrames.
+
+## Install
+
+```bash
+pip install pearatings
+```
+
+## Get a key
+
+Pick a tier at **https://api.pearatings.com/billing**. Your key is shown once: copy it.
+
+| Tier | Price | API calls per month | Per minute |
+|---|---|---|---|
+| Free | $0 | 500 | 10 |
+| Starter | $1.99/month | 1,000 | 30 |
+| Plus | $4.99/month | 5,000 | 60 |
+| Pro | $9.99/month | 20,000 | 120 |
+| Max | $19.99/month | 50,000 | 120 |
+
+Every request is one call; `players()` fetches a full leaderboard 200 rows per call. Calls reset on the 1st
+(UTC). `pear.account()` shows your tier and calls used this month; `pear.billing_portal()` changes tier or cancels.
+
+## Set your key
+
+```bash
+export PEAR_API_KEY='your-key'        # single quotes if the key has a ! in it
+```
+or pass it: `Pear(api_key="your-key")`.
+
+## Quick start
+
+```python
+from pearatings import Pear
+
+pear = Pear()
+
+ratings = pear.ratings()                               # D1 baseball, current
+ratings.attrs["date"]                                  # when the ratings were updated
+pear.ratings(sport="softball", division="d2")
+
+pear.preseason(2027)                                   # preseason ratings
+pear.stats(2025)                                       # team stats + end-of-season ratings for 2025
+
+pear.games("2026-04-18")                               # that day's games with PEAR's line and win probability
+pear.matchup("LSU", "Florida", neutral=True)           # any two teams
+pear.team_schedule("LSU", 2026)["schedule"]            # every game of a team's season
+
+pear.players(2026)                                     # full hitting leaderboard (every page)
+pear.players(2026, side="pitching", conferences=["SEC"], limit=50)
+roster = pear.roster("LSU", 2026)
+pear.player(roster["player_id"].iloc[0])["games"]      # one player's game-by-game lines
+
+pear.history("LSU")                                    # end-of-season numbers, every season
+pear.tournament_outlook()                              # projected NCAA field
+pear.simulate_bracket(seed=7)                          # one simulated tournament
+
+open("lsu.png", "wb").write(pear.logo("LSU"))
+```
+
+Every method takes keyword-only `sport` (`"baseball"` default, or `"softball"`) and `division` (`"d1"`
+default, `"d2"`, `"d3"`, `"naia"`) unless it exists for one division only. Use `help(pear.games)` for any
+method's details.
+
+## What comes back
+
+- **One table** → a `DataFrame`; the rest of the response (data date, season, totals) is in `df.attrs`.
+- **Anything else** → a `dict`, where every list of records is a `DataFrame`.
+- Nested fields are flattened to dotted columns: `record.wins`, `stats.PA`.
+- `pear.get("baseball/d1/ratings")` / `pear.post(path, body)` return the raw JSON of any endpoint.
+
+## Methods
+
+| Area | Methods |
+|---|---|
+| Your account | `account`, `billing_portal` |
+| Teams and ratings | `ratings`, `preseason`, `stats`, `teams`, `team`, `team_conferences`, `conferences`, `conference_standings`, `records`, `pcr_ranks`, `combined_ratings`, `logo`, `conference_logo` |
+| Projections | `games`, `matchup`, `team_schedule`, `simulate_wins`, `season_projection`, `conference_projections` |
+| Players | `players`, `roster`, `player` |
+| History | `history`, `tournament_history`, `historical_table` |
+| Lookup | `lookup_fields`, `lookup_options`, `lookup` |
+| Tournaments | `tournament_outlook`, `tournament_regionals`, `tournament_team`, `simulate_bracket`, `conference_tournament_probs`, `d2_simulate_cary`, `naia_simulate_regional`, `naia_simulate_ws`, `naia_ws_odds` |
+
+## Lookup
+
+Find games or player games that meet conditions. Field keys come from `pear.lookup_fields()`.
+
+```python
+pear.lookup_fields()                                   # kind, key, label, group, unit
+
+# games where a team scored 25+ in 2026
+pear.lookup(2026, conditions=[{"kind": "team", "field": "R", "op": ">=", "value": 25, "scope": "either"}])
+
+# 3-homer games, 2021-2026
+pear.lookup(2021, 2026, mode="players", role="bat",
+            conditions=[{"kind": "player", "field": "HR", "op": ">=", "value": 3}], limit=200)
+```
+Up to 200 rows per call; `df.attrs["total"]` is the full count, page with `offset=`.
+
+## Errors
+
+All errors subclass `pearatings.PearError` and carry `.status_code`:
+`AuthenticationError` (bad or missing key, or a lapsed subscription), `NotFoundError` (unknown team / season),
+`InvalidRequestError` (bad parameters), `RateLimitError` (over your tier's limit; `.retry_after` says how many
+seconds to wait), `APIError` (anything else, e.g. data not available out of season).
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest                                                    # offline tests
+PEAR_API_KEY='...' PEAR_API_URL=http://127.0.0.1:8001 pytest -m live   # every method against a running API
+```
+`PEAR_API_URL` (or `Pear(base_url=...)`) points the client at another server; the default is
+`https://api.pearatings.com`.

pearatings-0.2.0/src/pearatings.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/pearatings/__init__.py
+src/pearatings/client.py
+src/pearatings/errors.py
+src/pearatings.egg-info/PKG-INFO
+src/pearatings.egg-info/SOURCES.txt
+src/pearatings.egg-info/dependency_links.txt
+src/pearatings.egg-info/requires.txt
+src/pearatings.egg-info/top_level.txt
+tests/test_client.py
+tests/test_live.py

pearatings-0.2.0/src/pearatings.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pearatings-0.2.0/src/pearatings.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.25
+pandas>=1.3
+
+[test]
+pytest

pearatings-0.2.0/src/pearatings.egg-info/top_level.txt

@@ -0,0 +1 @@
+pearatings

pearatings-0.2.0/tests/test_client.py

@@ -0,0 +1,128 @@
+"""Offline tests: no network, the HTTP session is replaced by a fake that records requests."""
+import json
+
+import pandas as pd
+import pytest
+
+from pearatings import AuthenticationError, NotFoundError, Pear, RateLimitError
+
+
+class FakeResponse:
+    def __init__(self, status=200, body=None, content=b""):
+        self.status_code, self._body, self.content, self.headers = status, body, content, {}
+        self.text, self.reason = json.dumps(body), "reason"
+
+    def json(self):
+        if self._body is None:
+            raise ValueError
+        return self._body
+
+
+class FakeSession:
+    def __init__(self, response):
+        self.response, self.calls, self.headers = response, [], {}
+
+    def request(self, method, url, params=None, json=None, timeout=None):
+        self.calls.append({"method": method, "url": url, "params": params, "json": json})
+        return self.response
+
+
+def client(response):
+    pear = Pear(api_key="k", base_url="http://api.test/")
+    pear.session = FakeSession(response)
+    return pear
+
+
+def test_key_required(monkeypatch):
+    monkeypatch.delenv("PEAR_API_KEY", raising=False)
+    with pytest.raises(AuthenticationError):
+        Pear()
+    monkeypatch.setenv("PEAR_API_KEY", "from-env")
+    assert Pear().session.headers["X-API-Key"] == "from-env"
+
+
+def test_base_url_from_env(monkeypatch):
+    monkeypatch.setenv("PEAR_API_URL", "http://127.0.0.1:8001/")
+    assert Pear(api_key="k").base_url == "http://127.0.0.1:8001"
+
+
+def test_table_endpoint_returns_dataframe_with_attrs():
+    pear = client(FakeResponse(body={"teams": [{"Team": "LSU", "power_rating": 6.1}], "date": "May 1", "count": 1}))
+    df = pear.ratings(sport="softball", division="d2")
+    assert isinstance(df, pd.DataFrame) and df.loc[0, "Team"] == "LSU"
+    assert df.attrs == {"date": "May 1", "count": 1}
+    assert pear.session.calls[0]["url"] == "http://api.test/v1/softball/d2/ratings"
+
+
+def test_none_params_are_dropped_and_names_are_escaped():
+    pear = client(FakeResponse(body={"team": {}, "upcoming_games": [], "recent_games": []}))
+    pear.team("Texas A&M")
+    call = pear.session.calls[0]
+    assert call["url"].endswith("/v1/baseball/d1/team/Texas%20A%26M")
+    pear.games(date=None, team="LSU")
+    assert pear.session.calls[1]["params"] == {"team": "LSU"}
+    pear.games(__import__("datetime").date(2026, 4, 18))
+    assert pear.session.calls[2]["params"] == {"date": "2026-04-18", "season": 2026}
+
+
+def test_nested_records_become_flat_frames():
+    body = {"schedule": [{"Opponent": "UNO", "record": {"wins": 3}}], "metrics": {"pcr": 4}}
+    out = client(FakeResponse(body=body)).team_schedule("LSU")
+    assert list(out["schedule"].columns) == ["Opponent", "record.wins"] and out["metrics"] == {"pcr": 4}
+
+
+def test_players_pages_until_total():
+    pages = [{"total": 3, "players": [{"n": 1}, {"n": 2}]}, {"total": 3, "players": [{"n": 3}]}]
+
+    class Paging(FakeSession):
+        def request(self, *a, **k):
+            super().request(*a, **k)
+            return FakeResponse(body=dict(pages[len(self.calls) - 1]))
+
+    pear = Pear(api_key="k", base_url="http://api.test")
+    pear.session = Paging(None)
+    df = pear.players(season=2026, conferences=["SEC", "ACC"])
+    assert df["n"].tolist() == [1, 2, 3]
+    assert pear.session.calls[0]["params"]["conferences"] == "SEC,ACC"
+    assert pear.session.calls[1]["params"]["offset"] == 2
+
+
+def test_records_one_row_per_team():
+    body = {"records": {"LSU": {"wins": 5, "losses": 1}, "UNO": {"wins": 2, "losses": 4}}}
+    df = client(FakeResponse(body=body)).records()
+    assert df.columns[0] == "Team" and df.set_index("Team").loc["UNO", "losses"] == 4
+
+
+@pytest.mark.parametrize("status,error", [(401, AuthenticationError), (403, AuthenticationError), (404, NotFoundError),
+                                          (429, RateLimitError)])
+def test_http_errors(status, error):
+    with pytest.raises(error) as e:
+        client(FakeResponse(status=status, body={"detail": "nope"})).ratings()
+    assert e.value.status_code == status and "nope" in str(e.value)
+
+
+def test_bad_division_fails_before_any_request():
+    pear = client(FakeResponse(body={}))
+    with pytest.raises(ValueError):
+        pear.ratings(sport="softball", division="naia")
+    with pytest.raises(ValueError):
+        pear.tournament_team("X", division="d2")
+    assert pear.session.calls == []
+
+
+def test_logo_returns_bytes():
+    assert client(FakeResponse(content=b"\x89PNG")).logo("LSU") == b"\x89PNG"
+
+
+def test_rate_limit_carries_retry_after():
+    resp = FakeResponse(status=429, body={"detail": "Rate limit: 60 requests per minute"})
+    resp.headers = {"Retry-After": "17"}
+    with pytest.raises(RateLimitError) as e:
+        client(resp).ratings()
+    assert e.value.retry_after == 17
+
+
+def test_account_and_portal():
+    pear = client(FakeResponse(body={"url": "https://billing.stripe.com/p/session/x"}))
+    assert pear.billing_portal(open_browser=False) == "https://billing.stripe.com/p/session/x"
+    assert pear.session.calls[0]["method"] == "POST" and pear.session.calls[0]["url"].endswith("/v1/account/portal")

pearatings-0.2.0/tests/test_live.py

@@ -0,0 +1,100 @@
+"""Calls every client method against a running API. Skipped unless PEAR_API_KEY and PEAR_API_URL are set:
+    PEAR_API_KEY='...' PEAR_API_URL=http://127.0.0.1:8001 pytest -m live
+Uses 2026 data, so some calls need that season on the server."""
+import os
+
+import pandas as pd
+import pytest
+
+from pearatings import APIError, NotFoundError, Pear
+
+pytestmark = [pytest.mark.live,
+              pytest.mark.skipif(not (os.environ.get("PEAR_API_KEY") and os.environ.get("PEAR_API_URL")),
+                                 reason="needs PEAR_API_KEY and PEAR_API_URL")]
+
+
+@pytest.fixture(scope="module")
+def pear():
+    return Pear()
+
+
+def frame(df, min_rows=1):
+    assert isinstance(df, pd.DataFrame) and len(df) >= min_rows, df
+    return df
+
+
+def test_teams_and_ratings(pear):
+    frame(pear.ratings(), 250)
+    frame(pear.ratings(sport="softball", division="d3"), 100)
+    assert frame(pear.preseason(2027)).iloc[0]["Team"]
+    frame(pear.preseason(2005))
+    with pytest.raises(NotFoundError):
+        pear.preseason(1990)
+    frame(pear.stats(2026), 250)
+    frame(pear.stats(2026, sport="baseball", division="naia"))
+    teams = pear.teams()
+    assert "LSU" in teams
+    assert isinstance(pear.team("LSU")["team"], dict)
+    assert pear.team_conferences()["LSU"] == "SEC"
+    assert "SEC" in pear.conferences()
+    frame(pear.conference_standings("SEC"))
+    assert isinstance(pear.pcr_ranks()["LSU"], int)
+    frame(pear.combined_ratings(), 1000)
+    assert pear.logo("LSU").startswith(b"\x89PNG")
+    assert pear.logo("Oklahoma", sport="softball", variant="dark").startswith(b"\x89PNG")
+    assert pear.conference_logo("SEC").startswith(b"\x89PNG")
+
+
+def test_projections(pear):
+    games = frame(pear.games("2026-04-18"), 50)
+    assert {"home_team", "away_team", "home_win_prob"} <= set(games.columns)
+    frame(pear.games(conference="SEC"), 0)
+    m = pear.matchup("LSU", "Florida")
+    assert 0 < m["home_win_prob"] < 100   # percent here; games() uses 0-1
+    s = pear.team_schedule("LSU", 2026)
+    frame(s["schedule"], 50)
+    w = pear.simulate_wins("LSU", rating=7.0)
+    frame(w["distribution"])
+    frame(pear.season_projection(division="d2")["projected_pcr"]["teams"], 100)
+    assert {"team", "conference"} <= set(frame(pear.conference_projections(), 250).columns)
+
+
+def test_players(pear):
+    hitters = frame(pear.players(2026, limit=250), 250)
+    assert len(hitters) == 250 and hitters.attrs["total"] > 250
+    frame(pear.players(2026, side="pitching", conferences=["SEC"], sport="softball"))
+    roster = frame(pear.roster("LSU", 2026), 20)
+    p = pear.player(roster["player_id"].dropna().iloc[0])
+    frame(p["games"])
+
+
+def test_history_and_lookup(pear):
+    frame(pear.history("LSU"), 20)
+    frame(pear.tournament_history())
+    frame(pear.historical_table(), 5000)
+    assert {"kind", "key"} <= set(frame(pear.lookup_fields()).columns)
+    assert 2026 in pear.lookup_options()["seasons"]
+    rows = frame(pear.lookup(2026, conditions=[{"kind": "team", "field": "R", "op": ">=", "value": 25,
+                                                "scope": "either"}]))
+    assert rows.attrs["total"] >= len(rows)
+    frame(pear.lookup(2026, mode="players", team="LSU", limit=10))
+
+
+def test_tournaments(pear):
+    outlook = pear.tournament_outlook()
+    frame(outlook["regionals"], 16)
+    assert pear.simulate_bracket(outlook, seed=1)["regional_winners"]
+    assert pear.simulate_bracket(sport="softball", seed=1)["regional_winners"]
+    assert pear.simulate_bracket(division="d3", seed=1)["regional_winners"]
+    assert pear.simulate_bracket(division="d2", seed=1)["regions"]
+    frame(pear.tournament_outlook(division="d2")["regions"], 8)
+    assert pear.tournament_team("LSU")["team"] == "LSU"
+    frame(pear.tournament_regionals(2026)["games"], 100)
+    frame(pear.conference_tournament_probs("SEC")["teams"])
+    frame(pear.tournament_history(sport="softball"))
+    with pytest.raises(APIError):   # 503 until NAIA's bracket exists
+        pear.tournament_outlook(division="naia")
+
+
+def test_account(pear):
+    assert "plan" in pear.account()