feat: typed response-model pilot for candle + ticker (#141)#146
Merged
Conversation
Closes #141 Add hint-only TypedDicts (CandleRow/CandleResponse, TickerData/TickerResponse) describing the raw pandas=False JSON of the candle and ticker endpoints, and annotate those two methods' return types with them. Fields sourced from the live API docs; typed as str because numeric values arrive as strings on the wire (missing -> "NaN", coerced only on the pandas=True path). Hint-only: no runtime cost, no validation, no behavior change. Exported from the top level so callers can annotate their own code. Deliberately small pilot; other endpoints can be typed the same way incrementally.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #141
Summary
Pilot for typed response models (the scoped approach we agreed on). Adds hint-only
TypedDicts for thepandas=Falsereturn of the two highest-traffic endpoints and annotates their return types.datamaxi/resources/responses.py:CandleRow/CandleResponse,TickerData/TickerResponse.CexCandle.__call__→Union[pd.DataFrame, CandleResponse];CexTicker.get→Union[pd.DataFrame, TickerResponse].from datamaxi import CandleRow, TickerData, ...) so callers can annotate their own code.Accuracy notes
docs.datamaxiplus.com/rest/cex/{candle,ticker}/data), not guessed — candle:d,o,h,l,c,v; ticker:b,d,e,hb,la,ld,m,p,p24h,pc,q,s,ud,v.str: numeric values arrive as strings on the wire (missing → the literal"NaN", which is why the converter doesdf.replace("NaN", pd.NA)); only thepandas=Truepath coerces to numbers. So the raw dict is faithfullystr-valued.TypedDicthas no runtime cost/validation. Zero behavior change; thepandas=Truedefault still returns aDataFrame.Scope
Deliberately small (2 endpoints) per our discussion — DataFrames are the default interface, so typed models only help the
pandas=Falsepath. Other endpoints can be typed the same way incrementally; a full, drift-proof version would require emitting response schemas from the upstream OpenAPI codegen (bigger, cross-repo).Tests
tests/test_response_models.py(4): assert documented field sets, that apandas=Falsecandle call matches the typed envelope shape at runtime, and thatpandas=Truestill returns aDataFrame.pytest -m "not integration": 149 passed, 11 skipped (145 + 4).Known failures
None.