ADD: Add get_license_fee to Python client library

Author: cjdsellers

databento/common/parsing.py

@@ -68,15 +68,61 @@ def maybe_enum_or_str_lowercase(
     return enum_or_str_lowercase(value, param)
 
 
+def values_list_to_string(
+    values: Union[Iterable[str], str],
+) -> str:
+    """
+    Concatenate a values string or iterable of string values.
+
+    Parameters
+    ----------
+    values : iterable of str or str
+        The values to concatenate.
+
+    Returns
+    -------
+    str
+
+    """
+    if isinstance(values, str):
+        return values.strip().rstrip(",").lower()
+    elif isinstance(values, Iterable):
+        return ",".join(values).strip().lower()
+    else:
+        raise TypeError(f"invalid values type, was {type(values)}")
+
+
+def maybe_values_list_to_string(
+    values: Optional[Union[Iterable[str], str]],
+) -> Optional[str]:
+    """
+    Concatenate a values string or iterable of string values (if not None).
+
+    Parameters
+    ----------
+    values : iterable of str or str, optional
+        The values to concatenate.
+
+    Returns
+    -------
+    str or ``None``
+
+    """
+    if values is None:
+        return None
+
+    return values_list_to_string(values)
+
+
 def maybe_symbols_list_to_string(
-    symbols: Optional[Iterable[str]],
+    symbols: Optional[Union[Iterable[str], str]],
 ) -> Optional[str]:
     """
-    Concatenate a symbols string (if not None).
+    Concatenate a symbols string or iterable of symbol strings (if not None).
 
     Parameters
     ----------
-    symbols : iterable of str, optional
+    symbols : iterable of str or str, optional
         The symbols to concatenate.
 
     Returns
@@ -85,12 +131,12 @@ def maybe_symbols_list_to_string(
 
     """
     if symbols is None:
-        return None  # ALL
+        return None  # All symbols
 
     if isinstance(symbols, str):
-        return symbols.rstrip(",").upper()
-    if isinstance(symbols, (tuple, list)):
-        return ",".join(symbols).upper()
+        return symbols.strip().rstrip(",").upper()
+    elif isinstance(symbols, Iterable):
+        return ",".join(symbols).strip().upper()
     else:
         raise TypeError(f"invalid symbols type, was {type(symbols)}")
 

databento/historical/api/batch.py

@@ -12,7 +12,10 @@
     Schema,
     SType,
 )
-from databento.common.parsing import maybe_datetime_to_string
+from databento.common.parsing import (
+    maybe_datetime_to_string,
+    maybe_values_list_to_string,
+)
 from databento.common.validation import validate_enum
 from databento.historical.api import API_VERSION
 from databento.historical.http import BentoHttpAPI
