vanda-api 1.1.1__tar.gz → 1.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. {vanda_api-1.1.1 → vanda_api-1.1.2}/CHANGELOG.md +13 -0
  2. {vanda_api-1.1.1 → vanda_api-1.1.2}/PKG-INFO +1 -1
  3. {vanda_api-1.1.1 → vanda_api-1.1.2}/pyproject.toml +1 -1
  4. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/__init__.py +1 -1
  5. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/models.py +9 -3
  6. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_flow.py +63 -8
  7. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_positioning.py +43 -23
  8. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/flow.py +63 -8
  9. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/positioning.py +43 -23
  10. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_flow_client.py +83 -0
  11. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_positioning_client.py +82 -1
  12. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_flow_client.py +110 -0
  13. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_positioning_client.py +74 -1
  14. {vanda_api-1.1.1 → vanda_api-1.1.2}/.gitignore +0 -0
  15. {vanda_api-1.1.1 → vanda_api-1.1.2}/LICENSE +0 -0
  16. {vanda_api-1.1.1 → vanda_api-1.1.2}/README.md +0 -0
  17. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/_base/__init__.py +0 -0
  18. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/_base/async_base_client.py +0 -0
  19. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/_base/base_client.py +0 -0
  20. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/async_auth.py +0 -0
  21. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/async_client.py +0 -0
  22. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/auth.py +0 -0
  23. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/client.py +0 -0
  24. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/errors.py +0 -0
  25. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/retry.py +0 -0
  26. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/__init__.py +0 -0
  27. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/aggregates.py +0 -0
  28. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_aggregates.py +0 -0
  29. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_series.py +0 -0
  30. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/series.py +0 -0
  31. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/__init__.py +0 -0
  32. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/dates.py +0 -0
  33. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/deprecation.py +0 -0
  34. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/io.py +0 -0
  35. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/normalize.py +0 -0
  36. {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/params.py +0 -0
  37. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/__init__.py +0 -0
  38. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_aggregates_client.py +0 -0
  39. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_aggregates_client.py +0 -0
  40. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_series_client.py +0 -0
  41. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_auth.py +0 -0
  42. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_dates.py +0 -0
  43. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_normalize.py +0 -0
  44. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_retry.py +0 -0
  45. {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_series_client.py +0 -0
@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.1.2] - 2026-11-13
9
+
10
+ ### Added
11
+ - `version` and `revision` on `flow.get_timeseries()`, `flow.get_latest()` and `flow.export_timeseries()`, sent only when set. `revision` takes `"prefer_restated"` (the service default), `"restated"` or `"point_in_time"`; the strict values leave out series without that revision, and none having it raises `NotFoundError`. An unknown `version` also raises `NotFoundError`
12
+ - Flow responses keep the envelope's `revision`, `requested_revision` and `missing_revision`
13
+ - `FlowRevision` and `PositioningMetric` types
14
+ - Windows `"2"`, `"3"`, `"4"`, `"6"`, `"12"`, `"13"`, `"26"` and `"52"`, for weekly, bi-weekly and monthly series
15
+
16
+ ### Changed
17
+ - `metric` on positioning's `get_timeseries()`, `get_latest()` and `export_timeseries()` is optional and no longer sent by default, so the service serves each series' headline metric. Pass it to pin one; an unknown metric raises `VandaError` (HTTP 400) naming the valid ones
18
+ - Positioning docs follow the service's raw default: omit `normalisation` for stored values (`"none"` means the same), `normalisation` alone runs over `"All"`, and `normalisation_period` alone means `"zscore"`
19
+ - Docs: windows count observations, not days; positioning `revision` is strict; flow `list_catalog()` describes `versions`, `revisions`, `lag` and `update_time`
20
+
8
21
  ## [1.1.1] - 2026-10-02
9
22
 
10
23
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: vanda-api
3
- Version: 1.1.1
3
+ Version: 1.1.2
4
4
  Summary: Official Python SDK for Vanda Analytics Data API
5
5
  Project-URL: Homepage, https://gitlab.com/yourusername/vanda-api
6
6
  Project-URL: Documentation, https://gitlab.com/yourusername/vanda-api#readme
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "vanda-api"
7
- version = "1.1.1"
7
+ version = "1.1.2"
8
8
  description = "Official Python SDK for Vanda Analytics Data API"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -10,7 +10,7 @@ from vanda.errors import (
10
10
  VandaError,
11
11
  )
12
12
 
13
- __version__ = "1.1.1"
13
+ __version__ = "1.1.2"
14
14
 
15
15
  __all__ = [
16
16
  "VandaClient",
@@ -52,11 +52,17 @@ CompressionType = Literal["none", "gzip", "zip"]
52
52
  StreamFormat = Literal["ndjson", "csv"]
53
53
 
54
54
  Revision = Literal["restated", "point_in_time"]
55
- PositioningMetric = Literal["combined_positioning"]
55
+ # Flow alone has a default that picks per series: restated where it exists, else point in time.
56
+ FlowRevision = Literal["prefer_restated", "restated", "point_in_time"]
57
+ # Catalog-driven: /positioning/catalog/facets?dimensions=metric lists the valid values.
58
+ PositioningMetric = str
56
59
  SortOrder = Literal["asc", "desc"]
57
60
  Transformation = Literal["rolling_sum", "moving_avg"]
58
- Window = Literal["5", "20", "30", "60", "90", "120", "252"]
61
+ # In observations, not days: the trailing values suit weekly, bi-weekly and monthly series.
62
+ Window = Literal[
63
+ "5", "20", "30", "60", "90", "120", "252", "2", "3", "4", "6", "12", "13", "26", "52"
64
+ ]
59
65
  Normalisation = Literal["zscore", "percentile_rank"]
60
- # Positioning normalises by default, so it alone needs a value that opts out.
66
+ # Positioning still accepts "none", now the same as omitting normalisation.
61
67
  PositioningNormalisation = Literal["zscore", "percentile_rank", "none"]
62
68
  NormalisationPeriod = Literal["3m", "6m", "1y", "2y", "5y", "Expanding", "All"]
@@ -8,6 +8,7 @@ from vanda.errors import ValidationError, VandaError
8
8
  from vanda.models import (
9
9
  CompressionType,
10
10
  ExportFormat,
11
+ FlowRevision,
11
12
  Normalisation,
12
13
  NormalisationPeriod,
13
14
  SortOrder,
@@ -29,8 +30,20 @@ _TIMESERIES_KEYS = (
29
30
  "frequencies",
30
31
  "unresolved",
31
32
  "pagination",
33
+ "revision",
34
+ "requested_revision",
35
+ "missing_revision",
36
+ )
37
+ _LATEST_KEYS = (
38
+ "count",
39
+ "series_ids",
40
+ "metrics",
41
+ "frequencies",
42
+ "unresolved",
43
+ "revision",
44
+ "requested_revision",
45
+ "missing_revision",
32
46
  )
33
- _LATEST_KEYS = ("count", "series_ids", "metrics", "frequencies", "unresolved")
34
47
  _CATALOG_KEYS = ("count", "pagination")
35
48
  _FORECAST_RUNS_KEYS = ("count", "unresolved", "pagination")
36
49
  _FORECAST_KEYS = (
@@ -65,6 +78,8 @@ class AsyncFlowAPI:
65
78
  normalisation: Optional[Normalisation] = None,
66
79
  normalisation_period: Optional[NormalisationPeriod] = None,
67
80
  dimensions: Optional[Union[dict[str, Any], str]] = None,
81
+ version: Optional[str] = None,
82
+ revision: Optional[FlowRevision] = None,
68
83
  ) -> dict[str, Any]:
69
84
  """
70
85
  Get flow timeseries data.
@@ -94,17 +109,31 @@ class AsyncFlowAPI:
94
109
  accepted and changes nothing while any other cell is a 400 -
95
110
  read the cube with get_forecast(). A dataset that publishes no
96
111
  dimensions matches nothing.
112
+ version: Model version, e.g. "V2" ("2" and "v2" also work). Selects
113
+ series, not rows. Omit it and each label serves the newest
114
+ version of every metric it publishes.
115
+ revision: "prefer_restated" (the service default when omitted),
116
+ "restated" or "point_in_time". The default serves each series
117
+ restated where it has restated rows, else point in time. The
118
+ other two are strict: a series without that revision is left
119
+ out and listed in "missing_revision". Point in time never falls
120
+ back to restated, so a backtest cannot see later revisions.
97
121
 
98
122
  Returns:
99
123
  Records under "data", plus count, series, series_ids, metrics,
100
- frequencies, unresolved and pagination. Identifiers that matched
101
- nothing are listed in "unresolved" rather than failing the request.
124
+ frequencies, unresolved, pagination, revision, requested_revision
125
+ and missing_revision. Each record carries its own "revision"; the
126
+ top-level "revision" is None when the series served differ.
127
+ Identifiers that matched nothing are listed in "unresolved" rather
128
+ than failing the request.
102
129
  If the transformation service fails, the untransformed rows are
103
130
  returned with "transformation" reporting status "Failure" rather
104
131
  than raising.
105
132
 
106
133
  Raises:
107
134
  ValidationError: If parameters are invalid.
135
+ NotFoundError: If a metric or version matches no series, or a
136
+ strict revision leaves nothing to serve.
108
137
  """
109
138
  params: dict[str, Any] = {
110
139
  "series_ids": csv_param(series_ids),
@@ -121,6 +150,10 @@ class AsyncFlowAPI:
121
150
  params["dimensions"] = (
122
151
  dimensions if isinstance(dimensions, str) else json.dumps(dimensions)
123
152
  )
153
+ if version:
154
+ params["version"] = version
155
+ if revision:
156
+ params["revision"] = revision
124
157
 
125
158
  if start_date:
126
159
  params["start_date"] = format_date(start_date)
@@ -169,6 +202,8 @@ class AsyncFlowAPI:
169
202
  metrics: Optional[Union[str, Sequence[str]]] = None,
170
203
  frequency: Optional[Union[str, Sequence[str]]] = None,
171
204
  as_of: Optional[Union[str, date, datetime]] = None,
205
+ version: Optional[str] = None,
206
+ revision: Optional[FlowRevision] = None,
172
207
  ) -> dict[str, Any]:
173
208
  """
174
209
  Get the latest observation for each series.
@@ -179,10 +214,13 @@ class AsyncFlowAPI:
179
214
  metrics: Metrics to select; omit for all.
180
215
  frequency: Cadences to select; omit for all.
181
216
  as_of: Return the latest observation on or before this date.
217
+ version: Model version, as for get_timeseries().
218
+ revision: "prefer_restated" (default), "restated" or
219
+ "point_in_time", as for get_timeseries().
182
220
 
183
221
  Returns:
184
- Records under "data", plus count, series_ids, metrics, frequencies
185
- and unresolved.
222
+ Records under "data", plus count, series_ids, metrics, frequencies,
223
+ unresolved, revision, requested_revision and missing_revision.
186
224
  """
187
225
  params: dict[str, Any] = {"series_ids": csv_param(series_ids)}
188
226
 
@@ -192,6 +230,10 @@ class AsyncFlowAPI:
192
230
  params["frequency"] = csv_param(frequency)
193
231
  if as_of:
194
232
  params["as_of"] = format_date(as_of)
233
+ if version:
234
+ params["version"] = version
235
+ if revision:
236
+ params["revision"] = revision
195
237
 
196
238
  data = await self._client._request("GET", "/flow/latest", params=params)
197
239
 
@@ -207,6 +249,8 @@ class AsyncFlowAPI:
207
249
  end_date: Optional[Union[str, date, datetime]] = None,
208
250
  export_format: ExportFormat = "csv",
209
251
  compression: CompressionType = "none",
252
+ version: Optional[str] = None,
253
+ revision: Optional[FlowRevision] = None,
210
254
  ) -> None:
211
255
  """
212
256
  Export flow timeseries to a file.
@@ -221,6 +265,9 @@ class AsyncFlowAPI:
221
265
  end_date: End date (optional).
222
266
  export_format: "csv" or "json".
223
267
  compression: "none", "gzip", or "zip".
268
+ version: Model version, as for get_timeseries().
269
+ revision: "prefer_restated" (default), "restated" or
270
+ "point_in_time", as for get_timeseries().
224
271
 
225
272
  Raises:
226
273
  ValidationError: If parameters are invalid.
@@ -231,6 +278,10 @@ class AsyncFlowAPI:
231
278
  "compression": compression,
232
279
  }
233
280
 
281
+ if version:
282
+ params["version"] = version
283
+ if revision:
284
+ params["revision"] = revision
234
285
  if metrics:
235
286
  params["metrics"] = csv_param(metrics)
236
287
  if frequency:
@@ -259,8 +310,11 @@ class AsyncFlowAPI:
259
310
  Search the flow catalog.
260
311
 
261
312
  Entries are keyed by series_label, not by series: each one carries a
262
- "series" list holding the per-series slug, metric, unit and frequency.
263
- Address series by "slug" — series_id changes when the pipeline reloads.
313
+ "series" list holding the per-series slug, metric, unit, frequency and
314
+ version. Address series by "slug" — series_id changes when the pipeline
315
+ reloads. Each entry's identity lists its "versions" and the "revisions"
316
+ it publishes, plus "lag" (days) and "update_time" (time of day) from the
317
+ series library.
264
318
 
265
319
  Args:
266
320
  q: Free text search.
@@ -299,7 +353,8 @@ class AsyncFlowAPI:
299
353
  A forecast dataset publishes a cube: every combination of a horizon and
300
354
  a scenario, for each run date. This reports the run dates, horizons,
301
355
  components and scenario tokens, so `get_forecast()` can be called with
302
- values the series actually publishes.
356
+ values the series actually publishes. Horizons, components and scenarios
357
+ come from each series' newest run; run_dates lists every run.
303
358
 
304
359
  Args:
305
360
  series_ids: Slugs (preferred), series labels, entities or series ids,
@@ -38,7 +38,7 @@ class AsyncPositioningAPI:
38
38
  start_date: Optional[Union[str, date, datetime]] = None,
39
39
  end_date: Optional[Union[str, date, datetime]] = None,
40
40
  revision: Revision = "restated",
41
- metric: PositioningMetric = "combined_positioning",
41
+ metric: Optional[PositioningMetric] = None,
42
42
  version: Optional[str] = None,
43
43
  order: SortOrder = "desc",
44
44
  records_per_page: int = 2000,
@@ -55,23 +55,31 @@ class AsyncPositioningAPI:
55
55
  series_ids: Series identifiers or labels, comma separated or as a sequence.
56
56
  start_date: Start date (YYYY-MM-DD or date object).
57
57
  end_date: End date (YYYY-MM-DD or date object).
58
- revision: "restated" or "point_in_time".
59
- metric: Measure to return.
60
- version: Model version.
58
+ revision: "restated" or "point_in_time". Strict: a series with no
59
+ rows of that revision raises NotFoundError.
60
+ metric: Measure to return; valid values are listed by
61
+ list_catalog() and the service's metric facet. Omit for each
62
+ series' headline: its version's "combined_positioning", or
63
+ "combined_score_published" where that version has none (rates V2).
64
+ An unknown metric raises VandaError (HTTP 400) naming the valid ones.
65
+ version: Model version, e.g. "V1". Omit for the latest.
61
66
  order: "asc" or "desc" by timestamp.
62
67
  records_per_page: Records per page (1-10000).
63
68
  page_number: Page number, 1-indexed.
64
69
  transformation: "rolling_sum" or "moving_avg". Requires window.
65
- window: Transformation window in observations.
66
- normalisation: "zscore", "percentile_rank" or "none". The service
67
- normalises with "zscore" over "All" when omitted; pass "none"
68
- for raw values.
69
- normalisation_period: Calendar lookback for the normalisation.
70
+ window: Transformation window in observations, not days - "20" is
71
+ 20 weeks on a weekly series.
72
+ normalisation: "zscore" or "percentile_rank"; omit for raw values.
73
+ "none" is still accepted and means the same as omitting it.
74
+ Sent alone, normalisation runs over "All" history.
75
+ normalisation_period: Calendar lookback for the normalisation. Sent
76
+ alone, it normalises with "zscore".
70
77
 
71
78
  Returns:
72
79
  Records under "data", plus count, metric, revision, series_ids,
73
80
  version and pagination. Transformed and normalised values arrive
74
- under "transformation"; "data" is always the raw stored series.
81
+ under "transformation", present only when one was asked for; "data"
82
+ is always the raw stored series.
75
83
  If the transformation service fails, the untransformed rows are
76
84
  returned with "transformation" reporting status "Failure" rather
77
85
  than raising. Asking for more than one series skips the
@@ -83,7 +91,6 @@ class AsyncPositioningAPI:
83
91
  params: dict[str, Any] = {
84
92
  "series_ids": csv_param(series_ids),
85
93
  "revision": revision,
86
- "metric": metric,
87
94
  "order": order,
88
95
  "records_per_page": records_per_page,
89
96
  "page_number": page_number,
@@ -96,6 +103,8 @@ class AsyncPositioningAPI:
96
103
  if start_date and end_date:
97
104
  validate_date_range(params["start_date"], params["end_date"])
98
105
 
106
+ if metric:
107
+ params["metric"] = metric
99
108
  if version:
100
109
  params["version"] = version
101
110
 
@@ -107,8 +116,7 @@ class AsyncPositioningAPI:
107
116
  if transformation:
108
117
  params.update({"transformation": transformation, "window": window})
109
118
 
110
- # Positioning defaults both server-side and pairs them itself, so unlike
111
- # flow either one may be sent alone.
119
+ # Positioning pairs these itself, so unlike flow either one may be sent alone.
112
120
  if normalisation:
113
121
  params["normalisation"] = normalisation
114
122
  if normalisation_period:
@@ -133,7 +141,7 @@ class AsyncPositioningAPI:
133
141
  self,
134
142
  series_ids: Union[str, Sequence[str]],
135
143
  revision: Revision = "restated",
136
- metric: PositioningMetric = "combined_positioning",
144
+ metric: Optional[PositioningMetric] = None,
137
145
  version: Optional[str] = None,
138
146
  as_of: Optional[Union[str, date, datetime]] = None,
139
147
  ) -> dict[str, Any]:
@@ -142,9 +150,14 @@ class AsyncPositioningAPI:
142
150
 
143
151
  Args:
144
152
  series_ids: Series identifiers or labels, comma separated or as a sequence.
145
- revision: "restated" or "point_in_time".
146
- metric: Measure to return.
147
- version: Model version.
153
+ revision: "restated" or "point_in_time". Strict: a series with no
154
+ rows of that revision raises NotFoundError.
155
+ metric: Measure to return; valid values are listed by
156
+ list_catalog() and the service's metric facet. Omit for each
157
+ series' headline: its version's "combined_positioning", or
158
+ "combined_score_published" where that version has none (rates V2).
159
+ An unknown metric raises VandaError (HTTP 400) naming the valid ones.
160
+ version: Model version, e.g. "V1". Omit for the latest.
148
161
  as_of: Return the latest reading on or before this date.
149
162
 
150
163
  Returns:
@@ -153,9 +166,10 @@ class AsyncPositioningAPI:
153
166
  params: dict[str, Any] = {
154
167
  "series_ids": csv_param(series_ids),
155
168
  "revision": revision,
156
- "metric": metric,
157
169
  }
158
170
 
171
+ if metric:
172
+ params["metric"] = metric
159
173
  if version:
160
174
  params["version"] = version
161
175
  if as_of:
@@ -172,7 +186,7 @@ class AsyncPositioningAPI:
172
186
  start_date: Optional[Union[str, date, datetime]] = None,
173
187
  end_date: Optional[Union[str, date, datetime]] = None,
174
188
  revision: Revision = "restated",
175
- metric: PositioningMetric = "combined_positioning",
189
+ metric: Optional[PositioningMetric] = None,
176
190
  version: Optional[str] = None,
177
191
  export_format: ExportFormat = "csv",
178
192
  compression: CompressionType = "none",
@@ -185,9 +199,14 @@ class AsyncPositioningAPI:
185
199
  output_path: Output file path.
186
200
  start_date: Start date (optional).
187
201
  end_date: End date (optional).
188
- revision: "restated" or "point_in_time".
189
- metric: Measure to return.
190
- version: Model version.
202
+ revision: "restated" or "point_in_time". Strict: a series with no
203
+ rows of that revision raises NotFoundError.
204
+ metric: Measure to return; valid values are listed by
205
+ list_catalog() and the service's metric facet. Omit for each
206
+ series' headline: its version's "combined_positioning", or
207
+ "combined_score_published" where that version has none (rates V2).
208
+ An unknown metric raises VandaError (HTTP 400) naming the valid ones.
209
+ version: Model version, e.g. "V1". Omit for the latest.
191
210
  export_format: "csv" or "json".
192
211
  compression: "none", "gzip", or "zip".
193
212
 
@@ -197,7 +216,6 @@ class AsyncPositioningAPI:
197
216
  params: dict[str, Any] = {
198
217
  "series_ids": csv_param(series_ids),
199
218
  "revision": revision,
200
- "metric": metric,
201
219
  "export_format": export_format,
202
220
  "compression": compression,
203
221
  }
@@ -209,6 +227,8 @@ class AsyncPositioningAPI:
209
227
  if start_date and end_date:
210
228
  validate_date_range(params["start_date"], params["end_date"])
211
229
 
230
+ if metric:
231
+ params["metric"] = metric
212
232
  if version:
213
233
  params["version"] = version
214
234
 
@@ -8,6 +8,7 @@ from vanda.errors import ValidationError, VandaError
8
8
  from vanda.models import (
9
9
  CompressionType,
10
10
  ExportFormat,
11
+ FlowRevision,
11
12
  Normalisation,
12
13
  NormalisationPeriod,
13
14
  SortOrder,
@@ -29,8 +30,20 @@ _TIMESERIES_KEYS = (
29
30
  "frequencies",
30
31
  "unresolved",
31
32
  "pagination",
33
+ "revision",
34
+ "requested_revision",
35
+ "missing_revision",
36
+ )
37
+ _LATEST_KEYS = (
38
+ "count",
39
+ "series_ids",
40
+ "metrics",
41
+ "frequencies",
42
+ "unresolved",
43
+ "revision",
44
+ "requested_revision",
45
+ "missing_revision",
32
46
  )
33
- _LATEST_KEYS = ("count", "series_ids", "metrics", "frequencies", "unresolved")
34
47
  _CATALOG_KEYS = ("count", "pagination")
35
48
  _FORECAST_RUNS_KEYS = ("count", "unresolved", "pagination")
36
49
  _FORECAST_KEYS = (
@@ -65,6 +78,8 @@ class FlowAPI:
65
78
  normalisation: Optional[Normalisation] = None,
66
79
  normalisation_period: Optional[NormalisationPeriod] = None,
67
80
  dimensions: Optional[Union[dict[str, Any], str]] = None,
81
+ version: Optional[str] = None,
82
+ revision: Optional[FlowRevision] = None,
68
83
  ) -> dict[str, Any]:
69
84
  """
70
85
  Get flow timeseries data.
@@ -94,17 +109,31 @@ class FlowAPI:
94
109
  accepted and changes nothing while any other cell is a 400 -
95
110
  read the cube with get_forecast(). A dataset that publishes no
96
111
  dimensions matches nothing.
112
+ version: Model version, e.g. "V2" ("2" and "v2" also work). Selects
113
+ series, not rows. Omit it and each label serves the newest
114
+ version of every metric it publishes.
115
+ revision: "prefer_restated" (the service default when omitted),
116
+ "restated" or "point_in_time". The default serves each series
117
+ restated where it has restated rows, else point in time. The
118
+ other two are strict: a series without that revision is left
119
+ out and listed in "missing_revision". Point in time never falls
120
+ back to restated, so a backtest cannot see later revisions.
97
121
 
98
122
  Returns:
99
123
  Records under "data", plus count, series, series_ids, metrics,
100
- frequencies, unresolved and pagination. Identifiers that matched
101
- nothing are listed in "unresolved" rather than failing the request.
124
+ frequencies, unresolved, pagination, revision, requested_revision
125
+ and missing_revision. Each record carries its own "revision"; the
126
+ top-level "revision" is None when the series served differ.
127
+ Identifiers that matched nothing are listed in "unresolved" rather
128
+ than failing the request.
102
129
  If the transformation service fails, the untransformed rows are
103
130
  returned with "transformation" reporting status "Failure" rather
104
131
  than raising.
105
132
 
106
133
  Raises:
107
134
  ValidationError: If parameters are invalid.
135
+ NotFoundError: If a metric or version matches no series, or a
136
+ strict revision leaves nothing to serve.
108
137
  """
109
138
  params: dict[str, Any] = {
110
139
  "series_ids": csv_param(series_ids),
@@ -121,6 +150,10 @@ class FlowAPI:
121
150
  params["dimensions"] = (
122
151
  dimensions if isinstance(dimensions, str) else json.dumps(dimensions)
123
152
  )
153
+ if version:
154
+ params["version"] = version
155
+ if revision:
156
+ params["revision"] = revision
124
157
 
125
158
  if start_date:
126
159
  params["start_date"] = format_date(start_date)
@@ -169,6 +202,8 @@ class FlowAPI:
169
202
  metrics: Optional[Union[str, Sequence[str]]] = None,
170
203
  frequency: Optional[Union[str, Sequence[str]]] = None,
171
204
  as_of: Optional[Union[str, date, datetime]] = None,
205
+ version: Optional[str] = None,
206
+ revision: Optional[FlowRevision] = None,
172
207
  ) -> dict[str, Any]:
173
208
  """
174
209
  Get the latest observation for each series.
@@ -179,10 +214,13 @@ class FlowAPI:
179
214
  metrics: Metrics to select; omit for all.
180
215
  frequency: Cadences to select; omit for all.
181
216
  as_of: Return the latest observation on or before this date.
217
+ version: Model version, as for get_timeseries().
218
+ revision: "prefer_restated" (default), "restated" or
219
+ "point_in_time", as for get_timeseries().
182
220
 
183
221
  Returns:
184
- Records under "data", plus count, series_ids, metrics, frequencies
185
- and unresolved.
222
+ Records under "data", plus count, series_ids, metrics, frequencies,
223
+ unresolved, revision, requested_revision and missing_revision.
186
224
  """
187
225
  params: dict[str, Any] = {"series_ids": csv_param(series_ids)}
188
226
 
@@ -192,6 +230,10 @@ class FlowAPI:
192
230
  params["frequency"] = csv_param(frequency)
193
231
  if as_of:
194
232
  params["as_of"] = format_date(as_of)
233
+ if version:
234
+ params["version"] = version
235
+ if revision:
236
+ params["revision"] = revision
195
237
 
196
238
  data = self._client._request("GET", "/flow/latest", params=params)
197
239
 
@@ -207,6 +249,8 @@ class FlowAPI:
207
249
  end_date: Optional[Union[str, date, datetime]] = None,
208
250
  export_format: ExportFormat = "csv",
209
251
  compression: CompressionType = "none",
252
+ version: Optional[str] = None,
253
+ revision: Optional[FlowRevision] = None,
210
254
  ) -> None:
211
255
  """
212
256
  Export flow timeseries to a file.
@@ -221,6 +265,9 @@ class FlowAPI:
221
265
  end_date: End date (optional).
222
266
  export_format: "csv" or "json".
223
267
  compression: "none", "gzip", or "zip".
268
+ version: Model version, as for get_timeseries().
269
+ revision: "prefer_restated" (default), "restated" or
270
+ "point_in_time", as for get_timeseries().
224
271
 
225
272
  Raises:
226
273
  ValidationError: If parameters are invalid.
@@ -231,6 +278,10 @@ class FlowAPI:
231
278
  "compression": compression,
232
279
  }
233
280
 
281
+ if version:
282
+ params["version"] = version
283
+ if revision:
284
+ params["revision"] = revision
234
285
  if metrics:
235
286
  params["metrics"] = csv_param(metrics)
236
287
  if frequency:
@@ -257,8 +308,11 @@ class FlowAPI:
257
308
  Search the flow catalog.
258
309
 
259
310
  Entries are keyed by series_label, not by series: each one carries a
260
- "series" list holding the per-series slug, metric, unit and frequency.
261
- Address series by "slug" — series_id changes when the pipeline reloads.
311
+ "series" list holding the per-series slug, metric, unit, frequency and
312
+ version. Address series by "slug" — series_id changes when the pipeline
313
+ reloads. Each entry's identity lists its "versions" and the "revisions"
314
+ it publishes, plus "lag" (days) and "update_time" (time of day) from the
315
+ series library.
262
316
 
263
317
  Args:
264
318
  q: Free text search.
@@ -297,7 +351,8 @@ class FlowAPI:
297
351
  A forecast dataset publishes a cube: every combination of a horizon and
298
352
  a scenario, for each run date. This reports the run dates, horizons,
299
353
  components and scenario tokens, so `get_forecast()` can be called with
300
- values the series actually publishes.
354
+ values the series actually publishes. Horizons, components and scenarios
355
+ come from each series' newest run; run_dates lists every run.
301
356
 
302
357
  Args:
303
358
  series_ids: Slugs (preferred), series labels, entities or series ids,
@@ -38,7 +38,7 @@ class PositioningAPI:
38
38
  start_date: Optional[Union[str, date, datetime]] = None,
39
39
  end_date: Optional[Union[str, date, datetime]] = None,
40
40
  revision: Revision = "restated",
41
- metric: PositioningMetric = "combined_positioning",
41
+ metric: Optional[PositioningMetric] = None,
42
42
  version: Optional[str] = None,
43
43
  order: SortOrder = "desc",
44
44
  records_per_page: int = 2000,
@@ -55,23 +55,31 @@ class PositioningAPI:
55
55
  series_ids: Series identifiers or labels, comma separated or as a sequence.
56
56
  start_date: Start date (YYYY-MM-DD or date object).
57
57
  end_date: End date (YYYY-MM-DD or date object).
58
- revision: "restated" or "point_in_time".
59
- metric: Measure to return.
60
- version: Model version.
58
+ revision: "restated" or "point_in_time". Strict: a series with no
59
+ rows of that revision raises NotFoundError.
60
+ metric: Measure to return; valid values are listed by
61
+ list_catalog() and the service's metric facet. Omit for each
62
+ series' headline: its version's "combined_positioning", or
63
+ "combined_score_published" where that version has none (rates V2).
64
+ An unknown metric raises VandaError (HTTP 400) naming the valid ones.
65
+ version: Model version, e.g. "V1". Omit for the latest.
61
66
  order: "asc" or "desc" by timestamp.
62
67
  records_per_page: Records per page (1-10000).
63
68
  page_number: Page number, 1-indexed.
64
69
  transformation: "rolling_sum" or "moving_avg". Requires window.
65
- window: Transformation window in observations.
66
- normalisation: "zscore", "percentile_rank" or "none". The service
67
- normalises with "zscore" over "All" when omitted; pass "none"
68
- for raw values.
69
- normalisation_period: Calendar lookback for the normalisation.
70
+ window: Transformation window in observations, not days - "20" is
71
+ 20 weeks on a weekly series.
72
+ normalisation: "zscore" or "percentile_rank"; omit for raw values.
73
+ "none" is still accepted and means the same as omitting it.
74
+ Sent alone, normalisation runs over "All" history.
75
+ normalisation_period: Calendar lookback for the normalisation. Sent
76
+ alone, it normalises with "zscore".
70
77
 
71
78
  Returns:
72
79
  Records under "data", plus count, metric, revision, series_ids,
73
80
  version and pagination. Transformed and normalised values arrive
74
- under "transformation"; "data" is always the raw stored series.
81
+ under "transformation", present only when one was asked for; "data"
82
+ is always the raw stored series.
75
83
  If the transformation service fails, the untransformed rows are
76
84
  returned with "transformation" reporting status "Failure" rather
77
85
  than raising. Asking for more than one series skips the
@@ -83,7 +91,6 @@ class PositioningAPI:
83
91
  params: dict[str, Any] = {
84
92
  "series_ids": csv_param(series_ids),
85
93
  "revision": revision,
86
- "metric": metric,
87
94
  "order": order,
88
95
  "records_per_page": records_per_page,
89
96
  "page_number": page_number,
@@ -96,6 +103,8 @@ class PositioningAPI:
96
103
  if start_date and end_date:
97
104
  validate_date_range(params["start_date"], params["end_date"])
98
105
 
106
+ if metric:
107
+ params["metric"] = metric
99
108
  if version:
100
109
  params["version"] = version
101
110
 
@@ -107,8 +116,7 @@ class PositioningAPI:
107
116
  if transformation:
108
117
  params.update({"transformation": transformation, "window": window})
109
118
 
110
- # Positioning defaults both server-side and pairs them itself, so unlike
111
- # flow either one may be sent alone.
119
+ # Positioning pairs these itself, so unlike flow either one may be sent alone.
112
120
  if normalisation:
113
121
  params["normalisation"] = normalisation
114
122
  if normalisation_period:
@@ -133,7 +141,7 @@ class PositioningAPI:
133
141
  self,
134
142
  series_ids: Union[str, Sequence[str]],
135
143
  revision: Revision = "restated",
136
- metric: PositioningMetric = "combined_positioning",
144
+ metric: Optional[PositioningMetric] = None,
137
145
  version: Optional[str] = None,
138
146
  as_of: Optional[Union[str, date, datetime]] = None,
139
147
  ) -> dict[str, Any]:
@@ -142,9 +150,14 @@ class PositioningAPI:
142
150
 
143
151
  Args:
144
152
  series_ids: Series identifiers or labels, comma separated or as a sequence.
145
- revision: "restated" or "point_in_time".
146
- metric: Measure to return.
147
- version: Model version.
153
+ revision: "restated" or "point_in_time". Strict: a series with no
154
+ rows of that revision raises NotFoundError.
155
+ metric: Measure to return; valid values are listed by
156
+ list_catalog() and the service's metric facet. Omit for each
157
+ series' headline: its version's "combined_positioning", or
158
+ "combined_score_published" where that version has none (rates V2).
159
+ An unknown metric raises VandaError (HTTP 400) naming the valid ones.
160
+ version: Model version, e.g. "V1". Omit for the latest.
148
161
  as_of: Return the latest reading on or before this date.
149
162
 
150
163
  Returns:
@@ -153,9 +166,10 @@ class PositioningAPI:
153
166
  params: dict[str, Any] = {
154
167
  "series_ids": csv_param(series_ids),
155
168
  "revision": revision,
156
- "metric": metric,
157
169
  }
158
170
 
171
+ if metric:
172
+ params["metric"] = metric
159
173
  if version:
160
174
  params["version"] = version
161
175
  if as_of:
@@ -172,7 +186,7 @@ class PositioningAPI:
172
186
  start_date: Optional[Union[str, date, datetime]] = None,
173
187
  end_date: Optional[Union[str, date, datetime]] = None,
174
188
  revision: Revision = "restated",
175
- metric: PositioningMetric = "combined_positioning",
189
+ metric: Optional[PositioningMetric] = None,
176
190
  version: Optional[str] = None,
177
191
  export_format: ExportFormat = "csv",
178
192
  compression: CompressionType = "none",
@@ -185,9 +199,14 @@ class PositioningAPI:
185
199
  output_path: Output file path.
186
200
  start_date: Start date (optional).
187
201
  end_date: End date (optional).
188
- revision: "restated" or "point_in_time".
189
- metric: Measure to return.
190
- version: Model version.
202
+ revision: "restated" or "point_in_time". Strict: a series with no
203
+ rows of that revision raises NotFoundError.
204
+ metric: Measure to return; valid values are listed by
205
+ list_catalog() and the service's metric facet. Omit for each
206
+ series' headline: its version's "combined_positioning", or
207
+ "combined_score_published" where that version has none (rates V2).
208
+ An unknown metric raises VandaError (HTTP 400) naming the valid ones.
209
+ version: Model version, e.g. "V1". Omit for the latest.
191
210
  export_format: "csv" or "json".
192
211
  compression: "none", "gzip", or "zip".
193
212
 
@@ -197,7 +216,6 @@ class PositioningAPI:
197
216
  params: dict[str, Any] = {
198
217
  "series_ids": csv_param(series_ids),
199
218
  "revision": revision,
200
- "metric": metric,
201
219
  "export_format": export_format,
202
220
  "compression": compression,
203
221
  }
@@ -209,6 +227,8 @@ class PositioningAPI:
209
227
  if start_date and end_date:
210
228
  validate_date_range(params["start_date"], params["end_date"])
211
229
 
230
+ if metric:
231
+ params["metric"] = metric
212
232
  if version:
213
233
  params["version"] = version
214
234
 
@@ -486,3 +486,86 @@ async def test_get_forecast_sends_a_scenarios_string_unchanged(client: AsyncVand
486
486
  await client.flow.get_forecast(SLUG, scenarios="All,-1.0,1.0")
487
487
 
488
488
  assert route.calls[0].request.url.params["scenarios"] == "All,-1.0,1.0"
489
+
490
+
491
+ @respx.mock
492
+ @pytest.mark.asyncio
493
+ async def test_get_timeseries_sends_version_and_revision(client: AsyncVandaClient) -> None:
494
+ """version and revision are forwarded and the revision envelope kept."""
495
+ payload = _timeseries_payload()
496
+ payload.update(
497
+ {"revision": "point_in_time", "requested_revision": "point_in_time", "missing_revision": []}
498
+ )
499
+ route = respx.get(f"{BASE_URL}/flow/timeseries").mock(
500
+ return_value=httpx.Response(200, json=payload)
501
+ )
502
+
503
+ result = await client.flow.get_timeseries(SLUG, version="V2", revision="point_in_time")
504
+
505
+ params = route.calls[0].request.url.params
506
+ assert params["version"] == "V2"
507
+ assert params["revision"] == "point_in_time"
508
+ assert result["requested_revision"] == "point_in_time"
509
+ assert result["missing_revision"] == []
510
+
511
+
512
+ @respx.mock
513
+ @pytest.mark.asyncio
514
+ async def test_get_timeseries_omits_version_and_revision_by_default(
515
+ client: AsyncVandaClient,
516
+ ) -> None:
517
+ """Omitted, the service picks the newest version and prefer_restated."""
518
+ route = respx.get(f"{BASE_URL}/flow/timeseries").mock(
519
+ return_value=httpx.Response(200, json=_timeseries_payload())
520
+ )
521
+
522
+ await client.flow.get_timeseries(SLUG)
523
+
524
+ params = route.calls[0].request.url.params
525
+ assert "version" not in params
526
+ assert "revision" not in params
527
+
528
+
529
+ @respx.mock
530
+ @pytest.mark.asyncio
531
+ async def test_get_latest_sends_version_and_revision(client: AsyncVandaClient) -> None:
532
+ """Latest forwards version and revision and keeps the revision envelope."""
533
+ route = respx.get(f"{BASE_URL}/flow/latest").mock(
534
+ return_value=httpx.Response(
535
+ 200,
536
+ json={
537
+ "data": [{"series_id": 1, "slug": SLUG, "value": 1.0, "revision": None}],
538
+ "count": 1,
539
+ "revision": None,
540
+ "requested_revision": "prefer_restated",
541
+ "missing_revision": [],
542
+ },
543
+ )
544
+ )
545
+
546
+ result = await client.flow.get_latest(SLUG, version="V1", revision="prefer_restated")
547
+
548
+ params = route.calls[0].request.url.params
549
+ assert params["version"] == "V1"
550
+ assert params["revision"] == "prefer_restated"
551
+ assert result["revision"] is None
552
+ assert result["requested_revision"] == "prefer_restated"
553
+
554
+
555
+ @respx.mock
556
+ @pytest.mark.asyncio
557
+ async def test_export_timeseries_sends_version_and_revision(
558
+ client: AsyncVandaClient, tmp_path
559
+ ) -> None:
560
+ """Export forwards version and revision."""
561
+ route = respx.get(f"{BASE_URL}/flow/timeseries/export").mock(
562
+ return_value=httpx.Response(200, content=b"ts,series_id,metric,value\n")
563
+ )
564
+
565
+ await client.flow.export_timeseries(
566
+ SLUG, output_path=str(tmp_path / "flow.csv"), version="V1", revision="restated"
567
+ )
568
+
569
+ params = route.calls[0].request.url.params
570
+ assert params["version"] == "V1"
571
+ assert params["revision"] == "restated"
@@ -2,7 +2,7 @@ import httpx
2
2
  import pytest
3
3
  import respx
4
4
 
5
- from vanda import AsyncVandaClient, AuthError, ServerError, ValidationError
5
+ from vanda import AsyncVandaClient, AuthError, ServerError, ValidationError, VandaError
6
6
 
7
7
  BASE_URL = "https://api.test.com"
8
8
 
@@ -267,3 +267,84 @@ async def test_auth_error(client: AsyncVandaClient) -> None:
267
267
 
268
268
  with pytest.raises(AuthError):
269
269
  await client.positioning.get_timeseries("BREQCOMB-ALL")
270
+
271
+
272
+ @respx.mock
273
+ @pytest.mark.asyncio
274
+ async def test_get_timeseries_omits_metric_and_normalisation_by_default(
275
+ client: AsyncVandaClient,
276
+ ) -> None:
277
+ """Omitted, the service serves each series' headline metric, raw."""
278
+ route = respx.get(f"{BASE_URL}/positioning/timeseries").mock(
279
+ return_value=httpx.Response(200, json=_timeseries_payload())
280
+ )
281
+
282
+ result = await client.positioning.get_timeseries("USFICOMB-10YR")
283
+
284
+ params = route.calls[0].request.url.params
285
+ assert "metric" not in params
286
+ assert "normalisation" not in params
287
+ assert "normalisation_period" not in params
288
+ assert params["revision"] == "restated"
289
+ assert "transformation" not in result
290
+
291
+
292
+ @respx.mock
293
+ @pytest.mark.asyncio
294
+ async def test_get_timeseries_sends_a_named_metric(client: AsyncVandaClient) -> None:
295
+ """A metric is any catalog value, not only combined_positioning."""
296
+ route = respx.get(f"{BASE_URL}/positioning/timeseries").mock(
297
+ return_value=httpx.Response(200, json=_timeseries_payload())
298
+ )
299
+
300
+ await client.positioning.get_timeseries(
301
+ "USFICOMB-10YR", metric="spec_score", version="V1", transformation="moving_avg", window="13"
302
+ )
303
+
304
+ params = route.calls[0].request.url.params
305
+ assert params["metric"] == "spec_score"
306
+ assert params["version"] == "V1"
307
+ assert params["window"] == "13"
308
+
309
+
310
+ @respx.mock
311
+ @pytest.mark.asyncio
312
+ async def test_get_latest_and_export_omit_metric_by_default(
313
+ client: AsyncVandaClient, tmp_path
314
+ ) -> None:
315
+ """Latest and export leave the metric to the service unless named."""
316
+ latest = respx.get(f"{BASE_URL}/positioning/latest").mock(
317
+ return_value=httpx.Response(200, json={"data": [], "count": 0})
318
+ )
319
+ export = respx.get(f"{BASE_URL}/positioning/timeseries/export").mock(
320
+ return_value=httpx.Response(200, content=b"ts,series_id,value\n")
321
+ )
322
+
323
+ await client.positioning.get_latest("USFICOMB-10YR")
324
+ await client.positioning.export_timeseries(
325
+ "USFICOMB-10YR", output_path=str(tmp_path / "p.csv"), metric="combined_positioning"
326
+ )
327
+
328
+ assert "metric" not in latest.calls[0].request.url.params
329
+ assert export.calls[0].request.url.params["metric"] == "combined_positioning"
330
+
331
+
332
+ @respx.mock
333
+ @pytest.mark.asyncio
334
+ async def test_unknown_metric_raises_with_the_valid_ones(client: AsyncVandaClient) -> None:
335
+ """The service's 400 surfaces as a VandaError carrying its body."""
336
+ respx.get(f"{BASE_URL}/positioning/timeseries").mock(
337
+ return_value=httpx.Response(
338
+ 400,
339
+ json={
340
+ "error": "Unknown metric: nope. Available: combined_positioning, spec_score",
341
+ "details": {"metric": "nope", "available": ["combined_positioning", "spec_score"]},
342
+ },
343
+ )
344
+ )
345
+
346
+ with pytest.raises(VandaError) as exc:
347
+ await client.positioning.get_timeseries("USFICOMB-10YR", metric="nope")
348
+
349
+ assert exc.value.status_code == 400
350
+ assert exc.value.response_body["details"]["available"] == ["combined_positioning", "spec_score"]
@@ -479,3 +479,113 @@ def test_get_forecast_preserves_the_scenarios_list(client: VandaClient) -> None:
479
479
  assert result["scenarios"] == ["-1.0", "1.0", "All"]
480
480
  assert result["scenario"] is None
481
481
  assert result["data"][0]["scenario"] == "-1.0"
482
+
483
+
484
+ def _revision_envelope(revision, requested="prefer_restated", missing=None) -> dict:
485
+ return {
486
+ "revision": revision,
487
+ "requested_revision": requested,
488
+ "missing_revision": missing or [],
489
+ }
490
+
491
+
492
+ @respx.mock
493
+ def test_get_timeseries_sends_version_and_revision(client: VandaClient) -> None:
494
+ """version and revision are forwarded as given."""
495
+ route = respx.get(f"{BASE_URL}/flow/timeseries").mock(
496
+ return_value=httpx.Response(
497
+ 200,
498
+ json={**_timeseries_payload(), **_revision_envelope("point_in_time", "point_in_time")},
499
+ )
500
+ )
501
+
502
+ client.flow.get_timeseries(SLUG, version="V2", revision="point_in_time")
503
+
504
+ params = route.calls[0].request.url.params
505
+ assert params["version"] == "V2"
506
+ assert params["revision"] == "point_in_time"
507
+
508
+
509
+ @respx.mock
510
+ def test_get_timeseries_omits_version_and_revision_by_default(client: VandaClient) -> None:
511
+ """Omitted, the service picks the newest version and prefer_restated."""
512
+ route = respx.get(f"{BASE_URL}/flow/timeseries").mock(
513
+ return_value=httpx.Response(200, json=_timeseries_payload())
514
+ )
515
+
516
+ client.flow.get_timeseries(SLUG)
517
+
518
+ params = route.calls[0].request.url.params
519
+ assert "version" not in params
520
+ assert "revision" not in params
521
+
522
+
523
+ @respx.mock
524
+ def test_get_timeseries_preserves_the_revision_envelope(client: VandaClient) -> None:
525
+ """A mixed response reports revision None, and each row keeps its own."""
526
+ payload = _timeseries_payload()
527
+ payload["data"][0]["revision"] = "restated"
528
+ payload.update(_revision_envelope(None, "restated", ["FLOW.US.FI.CTA.V1:X:CTA_SCORE:Y"]))
529
+ respx.get(f"{BASE_URL}/flow/timeseries").mock(return_value=httpx.Response(200, json=payload))
530
+
531
+ result = client.flow.get_timeseries(SLUG, revision="restated")
532
+
533
+ assert result["revision"] is None
534
+ assert result["requested_revision"] == "restated"
535
+ assert result["missing_revision"] == ["FLOW.US.FI.CTA.V1:X:CTA_SCORE:Y"]
536
+ assert result["data"][0]["revision"] == "restated"
537
+
538
+
539
+ @respx.mock
540
+ def test_get_latest_sends_version_and_revision(client: VandaClient) -> None:
541
+ """Latest forwards version and revision and keeps the revision envelope."""
542
+ route = respx.get(f"{BASE_URL}/flow/latest").mock(
543
+ return_value=httpx.Response(
544
+ 200,
545
+ json={
546
+ "data": [{"series_id": 1, "slug": SLUG, "value": 1.0, "revision": "restated"}],
547
+ "count": 1,
548
+ "series_ids": [1],
549
+ "metrics": ["net"],
550
+ "frequencies": ["daily"],
551
+ "unresolved": [],
552
+ **_revision_envelope("restated", "restated"),
553
+ },
554
+ )
555
+ )
556
+
557
+ result = client.flow.get_latest(SLUG, version="1", revision="restated")
558
+
559
+ params = route.calls[0].request.url.params
560
+ assert params["version"] == "1"
561
+ assert params["revision"] == "restated"
562
+ assert result["revision"] == "restated"
563
+ assert result["missing_revision"] == []
564
+
565
+
566
+ @respx.mock
567
+ def test_export_timeseries_sends_version_and_revision(client: VandaClient, tmp_path) -> None:
568
+ """Export forwards version and revision."""
569
+ route = respx.get(f"{BASE_URL}/flow/timeseries/export").mock(
570
+ return_value=httpx.Response(200, content=b"ts,series_id,metric,value\n")
571
+ )
572
+
573
+ client.flow.export_timeseries(
574
+ SLUG, output_path=str(tmp_path / "flow.csv"), version="V1", revision="point_in_time"
575
+ )
576
+
577
+ params = route.calls[0].request.url.params
578
+ assert params["version"] == "V1"
579
+ assert params["revision"] == "point_in_time"
580
+
581
+
582
+ @respx.mock
583
+ def test_get_timeseries_accepts_a_cadence_window(client: VandaClient) -> None:
584
+ """The weekly/monthly windows are sent like the daily ones."""
585
+ route = respx.get(f"{BASE_URL}/flow/timeseries").mock(
586
+ return_value=httpx.Response(200, json=_timeseries_payload())
587
+ )
588
+
589
+ client.flow.get_timeseries(SLUG, transformation="moving_avg", window="13")
590
+
591
+ assert route.calls[0].request.url.params["window"] == "13"
@@ -2,7 +2,7 @@ import httpx
2
2
  import pytest
3
3
  import respx
4
4
 
5
- from vanda import AuthError, ServerError, ValidationError, VandaClient
5
+ from vanda import AuthError, ServerError, ValidationError, VandaClient, VandaError
6
6
 
7
7
  BASE_URL = "https://api.test.com"
8
8
 
@@ -255,3 +255,76 @@ def test_auth_error(client: VandaClient) -> None:
255
255
 
256
256
  with pytest.raises(AuthError):
257
257
  client.positioning.get_timeseries("BREQCOMB-ALL")
258
+
259
+
260
+ @respx.mock
261
+ def test_get_timeseries_omits_metric_and_normalisation_by_default(client: VandaClient) -> None:
262
+ """Omitted, the service serves each series' headline metric, raw."""
263
+ route = respx.get(f"{BASE_URL}/positioning/timeseries").mock(
264
+ return_value=httpx.Response(200, json=_timeseries_payload())
265
+ )
266
+
267
+ result = client.positioning.get_timeseries("USFICOMB-10YR")
268
+
269
+ params = route.calls[0].request.url.params
270
+ assert "metric" not in params
271
+ assert "normalisation" not in params
272
+ assert "normalisation_period" not in params
273
+ assert params["revision"] == "restated"
274
+ assert "transformation" not in result
275
+
276
+
277
+ @respx.mock
278
+ def test_get_timeseries_sends_a_named_metric(client: VandaClient) -> None:
279
+ """A metric is any catalog value, not only combined_positioning."""
280
+ route = respx.get(f"{BASE_URL}/positioning/timeseries").mock(
281
+ return_value=httpx.Response(200, json=_timeseries_payload())
282
+ )
283
+
284
+ client.positioning.get_timeseries(
285
+ "USFICOMB-10YR", metric="spec_score", version="V1", transformation="moving_avg", window="13"
286
+ )
287
+
288
+ params = route.calls[0].request.url.params
289
+ assert params["metric"] == "spec_score"
290
+ assert params["version"] == "V1"
291
+ assert params["window"] == "13"
292
+
293
+
294
+ @respx.mock
295
+ def test_get_latest_and_export_omit_metric_by_default(client: VandaClient, tmp_path) -> None:
296
+ """Latest and export leave the metric to the service unless named."""
297
+ latest = respx.get(f"{BASE_URL}/positioning/latest").mock(
298
+ return_value=httpx.Response(200, json={"data": [], "count": 0})
299
+ )
300
+ export = respx.get(f"{BASE_URL}/positioning/timeseries/export").mock(
301
+ return_value=httpx.Response(200, content=b"ts,series_id,value\n")
302
+ )
303
+
304
+ client.positioning.get_latest("USFICOMB-10YR")
305
+ client.positioning.export_timeseries(
306
+ "USFICOMB-10YR", output_path=str(tmp_path / "p.csv"), metric="combined_positioning"
307
+ )
308
+
309
+ assert "metric" not in latest.calls[0].request.url.params
310
+ assert export.calls[0].request.url.params["metric"] == "combined_positioning"
311
+
312
+
313
+ @respx.mock
314
+ def test_unknown_metric_raises_with_the_valid_ones(client: VandaClient) -> None:
315
+ """The service's 400 surfaces as a VandaError carrying its body."""
316
+ respx.get(f"{BASE_URL}/positioning/timeseries").mock(
317
+ return_value=httpx.Response(
318
+ 400,
319
+ json={
320
+ "error": "Unknown metric: nope. Available: combined_positioning, spec_score",
321
+ "details": {"metric": "nope", "available": ["combined_positioning", "spec_score"]},
322
+ },
323
+ )
324
+ )
325
+
326
+ with pytest.raises(VandaError) as exc:
327
+ client.positioning.get_timeseries("USFICOMB-10YR", metric="nope")
328
+
329
+ assert exc.value.status_code == 400
330
+ assert exc.value.response_body["details"]["available"] == ["combined_positioning", "spec_score"]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes