Skip to content

Commit 094b4fc

Browse files
cjdsellerscjdsellers
committed
MOD: Standardize and clarify date parameters
1 parent 7ff95bc commit 094b4fc

File tree

13 files changed

+119
-69
lines changed

13 files changed

+119
-69
lines changed

‎databento/common/bento.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -402,8 +402,8 @@ def symbology(self) -> Dict[str, Any]:
402402
"symbols": self.symbols,
403403
"stype_in": self.stype_in.value,
404404
"stype_out": self.stype_out.value,
405-
"from_date": str(self.start.date()),
406-
"to_date": str(self.end.date()),
405+
"start_date": str(self.start.date()),
406+
"end_date": str(self.end.date()),
407407
"partial": self._metadata["partial"],
408408
"not_found": self._metadata["not_found"],
409409
"message": message,

‎databento/common/parsing.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,28 @@ def maybe_symbols_list_to_string(
9595
raise TypeError(f"invalid symbols type, was {type(symbols)}")
9696

9797

98+
def maybe_date_to_string(
99+
value: Optional[Union[date, str]],
100+
) -> Optional[str]:
101+
"""
102+
Return a valid date string from the given value (if not None).
103+
104+
Parameters
105+
----------
106+
value : date or str, optional
107+
The value to parse.
108+
109+
Returns
110+
-------
111+
str or ``None``
112+
113+
"""
114+
if value is None:
115+
return None
116+
117+
return str(pd.to_datetime(value).date())
118+
119+
98120
def maybe_datetime_to_string(
99121
value: Optional[Union[pd.Timestamp, date, str]],
100122
) -> Optional[str]:

‎databento/historical/api/batch.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,12 @@ def timeseries_submit(
5858
schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, default 'trades' # noqa
5959
The data record schema for the request.
6060
start : pd.Timestamp or date or str or int, optional
61-
The UTC start of the time range (inclusive) for the request.
61+
The start datetime of the request time range (inclusive).
62+
Assumes UTC as timezone unless passed a tz-aware object.
6263
If using an integer then this represents nanoseconds since UNIX epoch.
6364
end : pd.Timestamp or date or str or int, optional
64-
The UTC end of the time range (exclusive) for the request.
65+
The end datetime of the request time range (exclusive).
66+
Assumes UTC as timezone unless passed a tz-aware object.
6567
If using an integer then this represents nanoseconds since UNIX epoch.
6668
encoding : Encoding or str {'dbz', 'csv', 'json'}, default 'dbz'
6769
The data encoding.

‎databento/historical/api/metadata.py‎

Lines changed: 33 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
from databento.common.enums import Dataset, Encoding, FeedMode, Schema, SType
66
from databento.common.parsing import (
77
enum_or_str_lowercase,
8+
maybe_date_to_string,
89
maybe_datetime_to_string,
910
maybe_enum_or_str_lowercase,
1011
maybe_symbols_list_to_string,
@@ -26,8 +27,8 @@ def __init__(self, key, gateway):
2627

2728
def list_datasets(
2829
self,
29-
start: Optional[Union[pd.Timestamp, date, str, int]] = None,
30-
end: Optional[Union[pd.Timestamp, date, str, int]] = None,
30+
start_date: Optional[Union[date, str]] = None,
31+
end_date: Optional[Union[date, str]] = None,
3132
) -> List[str]:
3233
"""
3334
List all datasets available from Databento.
@@ -36,12 +37,10 @@ def list_datasets(
3637
3738
Parameters
3839
----------
39-
start : pd.Timestamp or date or str or int, optional
40-
The UTC start datetime for the request range.
41-
If using an integer then this represents nanoseconds since UNIX epoch.
42-
end : pd.Timestamp or date or str or int, optional
43-
The UTC end datetime for the request range.
44-
If using an integer then this represents nanoseconds since UNIX epoch.
40+
start_date : date or str, optional
41+
The start date (UTC) for the request range.
42+
end_date : date or str, optional
43+
The end date (UTC) for the request range.
4544
4645
Returns
4746
-------
@@ -59,12 +58,12 @@ def list_datasets(
5958
other methods which take the `dataset` parameter.
6059
6160
"""
62-
start = maybe_datetime_to_string(start)
63-
end = maybe_datetime_to_string(end)
61+
start_date = maybe_date_to_string(start_date)
62+
end_date = maybe_date_to_string(end_date)
6463

6564
params: List[Tuple[str, str]] = [
66-
("start", start),
67-
("end", end),
65+
("start_date", start_date),
66+
("end_date", end_date),
6867
]
6968

7069
response: Response = self._get(
@@ -77,8 +76,8 @@ def list_datasets(
7776
def list_schemas(
7877
self,
7978
dataset: Union[Dataset, str],
80-
start: Optional[Union[pd.Timestamp, date, str, int]] = None,
81-
end: Optional[Union[pd.Timestamp, date, str, int]] = None,
79+
start_date: Optional[Union[date, str]] = None,
80+
end_date: Optional[Union[date, str]] = None,
8281
) -> List[str]:
8382
"""
8483
List all data schemas available from Databento.
@@ -89,26 +88,24 @@ def list_schemas(
8988
----------
9089
dataset : Dataset or str
9190
The dataset name for the request.
92-
start : pd.Timestamp or date or str or int, optional
93-
The start datetime for the request range (UTC).
94-
If using an integer then this represents nanoseconds since UNIX epoch.
95-
end : pd.Timestamp or date or str or int, optional
96-
The end datetime for the request range (UTC).
97-
If using an integer then this represents nanoseconds since UNIX epoch.
91+
start_date : date or str, optional
92+
The start date (UTC) for the request range.
93+
end_date : date or str, optional
94+
The end date (UTC) for the request range.
9895
9996
Returns
10097
-------
10198
List[str]
10299
103100
"""
104101
dataset = enum_or_str_lowercase(dataset, "dataset")
105-
start = maybe_datetime_to_string(start)
106-
end = maybe_datetime_to_string(end)
102+
start_date = maybe_date_to_string(start_date)
103+
end_date = maybe_date_to_string(end_date)
107104

108105
params: List[Tuple[str, str]] = [
109106
("dataset", dataset),
110-
("start", start),
111-
("end", end),
107+
("start_date", start_date),
108+
("end_date", end_date),
112109
]
113110

114111
response: Response = self._get(
@@ -272,10 +269,12 @@ def get_shape(
272269
schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, default 'trades' # noqa
273270
The data record schema for the request.
274271
start : pd.Timestamp or date or str or int, optional
275-
The start datetime for the request range (UTC).
272+
The start datetime for the request range.
273+
Assumes UTC as timezone unless passed a tz-aware object.
276274
If using an integer then this represents nanoseconds since UNIX epoch.
277275
end : pd.Timestamp or date or str or int, optional
278-
The end datetime for the request range (UTC).
276+
The end datetime for the request range.
277+
Assumes UTC as timezone unless passed a tz-aware object.
279278
If using an integer then this represents nanoseconds since UNIX epoch.
280279
encoding : Encoding or str {'dbz', 'csv', 'json'}, optional
281280
The data encoding.
@@ -347,10 +346,12 @@ def get_billable_size(
347346
schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, default 'trades' # noqa
348347
The data record schema for the request.
349348
start : pd.Timestamp or date or str or int, optional
350-
The start datetime for the request range (UTC).
349+
The start datetime for the request range.
350+
Assumes UTC as timezone unless passed a tz-aware object.
351351
If using an integer then this represents nanoseconds since UNIX epoch.
352352
end : pd.Timestamp or date or str or int, optional
353-
The end datetime for the request range (UTC).
353+
The end datetime for the request range.
354+
Assumes UTC as timezone unless passed a tz-aware object.
354355
If using an integer then this represents nanoseconds since UNIX epoch.
355356
stype_in : SType or str, default 'native'
356357
The input symbol type to resolve from.
@@ -414,10 +415,12 @@ def get_cost(
414415
schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, default 'trades' # noqa
415416
The data record schema for the request.
416417
start : pd.Timestamp or date or str or int, optional
417-
The start datetime for the request range (UTC).
418+
The start datetime for the request range.
419+
Assumes UTC as timezone unless passed a tz-aware object.
418420
If using an integer then this represents nanoseconds since UNIX epoch.
419421
end : pd.Timestamp or date or str or int, optional
420-
The end datetime for the request range (UTC).
422+
The end datetime for the request range.
423+
Assumes UTC as timezone unless passed a tz-aware object.
421424
If using an integer then this represents nanoseconds since UNIX epoch.
422425
stype_in : SType or str, default 'native'
423426
The input symbol type to resolve from.

‎databento/historical/api/symbology.py‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ def resolve(
2424
symbols: Union[List[str], str],
2525
stype_in: Union[SType, str],
2626
stype_out: Union[SType, str],
27-
start: Union[date, str],
28-
end: Union[date, str],
27+
start_date: Union[date, str],
28+
end_date: Union[date, str],
2929
default_value: Optional[str] = "",
3030
):
3131
"""
@@ -43,12 +43,10 @@ def resolve(
4343
The input symbol type to resolve from.
4444
stype_out : SType or str, default 'product_id'
4545
The output symbol type to resolve to.
46-
start : pd.Timestamp or date or str or int
47-
The UTC start of the time range (inclusive) to resolve.
48-
If using an integer then this represents nanoseconds since UNIX epoch.
49-
end : pd.Timestamp or date or str or int
50-
The UTC end of the time range (exclusive) to resolve.
51-
If using an integer then this represents nanoseconds since UNIX epoch.
46+
start_date : date or str
47+
The start date (UTC) of the request time range (inclusive).
48+
end_date : date or str
49+
The end date (UTC) of the request time range (exclusive).
5250
default_value : str, default '' (empty string)
5351
The default value to return if a symbol cannot be resolved.
5452
@@ -62,16 +60,16 @@ def resolve(
6260
symbols = maybe_symbols_list_to_string(symbols)
6361
stype_in = enum_or_str_lowercase(stype_in, "stype_in")
6462
stype_out = enum_or_str_lowercase(stype_out, "stype_out")
65-
start = str(pd.to_datetime(start).date())
66-
end = str(pd.to_datetime(end).date())
63+
start_date = str(pd.to_datetime(start_date).date())
64+
end_date = str(pd.to_datetime(end_date).date())
6765

6866
params: List[Tuple[str, str]] = [
6967
("dataset", dataset),
7068
("symbols", symbols),
7169
("stype_in", stype_in),
7270
("stype_out", stype_out),
73-
("start", start),
74-
("end", end),
71+
("start_date", start_date),
72+
("end_date", end_date),
7573
("default_value", default_value),
7674
]
7775

‎databento/historical/api/timeseries.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -50,10 +50,10 @@ def stream(
5050
schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, default 'trades' # noqa
5151
The data record schema for the request.
5252
start : pd.Timestamp or date or str or int, optional
53-
The UTC start of the time range (inclusive) for the request.
53+
The start datetime (UTC) of the request time range (inclusive).
5454
If using an integer then this represents nanoseconds since UNIX epoch.
5555
end : pd.Timestamp or date or str or int, optional
56-
The UTC end of the time range (exclusive) for the request.
56+
The end datetime (UTC) of the request time range (exclusive).
5757
If using an integer then this represents nanoseconds since UNIX epoch.
5858
stype_in : SType or str, default 'native'
5959
The input symbol type to resolve from.
@@ -143,15 +143,15 @@ async def stream_async(
143143
schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, default 'trades' # noqa
144144
The data record schema for the request.
145145
start : pd.Timestamp or date or str or int, optional
146-
The UTC start of the time range (inclusive) for the request.
146+
The start datetime (UTC) of the request time range (inclusive).
147147
If using an integer then this represents nanoseconds since UNIX epoch.
148148
end : pd.Timestamp or date or str or int, optional
149-
The UTC end of the time range (exclusive) for the request.
149+
The end datetime (UTC) of the request time range (exclusive).
150150
If using an integer then this represents nanoseconds since UNIX epoch.
151151
stype_in : SType or str, default 'native'
152-
The input symbol type to resolve from.
152+
The input symbology type to resolve from.
153153
stype_out : SType or str, default 'product_id'
154-
The output symbol type to resolve to.
154+
The output symbology type to resolve to.
155155
limit : int, optional
156156
The maximum number of records to return.
157157
path : str, optional

‎databento/historical/client.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,8 @@ def request_symbology(self, data: Bento) -> Dict[str, Dict[str, Any]]:
106106
symbols=data.symbols,
107107
stype_in=data.stype_in,
108108
stype_out=data.stype_out,
109-
start=data.start,
110-
end=data.end,
109+
start_date=data.start.date(),
110+
end_date=data.end.date(),
111111
)
112112

113113
def request_full_definitions(

‎examples/historical_symbology_resolve.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@
1515
symbols=["ESH1"],
1616
stype_in=SType.NATIVE,
1717
stype_out=SType.PRODUCT_ID,
18-
start="2020-12-27",
19-
end="2020-12-29",
18+
start_date="2020-12-27",
19+
end_date="2020-12-29",
2020
)
2121

2222
pprint(response)

‎notebooks/quickstart.ipynb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -690,8 +690,8 @@
690690
" 'symbols': ['ES.FUT'],\n",
691691
" 'stype_in': 'smart',\n",
692692
" 'stype_out': 'product_id',\n",
693-
" 'from_date': '2020-12-27',\n",
694-
" 'to_date': '2020-12-30',\n",
693+
" 'start_date': '2020-12-27',\n",
694+
" 'end_date': '2020-12-30',\n",
695695
" 'partial': [],\n",
696696
" 'not_found': [],\n",
697697
" 'message': 'OK',\n",

‎tests/test_common_parsing.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
from databento.common.enums import Dataset, Flags
66
from databento.common.parsing import (
77
enum_or_str_lowercase,
8+
maybe_date_to_string,
89
maybe_datetime_to_string,
910
maybe_enum_or_str_lowercase,
1011
maybe_symbols_list_to_string,
@@ -88,6 +89,27 @@ def test_maybe_symbols_list_to_string_given_valid_inputs_returns_expected(
8889
# Assert
8990
assert result == expected
9091

92+
@pytest.mark.parametrize(
93+
"value, expected",
94+
[
95+
[None, None],
96+
[1604782791000000000, "2020-11-07"],
97+
["2020-11-07T20:59:51", "2020-11-07"],
98+
[date(2020, 12, 28), "2020-12-28"],
99+
[pd.Timestamp("2020-12-28T23:12:01.123"), "2020-12-28"],
100+
],
101+
)
102+
def test_maybe_date_to_string_give_valid_values_returns_expected_results(
103+
self,
104+
value,
105+
expected,
106+
) -> None:
107+
# Arrange, Act
108+
result = maybe_date_to_string(value)
109+
110+
# Assert
111+
assert result == expected
112+
91113
@pytest.mark.parametrize(
92114
"value, expected",
93115
[

0 commit comments

Comments
 (0)