Make date column detection configurable in OData API (Phase 7.1)

Add DATE_COLUMNS class variable to BaseODataAPI. When a subclass declares
a non-empty DATE_COLUMNS list, EndpointQuery.collect() converts only those
columns to datetime instead of running the built-in name-based heuristic.
When DATE_COLUMNS is empty (the default), the existing heuristic is unchanged
so all current callers keep working without any migration.

  class MyAPI(BaseODataAPI):
      DATE_COLUMNS = ["Data", "DataVigencia"]
      BASE_URL = "..."

Wire-up: get_endpoint() passes DATE_COLUMNS to Endpoint, which stores it and
forwards it to EndpointQuery via both query() and get().

Add four new tests covering:
- empty DATE_COLUMNS → heuristic converts all known date columns
- DATE_COLUMNS = ["Data"] → only "Data" is converted; "DataVigencia" stays str
- DATE_COLUMNS = ["DataVigencia"] → only "DataVigencia" is converted
- propagation through ep.get() shortcut

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: wilsonfreitas

bcb/odata/api.py

@@ -41,23 +41,36 @@ class EndpointQuery(ODataQuery):
         "DataVigencia",
     }
 
+    def __init__(
+        self,
+        entity: Any,
+        url: str,
+        date_columns: Optional[list[str]] = None,
+    ) -> None:
+        super().__init__(entity, url)
+        self._date_columns: list[str] = date_columns or []
+
     def collect(self) -> pd.DataFrame:
         raw_data = super().collect()
         data = pd.DataFrame(raw_data["value"])
         if not self._raw:
-            for col in self._DATE_COLUMN_NAMES:
-                if (
-                    self.entity.name in self._DATE_COLUMN_NAMES_BY_ENDPOINT
-                    and col in self._DATE_COLUMN_NAMES_BY_ENDPOINT[self.entity.name]
-                ):
-                    data[col] = pd.to_datetime(
-                        data[col],
-                        format=self._DATE_COLUMN_NAMES_BY_ENDPOINT[self.entity.name][
-                            col
-                        ],
-                    )
-                elif col in data.columns:
-                    data[col] = pd.to_datetime(data[col])
+            if self._date_columns:
+                # Use the explicit list provided by the API subclass.
+                for col in self._date_columns:
+                    if col in data.columns:
+                        data[col] = pd.to_datetime(data[col])
+            else:
+                # Fall back to the built-in heuristic.
+                endpoint_overrides = self._DATE_COLUMN_NAMES_BY_ENDPOINT.get(
+                    self.entity.name, {}
+                )
+                for col in self._DATE_COLUMN_NAMES:
+                    if col in endpoint_overrides:
+                        data[col] = pd.to_datetime(
+                            data[col], format=endpoint_overrides[col]
+                        )
+                    elif col in data.columns:
+                        data[col] = pd.to_datetime(data[col])
         return data
 
 
@@ -75,7 +88,9 @@ class Endpoint(metaclass=EndpointMeta):
     :py:class:`bcb.odata.api.BaseODataAPI`.
     """
 
-    def __init__(self, entity: Any, url: str) -> None:
+    def __init__(
+        self, entity: Any, url: str, date_columns: Optional[list[str]] = None
+    ) -> None:
         """
         Construtor da classe Endpoint.
 
@@ -86,9 +101,13 @@ def __init__(self, entity: Any, url: str) -> None:
             Obtidos da classe ``bcb.odata.framework.ODataService``.
         url : str
             URL da API OData.
+        date_columns : list[str], optional
+            Colunas a converter para datetime. Quando fornecido, substitui a
+            heurística padrão de detecção de datas.
         """
         self._entity = entity
         self._url = url
+        self._date_columns: list[str] = date_columns or []
 
     def get(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
         """