@@ -47,7 +50,7 @@ def timeseries_submit(
         """
         Submit a time series batch data job to the Databento backend.
 
-        `POST /v0/batch.timeseries_submit` HTTP API endpoint.
+        Makes a `POST /batch.timeseries_submit` HTTP request.
 
         Parameters
         ----------
@@ -139,32 +142,35 @@ def timeseries_submit(
 
     def list_jobs(
         self,
-        states: Optional[str] = "received,queued,processing,done",
+        states: Optional[Union[List[str], str]] = "received,queued,processing,done",
         since: Optional[Union[pd.Timestamp, date, str, int]] = None,
     ) -> List[Dict[str, Any]]:
         """
-        Request all batch data jobs associated with the client access key with
-        the optional query filters.
+        List batch job details for the user account.
+
+        The job details will be sorted in order of `ts_received`.
 
-        Makes a `GET /v0/batch.list_jobs` HTTP request.
+        Makes a `GET /batch.list_jobs` HTTP request.
 
         Parameters
         ----------
-        states : str, optional {'received', 'queued', 'processing', 'done', 'expired'}
-            The comma separated job states to include in the response. If ``None``
-            will default to 'queued,processing,done' (may contain whitespace).
+        states : List[str] or str, optional {'received', 'queued', 'processing', 'done', 'expired'}  # noqa
+            The filter for jobs states as a list of comma separated values.
         since : pd.Timestamp or date or str or int, optional
-            The datetime to filter from.
+            The filter for timestamp submitted (will not include jobs prior to this).
 
         Returns
         -------
         List[Dict[str, Any]]
-            The matching jobs sorted in order of timestamp received.
+            The batch job details.
 
         """
+        states = maybe_values_list_to_string(states)
+        since = maybe_datetime_to_string(since)
+
         params: List[Tuple[str, str]] = [
             ("states", states),
-            ("since", maybe_datetime_to_string(since)),
+            ("since", since),
         ]
 
         return self._get(

databento/historical/api/metadata.py

@@ -9,6 +9,7 @@
     maybe_datetime_to_string,
     maybe_enum_or_str_lowercase,
     maybe_symbols_list_to_string,
+    values_list_to_string,
 )
 from databento.common.validation import validate_enum, validate_maybe_enum
 from databento.historical.api import API_VERSION
@@ -33,7 +34,7 @@ def list_datasets(
         """
         List all available datasets from Databento.
 
-        Makes a `GET /v0/metadata.list_datasets` HTTP request.
+        Makes a `GET /metadata.list_datasets` HTTP request.
 
         Parameters
         ----------
@@ -82,7 +83,7 @@ def list_schemas(
         """
         List all available data schemas from Databento.
 
-        Makes a `GET /v0/metadata.list_schemas` HTTP request.
+        Makes a `GET /metadata.list_schemas` HTTP request.
 
         Parameters
         ----------
@@ -124,7 +125,7 @@ def list_fields(
         """
         List all fields for a dataset, schema and encoding from Databento.
 
-        Makes a `GET /v0/metadata.list_fields` HTTP request.
+        Makes a `GET /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.
@@ -168,7 +169,7 @@ def list_encodings(self) -> List[str]:
         """
         List all available data encodings from Databento.
 
-        Makes a `GET /v0/metadata.list_encodings` HTTP request.
+        Makes a `GET /metadata.list_encodings` HTTP request.
 
         Returns
         -------
@@ -185,7 +186,7 @@ def list_compressions(self) -> List[str]:
         """
         List all available data compression modes from Databento.
 
-        Makes a `GET /v0/metadata.list_compressions` HTTP request.
+        Makes a `GET /metadata.list_compressions` HTTP request.
 
         Returns
         -------
@@ -207,7 +208,7 @@ def list_unit_prices(
         """
         List data schema prices per GB unit from Databento.
 
-        Makes a `GET /v0/metadata.list_unit_prices` HTTP request.
+        Makes a `GET /metadata.list_unit_prices` HTTP request.
 
         Parameters
         ----------
@@ -258,7 +259,7 @@ def get_shape(
         """
         Get the shape of the time series data query.
 
-        Makes a GET `/v0/metadata.get_shape` HTTP request.
+        Makes a GET `/metadata.get_shape` HTTP request.
 
         Parameters
         ----------
@@ -337,7 +338,7 @@ def get_billable_size(
         Get the raw uncompressed binary size of a historical streaming or batch
         data request, which would be used for billing.
 
-        Makes a GET `/v0/metadata.get_billable_size` HTTP request.
+        Makes a GET `/metadata.get_billable_size` HTTP request.
 
         Parameters
         ----------
@@ -405,7 +406,7 @@ def get_cost(
         """
         Get cost in US Dollars for a historical streaming or batch data request.
 
-        Makes a `GET /v0/metadata.get_cost` HTTP request.
+        Makes a `GET /metadata.get_cost` HTTP request.
 
         Parameters
         ----------
@@ -464,3 +465,42 @@ def get_cost(
         )
 
         return response.json()
+
+    def get_license_fee(
+        self,
+        dataset: Union[Dataset, str],
+        purposes: Union[List[str], str],
+    ) -> int:
+        """
+        Get the license fee in US Dollars for a dataset and access purposes.
+
+        Makes a `GET /metadata.get_license_fee` HTTP request.
+
+        Parameters
+        ----------
+        dataset : Dataset or str
+            The dataset name for the request.
+        purposes : List[str] or str, {'professional trading', 'display usage', 'non-display usage', 'external redistribution', 'internal redistribution'}  # noqa
+            The licensing purposes.
+
+        Returns
+        -------
+        int
+            The license fee in US Dollars.
+
+        """
+        dataset = enum_or_str_lowercase(dataset, "dataset")
+        purposes = values_list_to_string(purposes)
+
+        params: List[Tuple[str, str]] = [
+            ("dataset", dataset),
+            ("purposes", purposes),
+        ]
+
+        response: Response = self._get(
+            url=self._base_url + ".get_license_fee",
+            params=params,
+            basic_auth=True,
+        )
+
+        return response.json()

databento/historical/api/symbology.py

@@ -31,7 +31,7 @@ def resolve(
         """
         Request symbology resolution.
 
-        Makes a `GET /v0/symbology.resolve` HTTP request.
+        Makes a `GET /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.
 
-        Makes a `GET /v0/timeseries.stream` HTTP request.
+        Makes a `GET /timeseries.stream` HTTP request.
 
         Parameters
         ----------
@@ -133,7 +133,7 @@ async def stream_async(
         Request a historical time series stream from the Databento API servers
         asynchronously.
 
-        Makes a `GET /v0/timeseries.stream` HTTP request.
+        Makes a `GET /timeseries.stream` HTTP request.
 
         Parameters
         ----------
@@ -236,7 +236,7 @@ def _pre_check_data_size(
                 "request...",
             )
             response: Response = self._get(
-                url=self._gateway + "/v0/metadata.get_size_estimation",
+                url=self._gateway + f"/v{API_VERSION}/metadata.get_size_estimation",
                 params=params,
                 basic_auth=True,
             )
@@ -260,7 +260,7 @@ def _pre_check_data_size(
 
 def _is_large_number_of_symbols(symbols: Optional[Union[List[str], str]]):
     if not symbols:
-        return True  # ALL
+        return True  # All symbols
 
     if isinstance(symbols, str):
         symbols = symbols.split(",")

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.
 
-        Makes a `GET /v0/symbology.resolve` HTTP request.
+        Makes a `GET /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.
 
-        Makes a `GET /v0/timeseries.stream` HTTP request.
+        Makes a `GET /timeseries.stream` HTTP request.
 
         Parameters
         ----------

tests/test_common_parsing.py

@@ -1,5 +1,6 @@
 from datetime import date
 
+import numpy as np
 import pandas as pd
 import pytest
 from databento.common.enums import Dataset, Flags
@@ -9,6 +10,7 @@
     maybe_datetime_to_string,
     maybe_enum_or_str_lowercase,
     maybe_symbols_list_to_string,
+    maybe_values_list_to_string,
     parse_flags,
 )
 
@@ -60,6 +62,35 @@ def test_maybe_enum_or_str_lowercase_returns_expected_outputs(
         # Arrange, Act, Assert
         assert maybe_enum_or_str_lowercase(value, "param") == expected
 
+    def test_maybe_values_list_to_string_given_invalid_input_raises_type_error(
+        self,
+    ) -> None:
+        # Arrange, Act, Assert
+        with pytest.raises(TypeError):
+            maybe_values_list_to_string(type)
+
+    @pytest.mark.parametrize(
+        "values, expected",
+        [
+            [None, None],
+            ["ABC,DEF", "abc,def"],
+            [" ABC, DEF ", "abc, def"],
+            [[" ABC", "DEF "], "abc,def"],
+            [np.asarray([" ABC", "DEF "]), "abc,def"],
+            [("1", "2"), "1,2"],
+        ],
+    )
+    def test_maybe_values_list_to_string_given_valid_inputs_returns_expected(
+        self,
+        values,
+        expected,
+    ) -> None:
+        # Arrange, Act
+        result = maybe_values_list_to_string(values)
+
+        # Assert
+        assert result == expected
+
     def test_maybe_symbols_list_to_string_given_invalid_input_raises_type_error(
         self,
     ) -> None: