DOC: Align and refine API reference pt1

Author: cjdsellers

databento/common/bento.py

@@ -414,7 +414,7 @@ def symbology(self) -> Dict[str, Any]:
 
     def to_ndarray(self) -> np.ndarray:
         """
-        Return the data as a numpy ndarray.
+        Return the data as a numpy `ndarray`.
 
         Returns
         -------
@@ -480,7 +480,7 @@ def to_df(self, pretty_ts: bool = False, pretty_px: bool = False) -> pd.DataFram
 
     def replay(self, callback: Callable[[Any], None]) -> None:
         """
-        Pass all data records sequentially to the given callback.
+        Replay data by passing records sequentially to the given callback.
 
         Parameters
         ----------
@@ -538,7 +538,7 @@ def to_file(self, path: str) -> "FileBento":
         Parameters
         ----------
         path : str
-            The path to write to.
+            The file path to write to.
 
         Returns
         -------
@@ -555,24 +555,32 @@ def to_file(self, path: str) -> "FileBento":
 
     def to_csv(self, path: str) -> None:
         """
-        Write the data to a CSV file at the given path.
+        Write the data to a file in CSV format.
 
         Parameters
         ----------
         path : str
-            The path to write to.
+            The file path to write to.
+
+        Notes
+        -----
+        Requires all the data to be brought up into memory to then be written.
 
         """
         self.to_df().to_csv(path)
 
     def to_json(self, path: str) -> None:
         """
-        Write the data to a JSON file at the given path.
+        Write the data to a file in JSON format.
 
         Parameters
         ----------
         path : str
-            The path to write to.
+            The file path to write to.
+
+        Notes
+        -----
+        Requires all the data to be brought up into memory to then be written.
 
         """
         self.to_df().to_json(path, orient="records", lines=True)

databento/historical/api/batch.py

