ADD: Optional dataset to metadata.list_fields

Author: Dane Rigby

CHANGELOG.md

@@ -6,6 +6,9 @@
 - Added support for `listing_id`, `issuer_id`, and `security_id` as `stype_in`
   values for the security master and corporate actions reference data
   endpoints, and `security_id` for the adjustment factors endpoint
+- Added a `dataset` parameter to `MetadataHttpAPI.list_fields()`. If not
+  provided, the returned fields are for the latest DBN encoding version,
+  which may not match a specific dataset's schema
 
 ## 0.83.0 - 2026-08-04
 

databento/historical/api/metadata.py

@@ -123,6 +123,7 @@ def list_fields(
         self,
         schema: Schema | str,
         encoding: Encoding | str,
+        dataset: Dataset | str | None = None,
     ) -> list[dict[str, str]]:
         """
         List all fields for a particular schema and encoding from Databento.
@@ -135,6 +136,10 @@ def list_fields(
             The data record schema for the request.
         encoding : Encoding or str {'dbn', 'csv', 'json'}
             The data encoding.
+        dataset : Dataset or str, optional
+            The dataset code (string identifier) used to determine which fields are relevant.
+            If `None` then the fields for the latest DBN encoding version are returned,
+            which may differ from a specific dataset's schema.
 
         Returns
         -------
@@ -145,6 +150,10 @@ def list_fields(
         params: list[tuple[str, str | Any]] = [
             ("schema", validate_enum(schema, Schema, "schema")),
             ("encoding", validate_enum(encoding, Encoding, "encoding")),
+            (
+                "dataset",
+                validate_semantic_string(dataset, "dataset") if dataset is not None else None,
+            ),
         ]
 
         response: Response = self._get(

tests/test_historical_metadata.py

@@ -94,6 +94,42 @@ def test_list_fields_sends_expected_request(
     assert call["url"] == f"{historical_client.gateway}/v{db.API_VERSION}/metadata.list_fields"
     assert ("schema", "mbo") in call["params"]
     assert ("encoding", "dbn") in call["params"]
+    assert ("dataset", None) in call["params"]
+    assert sorted(call["headers"].keys()) == ["accept", "user-agent"]
+    assert call["headers"]["accept"] == "application/json"
+    assert all(v in call["headers"]["user-agent"] for v in ("Databento/", "Python/"))
+    assert call["timeout"] == (100, 100)
+    assert isinstance(call["auth"], requests.auth.HTTPBasicAuth)
+
+
+@pytest.mark.parametrize(
+    "dataset",
+    [
+        "GLBX.MDP3",
+        Dataset.GLBX_MDP3,
+    ],
+)
+def test_list_fields_with_dataset_sends_expected_request(
+    monkeypatch: pytest.MonkeyPatch,
+    historical_client: Historical,
+    dataset: Dataset | str,
+) -> None:
+    # Arrange
+    monkeypatch.setattr(requests, "get", mocked_get := MagicMock())
+
+    # Act
+    historical_client.metadata.list_fields(
+        schema="mbo",
+        encoding="dbn",
+        dataset=dataset,
+    )
+
+    # Assert
+    call = mocked_get.call_args.kwargs
+    assert call["url"] == f"{historical_client.gateway}/v{db.API_VERSION}/metadata.list_fields"
+    assert ("schema", "mbo") in call["params"]
+    assert ("encoding", "dbn") in call["params"]
+    assert ("dataset", "GLBX.MDP3") in call["params"]
     assert sorted(call["headers"].keys()) == ["accept", "user-agent"]
     assert call["headers"]["accept"] == "application/json"
     assert all(v in call["headers"]["user-agent"] for v in ("Databento/", "Python/"))