DOC: Standardize API reference pt3

Author: cjdsellers

databento/historical/api/batch.py

@@ -48,7 +48,7 @@ def timeseries_submit(
         limit: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
-        Submit a time series batch data job to the Databento backend.
+        Request a new time series batch data job from Databento.
 
         Makes a `POST /batch.timeseries_submit` HTTP request.
 
@@ -93,6 +93,10 @@ def timeseries_submit(
         Dict[str, Any]
             The job info for submitted batch data request.
 
+        Warnings
+        --------
+        Calling this method will incur a cost.
+
         """
         if compression is None:
             compression = Compression.NONE
@@ -146,7 +150,7 @@ def list_jobs(
         since: Optional[Union[pd.Timestamp, date, str, int]] = None,
     ) -> List[Dict[str, Any]]:
         """
-        List batch job details for the user account.
+        Request all batch data job details for the user account.
 
         The job details will be sorted in order of `ts_received`.
 

databento/historical/api/metadata.py

@@ -32,7 +32,7 @@ def list_datasets(
         end_date: Optional[Union[date, str]] = None,
     ) -> List[str]:
         """
-        List all available datasets from Databento.
+        Request all available datasets from Databento.
 
         Makes a `GET /metadata.list_datasets` HTTP request.
 
@@ -81,7 +81,7 @@ def list_schemas(
         end_date: Optional[Union[date, str]] = None,
     ) -> List[str]:
         """
-        List all available data schemas from Databento.
+        Request all available data schemas from Databento.
 
         Makes a `GET /metadata.list_schemas` HTTP request.
 
@@ -123,7 +123,7 @@ def list_fields(
         encoding: Optional[Union[Encoding, str]] = None,
     ) -> Dict[str, Dict]:
         """
-        List all fields for a dataset, schema and encoding from Databento.
+        Request all fields for a dataset, schema and encoding from Databento.
 
         Makes a `GET /metadata.list_fields` HTTP request.
 
@@ -167,7 +167,7 @@ def list_fields(
 
     def list_encodings(self) -> List[str]:
         """
-        List all available data encodings from Databento.
+        Request all available data encodings from Databento.
 
         Makes a `GET /metadata.list_encodings` HTTP request.
 
@@ -184,7 +184,7 @@ def list_encodings(self) -> List[str]:
 
     def list_compressions(self) -> List[str]:
         """
-        List all available data compression modes from Databento.
+        Request all available data compression modes from Databento.
 
         Makes a `GET /metadata.list_compressions` HTTP request.
 
@@ -206,7 +206,7 @@ def list_unit_prices(
         schema: Optional[Union[Schema, str]] = None,
     ) -> Dict[str, Any]:
         """
-        List data schema prices per GB unit from Databento.
+        Request data schema prices per GB unit from Databento.
 
         Makes a `GET /metadata.list_unit_prices` HTTP request.
 
@@ -257,7 +257,7 @@ def get_shape(
         limit: Optional[int] = None,
     ) -> Tuple:
         """
-        Get the shape of the time series data query.
+        Request the shape of the time series data from Databento.
 
         Makes a GET `/metadata.get_shape` HTTP request.
 
@@ -335,8 +335,8 @@ def get_billable_size(
         limit: Optional[int] = None,
     ) -> int:
         """
-        Get the raw uncompressed binary size of a historical streaming or batch
-        data request, which would be used for billing.
+        Request the billable uncompressed raw binary size for historical
+        streaming or batched files from Databento.
 
         Makes a GET `/metadata.get_billable_size` HTTP request.
 
@@ -404,7 +404,8 @@ def get_cost(
         limit: Optional[int] = None,
     ) -> float:
         """
-        Get cost in US Dollars for a historical streaming or batch data request.
+        Request the cost in US Dollars for historical streaming or batched files
+        from Databento.
 
         Makes a `GET /metadata.get_cost` HTTP request.
 
@@ -472,7 +473,8 @@ def get_license_fee(
         purposes: Union[List[str], str],
     ) -> int:
         """
-        Get the license fee in US Dollars for a dataset and access purposes.
+        Request the license fee in US Dollars for a dataset and access purposes
+        from Databento.
 
         Makes a `GET /metadata.get_license_fee` HTTP request.
 

databento/historical/api/symbology.py

@@ -29,7 +29,7 @@ def resolve(
         default_value: Optional[str] = "",
     ):
         """
-        Request symbology resolution.
+        Request symbology mappings resolution from Databento.
 
         Makes a `GET /symbology.resolve` HTTP request.
 

databento/historical/api/timeseries.py

@@ -37,7 +37,7 @@ def stream(
         path: Optional[str] = None,
     ) -> Bento:
         """
-        Request a historical time series stream from the Databento API servers.
+        Request a historical time series stream from Databento.
 
         Makes a `GET /timeseries.stream` HTTP request.
 
@@ -68,12 +68,16 @@ def stream(
         Returns
         -------
         Bento
-            If `path` provided then FileBento, otherwise MemoryBento.
+            If `path` provided then `FileBento`, otherwise `MemoryBento`.
 
         Notes
         -----
         The Databento Binary Encoding + Zstd Compression (DBZ) will be streamed.
 
+        Warnings
+        --------
+        Calling this method will incur a cost.
+
         """
         validate_enum(schema, Schema, "schema")
         validate_enum(stype_in, SType, "stype_in")
@@ -130,8 +134,7 @@ async def stream_async(
         path: str = None,
     ) -> Bento:
         """
-        Request a historical time series stream from the Databento API servers
-        asynchronously.
+        Request a historical time series stream from Databento asynchronously.
 
         Makes a `GET /timeseries.stream` HTTP request.
 
@@ -162,12 +165,16 @@ async def stream_async(
         Returns
         -------
         Bento
-            If `path` provided then FileBento, otherwise MemoryBento.
+            If `path` provided then `FileBento`, otherwise `MemoryBento`.
 
         Notes
         -----
         The Databento Binary Encoding + Zstd Compression (DBZ) will be streamed.
 
+        Warnings
+        --------
+        Calling this method will incur a cost.
+
         """
         validate_enum(schema, Schema, "schema")
         validate_enum(stype_in, SType, "stype_in")