@@ -45,7 +45,7 @@ def timeseries_submit(
         limit: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
-        Submit a timeseries batch data job to the Databento backend.
+        Submit a time series batch data job to the Databento backend.
 
         `POST /v0/batch.timeseries_submit` HTTP API endpoint.
 
@@ -64,9 +64,9 @@ def timeseries_submit(
             The UTC end of the time range (exclusive) for the request.
             If using an integer then this represents nanoseconds since UNIX epoch.
         encoding : Encoding or str {'dbz', 'csv', 'json'}, default 'dbz'
-            The data output encoding.
+            The data encoding.
         compression : Compression or str {'none', 'zstd'}, default 'zstd'
-            The data output compression.
+            The data compression mode.
         split_duration : Duration or str {'day', 'week', 'month', 'none'}, default 'day'
             The time duration split per data file ('week' starts on Sunday UTC).
         split_size : int, optional
@@ -143,7 +143,7 @@ def list_jobs(
         Request all batch data jobs associated with the client access key with
         the optional query filters.
 
-        `GET /v0/batch.list_jobs` HTTP API endpoint.
+        Makes a `GET /v0/batch.list_jobs` HTTP request.
 
         Parameters
         ----------

databento/historical/api/metadata.py

@@ -30,9 +30,9 @@ def list_datasets(
         end: Optional[Union[pd.Timestamp, date, str, int]] = None,
     ) -> List[str]:
         """
-        Request the available datasets from the API server.
+        List all datasets available from Databento.
 
-        `GET /v0/metadata.list_datasets` HTTP API endpoint.
+        Makes a `GET /v0/metadata.list_datasets` HTTP request.
 
         Parameters
         ----------
@@ -47,6 +47,17 @@ def list_datasets(
         -------
         List[str]
 
+        Notes
+        -----
+        We use dataset names in the form `PUBLISHER.DATASET` for each dataset,
+        where each publisher is represented by a 4 character code, which is
+        usually its ISO 10383 [Market Identifier Code (MIC)](https://www.iso20022.org/market-identifier-codes).  # noqa
+        These dataset names are also found on the [Explore]() and [Quick Download]()
+        features of the Databento user portal.
+
+        Use this method to list the _names_ of all available datasets, so you can use
+        other methods which take the `dataset` parameter.
+
         """
         start = maybe_datetime_to_string(start)
         end = maybe_datetime_to_string(end)
@@ -70,9 +81,9 @@ def list_schemas(
         end: Optional[Union[pd.Timestamp, date, str, int]] = None,
     ) -> List[str]:
         """
-        Request the available data record schemas from the API server.
+        List all data schemas available from Databento.
 
-        `GET /v0/metadata.list_schemas` HTTP API endpoint.
+        Makes a `GET /v0/metadata.list_schemas` HTTP request.
 
         Parameters
         ----------
@@ -114,9 +125,12 @@ def list_fields(
         encoding: Optional[Union[Encoding, str]] = None,
     ) -> Dict[str, Dict]:
         """
-        Request the data record fields from the API server.
+        List all fields for a dataset, schema and encoding from Databento.
 
-        `GET /v0/metadata.list_fields` HTTP API endpoint.
+        Makes a `GET /v0/metadata.list_fields` HTTP request.
+
+        The `schema` and `encoding` parameters act as optional filters. All
+        metadata for that parameter is returned if they are not specified.
 
         Parameters
         ----------
@@ -125,7 +139,7 @@ def list_fields(
         schema : Schema or str {'mbo', 'mbp-1', 'mbp-10', 'trades', 'tbbo', 'ohlcv-1s', 'ohlcv-1m', 'ohlcv-1h', 'ohlcv-1d', 'definition', 'statistics', 'status'}, optional  # noqa
             The data record schema for the request.
         encoding : Encoding or str {'dbz', 'csv', 'json'}, optional
-            The data output encoding.
+            The data encoding.
 
         Returns
         -------
@@ -155,9 +169,9 @@ def list_fields(
 
     def list_encodings(self) -> List[str]:
         """
-        Request the available encoding options from the API server.
+        List all data encodings available from Databento.
 
-        `GET /v0/metadata.list_encodings` HTTP API endpoint.
+        Makes a `GET /v0/metadata.list_encodings` HTTP request.
 
         Returns
         -------
@@ -172,9 +186,9 @@ def list_encodings(self) -> List[str]:
 
     def list_compressions(self) -> List[str]:
         """
-        Request the available compression options from the API server.
+        List all data compression modes available from Databento.
 
-        `GET /v0/metadata.list_compressions` HTTP API endpoint.
+        Makes a `GET /v0/metadata.list_compressions` HTTP request.
 
         Returns
         -------
@@ -192,11 +206,11 @@ def list_unit_prices(
         dataset: Union[Dataset, str],
         mode: Optional[Union[FeedMode, str]] = None,
         schema: Optional[Union[Schema, str]] = None,
-    ) -> Union[Dict[str, Any], float]:
+    ) -> Dict[str, Any]:
         """
-        Request the data prices per unit GB from the API server.
+        List data schema prices per GB unit from Databento.
 
-        `GET /v0/metadata.list_unit_prices` HTTP API endpoint.
+        Makes a `GET /v0/metadata.list_unit_prices` HTTP request.
 
         Parameters
         ----------
@@ -209,8 +223,8 @@ def list_unit_prices(
 
         Returns
         -------
-        Dict[str, Any] or float
-            A map of unit prices filtered on the given optional parameters.
+        Dict[str, Any]
+            A map of dataset to feed mode to unit price.
 
         """
         validate_maybe_enum(schema, Schema, "schema")
@@ -243,11 +257,11 @@ def get_shape(
         encoding: Union[Encoding, str] = "dbz",
         stype_in: Optional[Union[SType, str]] = "native",
         limit: Optional[int] = None,
-    ) -> Tuple[int, int]:
+    ) -> Tuple:
         """
-        Request the shape of the timeseries data as a rows and columns tuple.
+        Get the shape of the time series data query.
 
-        GET `/v0/metadata.get_shape` HTTP API endpoint.
+        Makes a GET `/v0/metadata.get_shape` HTTP request.
 
         Parameters
         ----------
@@ -264,15 +278,15 @@ def get_shape(
             The end datetime for the request range (UTC).
             If using an integer then this represents nanoseconds since UNIX epoch.
         encoding : Encoding or str {'dbz', 'csv', 'json'}, optional
-            The data output encoding.
+            The data encoding.
         stype_in : SType or str, default 'native'
             The input symbol type to resolve from.
         limit : int, optional
-            The maximum number of records for the request.
+            The maximum number of records to include in the query.
 
         Returns
         -------
-        Tuple[int, int]
+        Tuple
 
         """
         validate_enum(schema, Schema, "schema")
@@ -319,9 +333,10 @@ def get_billable_size(
         limit: Optional[int] = None,
     ) -> int:
         """
-        Request the uncompressed binary size of the data stream (used for billing).
+        Get the raw uncompressed binary size of a historical streaming or batch
+        data request, which would be used for billing.
 
-        GET `/v0/metadata.get_billable_size` HTTP API endpoint.
+        Makes a GET `/v0/metadata.get_billable_size` HTTP request.
 
         Parameters
         ----------
@@ -340,12 +355,12 @@ def get_billable_size(
         stype_in : SType or str, default 'native'
             The input symbol type to resolve from.
         limit : int, optional
-            The maximum number of records for the request.
+            The maximum number of records to include in the query.
 
         Returns
         -------
         int
-            The uncompressed size of the data in bytes.
+            The size in number of bytes used for billing.
 
         """
         validate_enum(schema, Schema, "schema")
@@ -384,9 +399,9 @@ def get_cost(
         limit: Optional[int] = None,
     ) -> float:
         """
-        Request the expected total cost of the data stream.
+        Get the expected total cost of the data stream.
 
-        `GET /v0/metadata.get_cost` HTTP API endpoint.
+        Makes a `GET /v0/metadata.get_cost` HTTP request.
 
         Parameters
         ----------
@@ -407,7 +422,7 @@ def get_cost(
         stype_in : SType or str, default 'native'
             The input symbol type to resolve from.
         limit : int, optional
-            The maximum number of records for the request.
+            The maximum number of records to include in the query.
 
         Returns
         -------

databento/historical/api/symbology.py

@@ -31,7 +31,7 @@ def resolve(
         """
         Request symbology resolution.
 
-        `GET /v0/symbology.resolve` HTTP API endpoint.
+        Makes a `GET /v0/symbology.resolve` HTTP request.
 
         Parameters
         ----------

databento/historical/api/timeseries.py

@@ -39,7 +39,7 @@ def stream(
         """
         Request a historical time series stream from the Databento API servers.
 
-        `GET /v0/timeseries.stream` HTTP API endpoint.
+        Makes a `GET /v0/timeseries.stream` HTTP request.
 
         Parameters
         ----------
@@ -60,7 +60,7 @@ def stream(
         stype_out : SType or str, default 'product_id'
             The output symbol type to resolve to.
         limit : int, optional
-            The maximum number of records for the request.
+            The maximum number of records to return.
         path : str, optional
             The path to the file to write to on disk (if provided).
 
@@ -132,7 +132,7 @@ async def stream_async(
         Request a historical time series stream from the Databento API servers
         asynchronously.
 
-        `GET /v0/timeseries.stream` HTTP API endpoint.
+        Makes a `GET /v0/timeseries.stream` HTTP request.
 
         Parameters
         ----------
@@ -153,7 +153,7 @@ async def stream_async(
         stype_out : SType or str, default 'product_id'
             The output symbol type to resolve to.
         limit : int, optional
-            The maximum number of records for the request.
+            The maximum number of records to return.
         path : str, optional
             The path to the file to write to (if provided).
 

databento/historical/client.py

@@ -85,7 +85,7 @@ def request_symbology(self, data: Bento) -> Dict[str, Dict[str, Any]]:
         """
         Request symbology resolution based on the metadata properties.
 
-        `GET /v0/symbology.resolve` HTTP API endpoint.
+        Makes a `GET /v0/symbology.resolve` HTTP request.
 
         Current symbology mappings from the metadata are also available by
         calling the `.symbology` or `.mappings` properties.
@@ -118,7 +118,7 @@ def request_full_definitions(
         """
         Request full instrument definitions based on the metadata properties.
 
-        `GET /v0/timeseries.stream` HTTP API endpoint.
+        Makes a `GET /v0/timeseries.stream` HTTP request.
 
         Parameters
         ----------

examples/historical_metadata_get_shape.py

@@ -9,7 +9,7 @@
     key = "YOUR_ACCESS_KEY"
     client = db.Historical(key=key)
 
-    shape: Tuple[int, int] = client.metadata.get_shape(
+    shape: Tuple = client.metadata.get_shape(
         dataset="GLBX.MDP3",
         symbols=["ESH1"],
         schema="mbo",

examples/historical_metadata_list_unit_price.py

@@ -1,7 +1,6 @@
 from pprint import pprint
 
 import databento as db
-from databento.common.enums import FeedMode
 
 
 if __name__ == "__main__":
@@ -12,8 +11,7 @@
 
     unit_prices = client.metadata.list_unit_prices(
         dataset="GLBX.MDP3",
-        mode=FeedMode.HISTORICAL,
-        schema="mbo",
+        mode="historical-streaming",
     )
 
     pprint(unit_prices)