vanda-api 1.1.0__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.0 → vanda_api-1.1.2}/CHANGELOG.md +22 -0
  2. {vanda_api-1.1.0 → vanda_api-1.1.2}/PKG-INFO +25 -6
  3. {vanda_api-1.1.0 → vanda_api-1.1.2}/README.md +24 -5
  4. {vanda_api-1.1.0 → vanda_api-1.1.2}/pyproject.toml +1 -1
  5. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/__init__.py +1 -1
  6. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/models.py +9 -3
  7. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_flow.py +92 -13
  8. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_positioning.py +43 -23
  9. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/flow.py +92 -13
  10. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/positioning.py +43 -23
  11. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_flow_client.py +146 -0
  12. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_positioning_client.py +82 -1
  13. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_flow_client.py +168 -0
  14. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_positioning_client.py +74 -1
  15. {vanda_api-1.1.0 → vanda_api-1.1.2}/.gitignore +0 -0
  16. {vanda_api-1.1.0 → vanda_api-1.1.2}/LICENSE +0 -0
  17. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/_base/__init__.py +0 -0
  18. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/_base/async_base_client.py +0 -0
  19. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/_base/base_client.py +0 -0
  20. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/async_auth.py +0 -0
  21. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/async_client.py +0 -0
  22. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/auth.py +0 -0
  23. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/client.py +0 -0
  24. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/errors.py +0 -0
  25. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/retry.py +0 -0
  26. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/__init__.py +0 -0
  27. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/aggregates.py +0 -0
  28. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_aggregates.py +0 -0
  29. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_series.py +0 -0
  30. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/series.py +0 -0
  31. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/__init__.py +0 -0
  32. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/dates.py +0 -0
  33. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/deprecation.py +0 -0
  34. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/io.py +0 -0
  35. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/normalize.py +0 -0
  36. {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/params.py +0 -0
  37. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/__init__.py +0 -0
  38. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_aggregates_client.py +0 -0
  39. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_aggregates_client.py +0 -0
  40. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_series_client.py +0 -0
  41. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_auth.py +0 -0
  42. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_dates.py +0 -0
  43. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_normalize.py +0 -0
  44. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_retry.py +0 -0
  45. {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_series_client.py +0 -0
@@ -5,6 +5,28 @@ 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
+
21
+ ## [1.1.1] - 2026-10-02
22
+
23
+ ### Added
24
+ - `scenarios` on `flow.get_forecast()` - several branches of the cube in one call, as a sequence, a comma-separated string, or `"*"` for every one published. Mutually exclusive with `scenario`, which the SDK refuses before the round trip
25
+ - The response's `scenarios` list is preserved; with several branches the top-level `scenario` is `None` and each group carries its own
26
+
27
+ ### Changed
28
+ - `dimensions` on `flow.get_timeseries()` now documents the service's history-only rule: a forecast series' history is its neutral cell (`{"projection": 0, "zscore": "All"}`), and any other cell is refused with a 400. Read the cube with `get_forecast()`
29
+
8
30
  ## [1.1.0] - 2026-09-23
9
31
 
10
32
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: vanda-api
3
- Version: 1.1.0
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
@@ -408,17 +408,20 @@ complete. That holds as long as *something* resolved - a request where no
408
408
  identifier matches is a 404 and raises `NotFoundError`.
409
409
 
410
410
  Some flow datasets are published as a cube rather than a flat series, with a
411
- value per combination of dimensions. Pass `dimensions` to pin one cell:
411
+ value per combination of dimensions. `get_timeseries()` serves **history only**,
412
+ and a forecast series' history is its neutral cell, so that is the one cell
413
+ `dimensions` will pin here:
412
414
 
413
415
  ```python
414
416
  data = client.flow.get_timeseries(
415
- series_ids=slug, dimensions={"projection": 10, "zscore": "All"}
417
+ series_ids=slug, dimensions={"projection": 0, "zscore": "All"}
416
418
  )
417
419
  ```
418
420
 
419
- It is sent as JSON because the types decide what matches - `projection` is
420
- stored as a number and `zscore` as a string, so `{"projection": "10"}` matches
421
- nothing at all.
421
+ Any other cell is refused with a 400 - read the cube with `get_forecast()`
422
+ instead. It is sent as JSON because the types decide what matches:
423
+ `projection` is stored as a number and `zscore` as a string, so
424
+ `{"projection": "0"}` matches nothing at all.
422
425
 
423
426
  Intraday series (FX options) are capped at 31 days per request. A request with
424
427
  no dates returns the most recent 31 days rather than the full history, a longer
@@ -453,6 +456,22 @@ with VandaClient(token="YOUR_TOKEN_HERE") as client:
453
456
  print(group["horizon"], group["component"], group["metrics"])
454
457
  ```
455
458
 
459
+ Ask for several branches at once with `scenarios` - a sequence, a
460
+ comma-separated string, or `"*"` for every one published:
461
+
462
+ ```python
463
+ whole_run = client.flow.get_forecast(
464
+ series_ids="AUFXFUTUAUDMIXINSSPECTA", scenarios="*", horizons=[5], metrics="px"
465
+ )
466
+ print(whole_run["scenarios"]) # every branch served, in axis order
467
+ print(whole_run["data"][0]["scenario"]) # the branch is now part of the grain
468
+ ```
469
+
470
+ `scenario` and `scenarios` are mutually exclusive. With `scenarios` the
471
+ top-level `scenario` is `None` and each group carries its own instead. A cta run
472
+ is 64 scenarios x 16 horizons, so narrow with `metrics` or `horizons` unless you
473
+ really want the lot.
474
+
456
475
  Rows come back as one group per (series, component, horizon), with every metric
457
476
  nested inside - a forecast is read as a point on a path. Horizon 0 is the run
458
477
  date itself, so on the z-score axis it exists only for the unconditional
@@ -370,17 +370,20 @@ complete. That holds as long as *something* resolved - a request where no
370
370
  identifier matches is a 404 and raises `NotFoundError`.
371
371
 
372
372
  Some flow datasets are published as a cube rather than a flat series, with a
373
- value per combination of dimensions. Pass `dimensions` to pin one cell:
373
+ value per combination of dimensions. `get_timeseries()` serves **history only**,
374
+ and a forecast series' history is its neutral cell, so that is the one cell
375
+ `dimensions` will pin here:
374
376
 
375
377
  ```python
376
378
  data = client.flow.get_timeseries(
377
- series_ids=slug, dimensions={"projection": 10, "zscore": "All"}
379
+ series_ids=slug, dimensions={"projection": 0, "zscore": "All"}
378
380
  )
379
381
  ```
380
382
 
381
- It is sent as JSON because the types decide what matches - `projection` is
382
- stored as a number and `zscore` as a string, so `{"projection": "10"}` matches
383
- nothing at all.
383
+ Any other cell is refused with a 400 - read the cube with `get_forecast()`
384
+ instead. It is sent as JSON because the types decide what matches:
385
+ `projection` is stored as a number and `zscore` as a string, so
386
+ `{"projection": "0"}` matches nothing at all.
384
387
 
385
388
  Intraday series (FX options) are capped at 31 days per request. A request with
386
389
  no dates returns the most recent 31 days rather than the full history, a longer
@@ -415,6 +418,22 @@ with VandaClient(token="YOUR_TOKEN_HERE") as client:
415
418
  print(group["horizon"], group["component"], group["metrics"])
416
419
  ```
417
420
 
421
+ Ask for several branches at once with `scenarios` - a sequence, a
422
+ comma-separated string, or `"*"` for every one published:
423
+
424
+ ```python
425
+ whole_run = client.flow.get_forecast(
426
+ series_ids="AUFXFUTUAUDMIXINSSPECTA", scenarios="*", horizons=[5], metrics="px"
427
+ )
428
+ print(whole_run["scenarios"]) # every branch served, in axis order
429
+ print(whole_run["data"][0]["scenario"]) # the branch is now part of the grain
430
+ ```
431
+
432
+ `scenario` and `scenarios` are mutually exclusive. With `scenarios` the
433
+ top-level `scenario` is `None` and each group carries its own instead. A cta run
434
+ is 64 scenarios x 16 horizons, so narrow with `metrics` or `horizons` unless you
435
+ really want the lot.
436
+
418
437
  Rows come back as one group per (series, component, horizon), with every metric
419
438
  nested inside - a forecast is read as a point on a path. Horizon 0 is the run
420
439
  date itself, so on the z-score axis it exists only for the unconditional
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "vanda-api"
7
- version = "1.1.0"
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.0"
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,14 +30,27 @@ _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 = (
37
50
  "count",
38
51
  "run_date",
39
52
  "scenario",
53
+ "scenarios",
40
54
  "series_labels",
41
55
  "metrics",
42
56
  "unresolved",
@@ -64,6 +78,8 @@ class AsyncFlowAPI:
64
78
  normalisation: Optional[Normalisation] = None,
65
79
  normalisation_period: Optional[NormalisationPeriod] = None,
66
80
  dimensions: Optional[Union[dict[str, Any], str]] = None,
81
+ version: Optional[str] = None,
82
+ revision: Optional[FlowRevision] = None,
67
83
  ) -> dict[str, Any]:
68
84
  """
69
85
  Get flow timeseries data.
@@ -85,21 +101,39 @@ class AsyncFlowAPI:
85
101
  normalisation: "zscore" or "percentile_rank". Requires
86
102
  normalisation_period.
87
103
  normalisation_period: Lookback for the normalisation.
88
- dimensions: Filter to one cell of a dimensioned dataset, as a dict,
89
- e.g. {"projection": 10, "ret": -2}. Sent as JSON because the
90
- types matter: projection is stored as a number and zscore as a
91
- string. A dataset that publishes no dimensions matches nothing.
104
+ dimensions: Pin one cell of a dimensioned dataset, as a dict. Sent
105
+ as JSON because the types matter: projection is stored as a
106
+ number and zscore as a string. This endpoint serves history
107
+ only, and a forecast series' history is its neutral cell, so
108
+ {"projection": 0, "zscore": "All"} (or "ret": 0 for gamma) is
109
+ accepted and changes nothing while any other cell is a 400 -
110
+ read the cube with get_forecast(). A dataset that publishes no
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.
92
121
 
93
122
  Returns:
94
123
  Records under "data", plus count, series, series_ids, metrics,
95
- frequencies, unresolved and pagination. Identifiers that matched
96
- 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.
97
129
  If the transformation service fails, the untransformed rows are
98
130
  returned with "transformation" reporting status "Failure" rather
99
131
  than raising.
100
132
 
101
133
  Raises:
102
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.
103
137
  """
104
138
  params: dict[str, Any] = {
105
139
  "series_ids": csv_param(series_ids),
@@ -116,6 +150,10 @@ class AsyncFlowAPI:
116
150
  params["dimensions"] = (
117
151
  dimensions if isinstance(dimensions, str) else json.dumps(dimensions)
118
152
  )
153
+ if version:
154
+ params["version"] = version
155
+ if revision:
156
+ params["revision"] = revision
119
157
 
120
158
  if start_date:
121
159
  params["start_date"] = format_date(start_date)
@@ -164,6 +202,8 @@ class AsyncFlowAPI:
164
202
  metrics: Optional[Union[str, Sequence[str]]] = None,
165
203
  frequency: Optional[Union[str, Sequence[str]]] = None,
166
204
  as_of: Optional[Union[str, date, datetime]] = None,
205
+ version: Optional[str] = None,
206
+ revision: Optional[FlowRevision] = None,
167
207
  ) -> dict[str, Any]:
168
208
  """
169
209
  Get the latest observation for each series.
@@ -174,10 +214,13 @@ class AsyncFlowAPI:
174
214
  metrics: Metrics to select; omit for all.
175
215
  frequency: Cadences to select; omit for all.
176
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().
177
220
 
178
221
  Returns:
179
- Records under "data", plus count, series_ids, metrics, frequencies
180
- and unresolved.
222
+ Records under "data", plus count, series_ids, metrics, frequencies,
223
+ unresolved, revision, requested_revision and missing_revision.
181
224
  """
182
225
  params: dict[str, Any] = {"series_ids": csv_param(series_ids)}
183
226
 
@@ -187,6 +230,10 @@ class AsyncFlowAPI:
187
230
  params["frequency"] = csv_param(frequency)
188
231
  if as_of:
189
232
  params["as_of"] = format_date(as_of)
233
+ if version:
234
+ params["version"] = version
235
+ if revision:
236
+ params["revision"] = revision
190
237
 
191
238
  data = await self._client._request("GET", "/flow/latest", params=params)
192
239
 
@@ -202,6 +249,8 @@ class AsyncFlowAPI:
202
249
  end_date: Optional[Union[str, date, datetime]] = None,
203
250
  export_format: ExportFormat = "csv",
204
251
  compression: CompressionType = "none",
252
+ version: Optional[str] = None,
253
+ revision: Optional[FlowRevision] = None,
205
254
  ) -> None:
206
255
  """
207
256
  Export flow timeseries to a file.
@@ -216,6 +265,9 @@ class AsyncFlowAPI:
216
265
  end_date: End date (optional).
217
266
  export_format: "csv" or "json".
218
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().
219
271
 
220
272
  Raises:
221
273
  ValidationError: If parameters are invalid.
@@ -226,6 +278,10 @@ class AsyncFlowAPI:
226
278
  "compression": compression,
227
279
  }
228
280
 
281
+ if version:
282
+ params["version"] = version
283
+ if revision:
284
+ params["revision"] = revision
229
285
  if metrics:
230
286
  params["metrics"] = csv_param(metrics)
231
287
  if frequency:
@@ -254,8 +310,11 @@ class AsyncFlowAPI:
254
310
  Search the flow catalog.
255
311
 
256
312
  Entries are keyed by series_label, not by series: each one carries a
257
- "series" list holding the per-series slug, metric, unit and frequency.
258
- 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.
259
318
 
260
319
  Args:
261
320
  q: Free text search.
@@ -294,7 +353,8 @@ class AsyncFlowAPI:
294
353
  A forecast dataset publishes a cube: every combination of a horizon and
295
354
  a scenario, for each run date. This reports the run dates, horizons,
296
355
  components and scenario tokens, so `get_forecast()` can be called with
297
- 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.
298
358
 
299
359
  Args:
300
360
  series_ids: Slugs (preferred), series labels, entities or series ids,
@@ -325,6 +385,7 @@ class AsyncFlowAPI:
325
385
  run_date: Optional[Union[str, date, datetime]] = None,
326
386
  horizons: Optional[Union[int, str, Sequence[Union[int, str]]]] = None,
327
387
  scenario: Optional[Union[str, int, float]] = None,
388
+ scenarios: Optional[Union[str, Sequence[Union[str, int, float]]]] = None,
328
389
  components: Optional[Union[str, Sequence[str]]] = None,
329
390
  records_per_page: int = 2000,
330
391
  page_number: int = 1,
@@ -344,6 +405,10 @@ class AsyncFlowAPI:
344
405
  component - "zscore" for cta, rp and vt, "ret" for gamma - so
345
406
  read scenario_key from get_forecast_runs() first. On the z-score
346
407
  axis the domain mixes "All", "<0" and ">0" with numbers.
408
+ scenarios: Several branches at once, as a sequence or a
409
+ comma-separated string, or "*" for every one published - a whole
410
+ run in one call. Mutually exclusive with scenario. A cta run is
411
+ 64 scenarios x 16 horizons, so narrow with metrics or horizons.
347
412
  components: Systematic strategies to select, e.g. "cta,vt"; omit for
348
413
  all. Each publishes its own metrics, so a group never mixes them.
349
414
  records_per_page: Records per page (1-10000).
@@ -352,7 +417,13 @@ class AsyncFlowAPI:
352
417
  Returns:
353
418
  One group per (series, component, horizon) under "data", each
354
419
  holding every metric for that point, plus run_date, scenario,
355
- series_labels, metrics, unresolved, count and pagination.
420
+ scenarios, series_labels, metrics, unresolved, count and pagination.
421
+ With scenarios, the branch is part of the grain: every group carries
422
+ its own "scenario", the top-level "scenario" is None, and
423
+ "scenarios" lists what was served.
424
+
425
+ Raises:
426
+ ValidationError: If both scenario and scenarios are given.
356
427
 
357
428
  Note:
358
429
  Horizon 0 is the run date itself, so on the z-score axis it exists
@@ -373,12 +444,20 @@ class AsyncFlowAPI:
373
444
  if run_date:
374
445
  params["run_date"] = format_date(run_date)
375
446
 
447
+ if scenario is not None and scenarios is not None:
448
+ raise ValidationError("pass either scenario or scenarios, not both")
449
+
376
450
  # Horizon 0 and scenario 0 are real values, so test against None.
377
451
  if horizons is not None:
378
452
  values = horizons if isinstance(horizons, (str, Sequence)) else [horizons]
379
453
  params["horizons"] = csv_param(values)
380
454
  if scenario is not None:
381
455
  params["scenario"] = str(scenario)
456
+ if scenarios is not None:
457
+ # csv_param stringifies a sequence but passes a string through; mapping
458
+ # str() ourselves would iterate a string one character at a time.
459
+ branches = scenarios if isinstance(scenarios, (str, Sequence)) else [scenarios]
460
+ params["scenarios"] = csv_param(branches)
382
461
 
383
462
  data = await self._client._request("GET", "/flow/forecast", params=params)
384
463
 
@@ -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