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.
- {vanda_api-1.1.1 → vanda_api-1.1.2}/CHANGELOG.md +13 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/PKG-INFO +1 -1
- {vanda_api-1.1.1 → vanda_api-1.1.2}/pyproject.toml +1 -1
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/__init__.py +1 -1
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/models.py +9 -3
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_flow.py +63 -8
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_positioning.py +43 -23
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/flow.py +63 -8
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/positioning.py +43 -23
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_flow_client.py +83 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_positioning_client.py +82 -1
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_flow_client.py +110 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_positioning_client.py +74 -1
- {vanda_api-1.1.1 → vanda_api-1.1.2}/.gitignore +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/LICENSE +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/README.md +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/_base/__init__.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/_base/async_base_client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/_base/base_client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/async_auth.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/async_client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/auth.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/errors.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/retry.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/__init__.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/aggregates.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_aggregates.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/async_series.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/services/series.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/__init__.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/dates.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/deprecation.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/io.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/normalize.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/src/vanda/utils/params.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/__init__.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_aggregates_client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_aggregates_client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_async_series_client.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_auth.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_dates.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_normalize.py +0 -0
- {vanda_api-1.1.1 → vanda_api-1.1.2}/tests/test_retry.py +0 -0
- {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.
|
|
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
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
101
|
-
|
|
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
|
|
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
|
|
263
|
-
Address series by "slug" — series_id changes when the pipeline
|
|
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 =
|
|
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
|
-
|
|
60
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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"
|
|
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
|
|
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 =
|
|
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
|
-
|
|
147
|
-
|
|
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 =
|
|
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
|
-
|
|
190
|
-
|
|
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
|
|
101
|
-
|
|
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
|
|
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
|
|
261
|
-
Address series by "slug" — series_id changes when the pipeline
|
|
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 =
|
|
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
|
-
|
|
60
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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"
|
|
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
|
|
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 =
|
|
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
|
-
|
|
147
|
-
|
|
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 =
|
|
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
|
-
|
|
190
|
-
|
|
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
|
|
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
|
|
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
|