REF: Rename to timeseries.get_range

Author: cjdsellers

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.8.0 - TBD
 - Renamed 'dbz' encoding to 'dbn'
+- Renamed `timeseries.stream` to `timeseries.get_range`
 - Added `batch.list_files(...)` method
 - Added `batch.download(...)` method
 - Changed `.to_df(...)` `pretty_ts` default argument to `True`

README.md

@@ -54,7 +54,7 @@ A simple Databento application looks like this:
 import databento as db
 
 client = db.Historical('YOUR_API_KEY')
-data = client.timeseries.stream(
+data = client.timeseries.get_range(
     dataset='GLBX.MDP3',
     symbols='ES.FUT',
     stype_in='smart',

databento/common/bento.py

@@ -702,7 +702,7 @@ def request_full_definitions(
         """
         Request full instrument definitions based on the metadata properties.
 
-        Makes a `GET /timeseries.stream` HTTP request.
+        Makes a `GET /timeseries.get_range` HTTP request.
 
         Parameters
         ----------
@@ -720,7 +720,7 @@ def request_full_definitions(
         Calling this method will incur a cost.
 
         """
-        return client.timeseries.stream(
+        return client.timeseries.get_range(
             dataset=self.dataset,
             symbols=self.symbols,
             schema=Schema.DEFINITION,

databento/common/deprecated.py

@@ -0,0 +1,13 @@
+import functools
+import warnings
+from typing import Any
+
+
+def deprecated(func: Any) -> Any:
+    @functools.wraps(func)
+    def new_func(*args: Any, **kwargs: Any) -> Any:
+        warnings.simplefilter("always", DeprecationWarning)
+        warnings.warn(func.__doc__, category=DeprecationWarning)
+        return func(*args, **kwargs)
+
+    return new_func

databento/historical/api/timeseries.py

@@ -5,6 +5,7 @@
 
 import pandas as pd
 from databento.common.bento import Bento
+from databento.common.deprecated import deprecated
 from databento.common.enums import Compression, Dataset, Encoding, Schema, SType
 from databento.common.parsing import datetime_to_string, optional_symbols_list_to_string
 from databento.common.validation import validate_enum
@@ -22,6 +23,7 @@ def __init__(self, key: str, gateway: str) -> None:
         super().__init__(key=key, gateway=gateway)
         self._base_url = gateway + f"/v{API_VERSION}/timeseries"
 
+    @deprecated
     def stream(
         self,
         dataset: Union[Dataset, str],
@@ -33,11 +35,39 @@ def stream(
         stype_out: Union[SType, str] = "product_id",
         limit: Optional[int] = None,
         path: Optional[Union[Path, str]] = None,
+    ) -> Bento:
+        """
+        The `.stream` method is deprecated and will be removed in a future version.
+        The method has been renamed to `.get_range`, which you can now use.
+        """
+        return self.get_range(
+            dataset=dataset,
+            start=start,
+            end=end,
+            symbols=symbols,
+            schema=schema,
+            stype_in=stype_in,
+            stype_out=stype_out,
+            limit=limit,
+            path=path,
+        )
+
+    def get_range(
+        self,
+        dataset: Union[Dataset, str],
+        start: Union[pd.Timestamp, date, str, int],
+        end: Union[pd.Timestamp, date, str, int],
+        symbols: Optional[Union[List[str], str]] = None,
+        schema: Union[Schema, str] = "trades",
+        stype_in: Union[SType, str] = "native",
+        stype_out: Union[SType, str] = "product_id",
+        limit: Optional[int] = None,
+        path: Optional[Union[Path, str]] = None,
     ) -> Bento:
         """
         Request a historical time series data stream from Databento.
 
-        Makes a `GET /timeseries.stream` HTTP request.
+        Makes a `GET /timeseries.get_range` HTTP request.
 
         Primary method for getting historical intraday market data, daily data,
         instrument definitions and market status data directly into your application.
@@ -114,15 +144,15 @@ def stream(
         bento: Bento = self._create_bento(path=path)
 
         self._stream(
-            url=self._base_url + ".stream",
+            url=self._base_url + ".get_range",
             params=params,
             basic_auth=True,
             bento=bento,
         )
 
         return bento
 
-    async def stream_async(
+    async def get_range_async(
         self,
         dataset: Union[Dataset, str],
         start: Union[pd.Timestamp, date, str, int],
@@ -137,7 +167,7 @@ async def stream_async(
         """
         Request a historical time series data stream from Databento asynchronously.
 
-        Makes a `GET /timeseries.stream` HTTP request.
+        Makes a `GET /timeseries.get_range` HTTP request.
 
         Primary method for getting historical intraday market data, daily data,
         instrument definitions and market status data directly into your application.
@@ -213,7 +243,7 @@ async def stream_async(
         bento: Bento = self._create_bento(path=path)
 
         await self._stream_async(
-            url=self._base_url + ".stream",
+            url=self._base_url + ".get_range",
             params=params,
             basic_auth=True,
             bento=bento,

examples/historical_timeseries_async.py

@@ -11,7 +11,7 @@ async def request_stream_async() -> None:
     key = "YOUR_API_KEY"
     client = db.Historical(key=key)
 
-    data: Bento = await client.timeseries.stream_async(
+    data: Bento = await client.timeseries.get_range_async(
         dataset="GLBX.MDP3",
         symbols=["ESM2"],
         schema="mbo",

examples/historical_timeseries_disk_io.py

@@ -13,7 +13,7 @@
     path = "my_data.dbn"
 
     # Execute request through client
-    data: Bento = client.timeseries.stream(
+    data: Bento = client.timeseries.get_range(
         dataset="GLBX.MDP3",
         symbols=["ESM2"],
         schema="mbo",

examples/historical_timeseries_replay.py

@@ -8,7 +8,7 @@
     key = "YOUR_API_KEY"
     client = db.Historical(key=key)
 
-    data: Bento = client.timeseries.stream(
+    data: Bento = client.timeseries.get_range(
         dataset="GLBX.MDP3",
         symbols=["ESM2"],
         schema="trades",

examples/historical_timeseries_to_df.py

@@ -10,7 +10,7 @@
     key = "YOUR_API_KEY"
     client = db.Historical(key=key)
 
-    data: Bento = client.timeseries.stream(
+    data: Bento = client.timeseries.get_range(
         dataset="GLBX.MDP3",
         symbols=["ESM2"],
         schema="trades",

examples/historical_timeseries_to_file.py

@@ -10,7 +10,7 @@
     key = "YOUR_API_KEY"
     client = db.Historical(key=key)
 
-    data: Bento = client.timeseries.stream(
+    data: Bento = client.timeseries.get_range(
         dataset="GLBX.MDP3",
         symbols=["ESM2"],
         schema="trades",