DOC: Standardize API reference pt2

Author: cjdsellers

databento/common/bento.py

@@ -226,7 +226,7 @@ def symbols(self) -> List[str]:
     @property
     def stype_in(self) -> SType:
         """
-        Return the query input symbol type for the data.
+        Return the query input symbology type for the data.
 
         Returns
         -------
@@ -242,7 +242,7 @@ def stype_in(self) -> SType:
     @property
     def stype_out(self) -> SType:
         """
-        Return the query output symbol type for the data.
+        Return the query output symbology type for the data.
 
         Returns
         -------

databento/common/enums.py

@@ -101,7 +101,7 @@ class Delivery(Enum):
 
 @unique
 class SType(Enum):
-    """Represents a symbology symbol type."""
+    """Represents a symbology type."""
 
     PRODUCT_ID = "product_id"
     NATIVE = "native"

databento/historical/api/batch.py

@@ -78,11 +78,12 @@ def timeseries_submit(
         delivery : Delivery or str {'download', 's3', 'disk'}, default 'download'
             The batch data delivery mechanism.
         stype_in : SType or str, default 'native'
-            The input symbol type to resolve from.
+            The input symbology type to resolve from.
         stype_out : SType or str, default 'product_id'
-            The output symbol type to resolve to.
+            The output symbology type to resolve to.
         limit : int, optional
             The maximum number of records for the request.
+            If ``None`` is passed then no limit.
 
         Returns
         -------

databento/historical/api/metadata.py

@@ -31,7 +31,7 @@ def list_datasets(
         end_date: Optional[Union[date, str]] = None,
     ) -> List[str]:
         """
-        List all datasets available from Databento.
+        List all available datasets from Databento.
 
         Makes a `GET /v0/metadata.list_datasets` HTTP request.
 
@@ -80,7 +80,7 @@ def list_schemas(
         end_date: Optional[Union[date, str]] = None,
     ) -> List[str]:
         """
-        List all data schemas available from Databento.
+        List all available data schemas from Databento.
 
         Makes a `GET /v0/metadata.list_schemas` HTTP request.
 
@@ -166,7 +166,7 @@ def list_fields(
 
     def list_encodings(self) -> List[str]:
         """
-        List all data encodings available from Databento.
+        List all available data encodings from Databento.
 
         Makes a `GET /v0/metadata.list_encodings` HTTP request.
 
@@ -183,7 +183,7 @@ def list_encodings(self) -> List[str]:
 
     def list_compressions(self) -> List[str]:
         """
-        List all data compression modes available from Databento.
+        List all available data compression modes from Databento.
 
         Makes a `GET /v0/metadata.list_compressions` HTTP request.
 
@@ -279,13 +279,15 @@ def get_shape(
         encoding : Encoding or str {'dbz', 'csv', 'json'}, optional
             The data encoding.
         stype_in : SType or str, default 'native'
-            The input symbol type to resolve from.
+            The input symbology type to resolve from.
         limit : int, optional
             The maximum number of records to include in the query.
+            If ``None`` is passed then no limit.
 
         Returns
         -------
         Tuple
+            The shape of the data expressed as size per dimension.
 
         """
         validate_enum(schema, Schema, "schema")
@@ -319,7 +321,7 @@ def get_shape(
         )
 
         values = response.json()
-        return values[0], values[1]
+        return tuple(values)
 
     def get_billable_size(
         self,
@@ -354,9 +356,10 @@ def get_billable_size(
             Assumes UTC as timezone unless passed a tz-aware object.
             If using an integer then this represents nanoseconds since UNIX epoch.
         stype_in : SType or str, default 'native'
-            The input symbol type to resolve from.
+            The input symbology type to resolve from.
         limit : int, optional
             The maximum number of records to include in the query.
+            If ``None`` is passed then no limit.
 
         Returns
         -------
@@ -400,7 +403,7 @@ def get_cost(
         limit: Optional[int] = None,
     ) -> float:
         """
-        Get the expected total cost of the data stream.
+        Get cost in US Dollars for a historical streaming or batch data request.
 
         Makes a `GET /v0/metadata.get_cost` HTTP request.
 
@@ -423,14 +426,15 @@ def get_cost(
             Assumes UTC as timezone unless passed a tz-aware object.
             If using an integer then this represents nanoseconds since UNIX epoch.
         stype_in : SType or str, default 'native'
-            The input symbol type to resolve from.
+            The input symbology type to resolve from.
         limit : int, optional
             The maximum number of records to include in the query.
+            If ``None`` is passed then no limit.
 
         Returns
         -------
         float
-            The cost for the data in US Dollars.
+            The cost in US Dollars.
 
         """
         validate_enum(mode, FeedMode, "mode")

databento/historical/api/symbology.py

@@ -40,9 +40,9 @@ def resolve(
         symbols : List[Union[str, int]] or str, optional
             The symbols to resolve.
         stype_in : SType or str, default 'native'
-            The input symbol type to resolve from.
+            The input symbology type to resolve from.
         stype_out : SType or str, default 'product_id'
-            The output symbol type to resolve to.
+            The output symbology type to resolve to.
         start_date : date or str
             The start date (UTC) of the request time range (inclusive).
         end_date : date or str

databento/historical/api/timeseries.py

@@ -56,13 +56,14 @@ def stream(
             The end datetime (UTC) of the request time range (exclusive).
             If using an integer then this represents nanoseconds since UNIX epoch.
         stype_in : SType or str, default 'native'
-            The input symbol type to resolve from.
+            The input symbology type to resolve from.
         stype_out : SType or str, default 'product_id'
-            The output symbol type to resolve to.
+            The output symbology type to resolve to.
         limit : int, optional
             The maximum number of records to return.
+            If ``None`` is passed then no limit.
         path : str, optional
-            The path to the file to write to on disk (if provided).
+            The file path to write to on disk (if provided).
 
         Returns
         -------
@@ -154,8 +155,9 @@ async def stream_async(
             The output symbology type to resolve to.
         limit : int, optional
             The maximum number of records to return.
+            If ``None`` is passed then no limit.
         path : str, optional
-            The path to the file to write to (if provided).
+            The file path to write to on disk (if provided).
 
         Returns
         -------

databento/historical/client.py

@@ -125,7 +125,7 @@ def request_full_definitions(
         data : Bento
             The bento to source the metadata from.
         path : str, optional
-            The optional path to stream the data to on disk.
+            The file path to write to on disk (if provided).
 
         Returns
         -------