convert floating point stats from string

[louisadamian]

Convert floating stats with decimal representation from str to float with pydantic

adds a BeforeValidator to base.py that converts types to float or returns none and an OptionalFloat type that used the validator and changed all the relevant types in stat objects.

Tests

Passes all unit tests.

[Mattsface]

I've gone ahead and removed the broken workflows and scripts that was causing the CI failure.

Can you pull them down for the PR and run it?

Also thank you for the PR :)

[louisadamian]

Thanks, I merged in your upstream changes, but I can't trigger any workflows.

[louisadamian]

@Mattsface I've rebased on top of 0.8.0 all tests are passing

[Mattsface]

@claude review please

[claude]

Claude finished @Mattsface's task in 2m 20s —— View job

---

Code Review

• Gather context (PR diff, files changed)
• Review mlbstatsapi/models/base.py validator/type changes
• Review stat model changes (catching, fielding, hitting, pitching)
• Review test changes
• Check for downstream code that assumes these fields are strings
• Post review feedback

CI (Offline CI) is passing on this PR. Note: I wasn't able to execute the local test suite myself in this sandbox (bash execution requiring approval was denied), so this review is based on static analysis.

Summary: Solid, low-risk change. The OptionalFloat type (Annotated[float | None, BeforeValidator(float_or_none)] in mlbstatsapi/models/base.py:10-17) is a clean, reusable way to coerce string decimal stats to float, silently falling back to None on unparseable values (empty strings, None, MLB's .---/-.-- placeholders, etc.). Applied consistently across catching.py, fielding.py, hitting.py, and pitching.py. I searched the rest of mlbstatsapi/ for code that treats these fields as strings (formatting, slicing, serialization) and found none — the change is contained to the model layer.

A few things worth addressing:

1. ExpectedStatistics (mlbstatsapi/models/stats/stats.py:35-53) was missed. It has the same "formatted decimal string" semantics (avg, slg, woba, wobacon) as the fields converted elsewhere in this PR, but is still declared as required str. This is inconsistent with the PR's goal, and since the fields are required (not Optional), a missing value in the API response would raise a validation error rather than degrade gracefully like the newly-converted fields do.
   Fix this →

2. README.md example output is now stale. README.md:437-440 shows print(f"Batting Avg: {split.stat.avg}") → Batting Avg: .274. Since SimpleHittingSplit.avg (mlbstatsapi/models/stats/hitting.py:206) is now a float, the real output is Batting Avg: 0.274, not .274. (The other doc example at README.md:487-490 using ExpectedStatistics is unaffected since that class wasn't converted — see point 1.)
   Fix this →

3. Stale docstrings in hitting.py still describe the converted fields as str (e.g. babip : str at line 29, avg : str at line 147, obp/slg/ops etc.), while the equivalent docstrings in pitching.py, catching.py, and fielding.py were already updated to say float. Cosmetic, but worth a pass for consistency.

4. Semantic note (not a blocker): MLB's innings fields (innings_pitched in pitching.py:175, innings in fielding.py:80) use a notation where the digit after the decimal represents thirds of an inning (e.g. "6.2" means 6⅔ innings, not 6.2). This ambiguity pre-dates the PR (it was already a string), but converting to a real float may more strongly invite downstream arithmetic that assumes true decimal semantics. Worth a docstring callout if not already documented elsewhere.

None of these block the PR — 1 and 2 are the most worth fixing before merge since they're small, concrete gaps; 3 and 4 are minor polish.

[louisadamian]

I added the OptionalFoat to the missing variables in ExpectedStatistics and updated the stale docs in hitting.py. Regarding innings_pitched, the .1 for 1/3, .2 for 2/3 is the convention used in the API (baseball reference notes it here https://www.baseball-reference.com/bullpen/Inning). I don't think it makes sense to change the value that is reported for innings pitched here, but let me know if you disagree.

[Mattsface]

@louisadamian this is totally on my radar! I will clone it and take a look ASAP.

[Mattsface]

@louisadamian also yes this is interesting..

"Innings Pitched (IP) measures the length of a pitcher's appearance by outs. If a pitcher gets 1 out it's 0.1 innings (also written 0.3, both meaning 1/3 of an inning), 2 outs is 0.2 innings (also written 0.7) and 0 outs is 0 innings. Until 1982, innings pitched were rounded to the nearest full inning (e.g. 13.2 innings pitched became 14, and 13.1 became 13). This practice caused a controversy in the attribution of the 1981 AL ERA title and was scrapped (see below). The practice had been adopted before the invention of the pocket calculator and the spread of computers and no longer made any sense. Encyclopedias now list full innings pitched, including fractions, for the period before 1982, but older sources of data will often have rounded innings, and as a result pitchers' ERAs will differ slightly."

[Mattsface]

So I discovered that pydantic will actually handle this string to float conversion for us @louisadamian. I'm working on patch to change the the ones referenced in this PR.

I think we should leave that odd return for innings_pitched as a string unless you have any other thoughts.