@@ -104,7 +123,7 @@ def get(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
         -------
         pd.DataFrame: resultado da consulta
         """
-        _query = EndpointQuery(self._entity, self._url)
+        _query = EndpointQuery(self._entity, self._url, self._date_columns)
         for arg in args:
             if isinstance(arg, ODataPropertyFilter):
                 _query.filter(arg)
@@ -138,7 +157,7 @@ def query(self) -> EndpointQuery:
         -------
         bcb.odata.api.EndpointQuery
         """
-        return EndpointQuery(self._entity, self._url)
+        return EndpointQuery(self._entity, self._url, self._date_columns)
 
 
 class BaseODataAPI:
@@ -149,6 +168,7 @@ class BaseODataAPI:
     """
 
     BASE_URL: str
+    DATE_COLUMNS: list[str] = []
 
     def __init__(self) -> None:
         """
@@ -198,7 +218,9 @@ def get_endpoint(self, endpoint: str) -> Endpoint:
         ValueError
             Se o *endpoint* fornecido é errado.
         """
-        return Endpoint(self.service[endpoint], self.service.url)
+        return Endpoint(
+            self.service[endpoint], self.service.url, self.DATE_COLUMNS or None
+        )
 
 
 class ODataAPI(BaseODataAPI):

tests/conftest.py

@@ -67,6 +67,13 @@
   ]
 }"""
 
+# Response with two date columns to test DATE_COLUMNS selectivity
+ODATA_QUERY_RESPONSE_MULTI_DATE_JSON = """{
+  "value": [
+    {"Indicador": "IPCA", "Data": "2021-01-04", "DataVigencia": "2021-06-01", "Mediana": 4.5}
+  ]
+}"""
+
 
 # ---------------------------------------------------------------------------
 # Fixtures

tests/test_odata.py

@@ -11,6 +11,7 @@
     ODATA_SERVICE_ROOT_JSON,
     ODATA_METADATA_XML,
     ODATA_QUERY_RESPONSE_JSON,
+    ODATA_QUERY_RESPONSE_MULTI_DATE_JSON,
 )
 
 EXPECTATIVAS_BASE_URL = (
@@ -142,3 +143,83 @@ def test_endpoint_get_shortcut(httpx_mock):
     df = ep.get(limit=1)
     assert isinstance(df, pd.DataFrame)
     assert len(df) == 1
+
+
+# ---------------------------------------------------------------------------
+# DATE_COLUMNS — configurable date detection (Phase 7.1)
+# ---------------------------------------------------------------------------
+
+
+class _SingleDateAPI(Expectativas):
+    """API subclass that restricts date conversion to 'Data' only."""
+
+    DATE_COLUMNS = ["Data"]
+
+
+class _AltDateAPI(Expectativas):
+    """API subclass that restricts date conversion to 'DataVigencia' only."""
+
+    DATE_COLUMNS = ["DataVigencia"]
+
+
+def test_date_columns_default_empty_uses_heuristic(httpx_mock):
+    """When DATE_COLUMNS is empty (default), the built-in heuristic fires."""
+    add_service_mocks(httpx_mock)
+    httpx_mock.add_response(
+        url=ENTITY_URL_PATTERN,
+        text=ODATA_QUERY_RESPONSE_MULTI_DATE_JSON,
+        status_code=200,
+    )
+    api = Expectativas()  # DATE_COLUMNS = []
+    ep = api.get_endpoint("ExpectativasMercadoAnuais")
+    df = ep.query().limit(1).collect()
+    # Heuristic converts both "Data" and "DataVigencia"
+    assert isinstance(df["Data"].iloc[0], datetime)
+    assert isinstance(df["DataVigencia"].iloc[0], datetime)
+
+
+def test_date_columns_explicit_list_converts_only_listed(httpx_mock):
+    """When DATE_COLUMNS lists only 'Data', only that column is converted."""
+    add_service_mocks(httpx_mock)
+    httpx_mock.add_response(
+        url=ENTITY_URL_PATTERN,
+        text=ODATA_QUERY_RESPONSE_MULTI_DATE_JSON,
+        status_code=200,
+    )
+    api = _SingleDateAPI()
+    ep = api.get_endpoint("ExpectativasMercadoAnuais")
+    df = ep.query().limit(1).collect()
+    assert isinstance(df["Data"].iloc[0], datetime)
+    # DataVigencia is NOT in DATE_COLUMNS so it stays as a raw string
+    assert isinstance(df["DataVigencia"].iloc[0], str)
+
+
+def test_date_columns_explicit_list_alternate_column(httpx_mock):
+    """When DATE_COLUMNS lists only 'DataVigencia', only that column is converted."""
+    add_service_mocks(httpx_mock)
+    httpx_mock.add_response(
+        url=ENTITY_URL_PATTERN,
+        text=ODATA_QUERY_RESPONSE_MULTI_DATE_JSON,
+        status_code=200,
+    )
+    api = _AltDateAPI()
+    ep = api.get_endpoint("ExpectativasMercadoAnuais")
+    df = ep.query().limit(1).collect()
+    assert isinstance(df["DataVigencia"].iloc[0], datetime)
+    # Data is NOT in DATE_COLUMNS so it stays as a raw string
+    assert isinstance(df["Data"].iloc[0], str)
+
+
+def test_date_columns_propagates_through_get_shortcut(httpx_mock):
+    """DATE_COLUMNS applies to ep.get() as well as ep.query().collect()."""
+    add_service_mocks(httpx_mock)
+    httpx_mock.add_response(
+        url=ENTITY_URL_PATTERN,
+        text=ODATA_QUERY_RESPONSE_MULTI_DATE_JSON,
+        status_code=200,
+    )
+    api = _SingleDateAPI()
+    ep = api.get_endpoint("ExpectativasMercadoAnuais")
+    df = ep.get(limit=1)
+    assert isinstance(df["Data"].iloc[0], datetime)
+    assert isinstance(df["DataVigencia"].iloc[0], str)