Phase 5: API Consistency

- URL construction: _currency_url() now uses urllib.parse.urlencode instead of
  f-string query params for better consistency and maintainability
- OData API: Endpoint.get() now accepts explicit typed kwargs for filter,
  orderby, select, limit, skip, verbose, and output; maintains backwards
  compatibility with positional *args dispatch
- All validation checks passing: 24 tests, ruff format/check, mypy

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: wilsonfreitas

bcb/currency.py

@@ -5,6 +5,7 @@
 from datetime import date, timedelta
 from io import BytesIO, StringIO
 from typing import TYPE_CHECKING, Dict, List, Literal, NamedTuple, Union, overload
+from urllib.parse import urlencode
 
 import numpy as np
 import pandas as pd
@@ -30,11 +31,15 @@
 def _currency_url(currency_id: int, start_date: DateInput, end_date: DateInput) -> str:
     start_date = Date(start_date)
     end_date = Date(end_date)
-    return (
-        f"https://ptax.bcb.gov.br/ptax_internet/consultaBoletim.do?"
-        f"method=gerarCSVFechamentoMoedaNoPeriodo&"
-        f"ChkMoeda={currency_id}&DATAINI={start_date.date:%d/%m/%Y}&DATAFIM={end_date.date:%d/%m/%Y}"
+    params = urlencode(
+        {
+            "method": "gerarCSVFechamentoMoedaNoPeriodo",
+            "ChkMoeda": currency_id,
+            "DATAINI": start_date.date.strftime("%d/%m/%Y"),
+            "DATAFIM": end_date.date.strftime("%d/%m/%Y"),
+        }
     )
+    return f"https://ptax.bcb.gov.br/ptax_internet/consultaBoletim.do?{params}"
 
 
 class _CacheKey(NamedTuple):

bcb/odata/api.py

@@ -120,48 +120,78 @@ def __init__(
         self._url = url
         self._date_columns: list[str] = date_columns or []
 
-    def get(self, *args: Any, **kwargs: Any) -> Union[pd.DataFrame, str]:
+    def get(
+        self,
+        *args: Any,
+        filter: Optional[ODataPropertyFilter] = None,
+        orderby: Optional[ODataPropertyOrderBy] = None,
+        select: Optional[ODataProperty] = None,
+        limit: Optional[int] = None,
+        skip: Optional[int] = None,
+        output: str = "dataframe",
+        verbose: bool = False,
+        **kwargs: Any,
+    ) -> Union[pd.DataFrame, str]:
         """
         Executa a consulta na API OData e retorna o resultado.
 
         Parameters
         ----------
-        *args : argumentos para a consulta
-
-        **kwargs : argumentos para a consulta. Use ``output='text'`` to get
-            the raw OData JSON response string instead of a DataFrame.
+        *args : argumentos para a consulta (ODataPropertyFilter, ODataPropertyOrderBy, ODataProperty)
+        filter : ODataPropertyFilter, optional
+            Filter condition for the query
+        orderby : ODataPropertyOrderBy, optional
+            Order by condition for the query
+        select : ODataProperty, optional
+            Properties to select from the query
+        limit : int, optional
+            Limit the number of results
+        skip : int, optional
+            Skip the first N results
+        output : str, default "dataframe"
+            Output format. Use ``'text'`` to get the raw OData JSON response
+            string instead of a DataFrame.
+        verbose : bool, default False
+            Print the query before executing it
+        **kwargs : argumentos adicionais para a consulta
 
         Returns
         -------
         pd.DataFrame or str: resultado da consulta. Returns a DataFrame by
             default; returns a raw JSON string when ``output='text'``.
         """
         _query = EndpointQuery(self._entity, self._url, self._date_columns)
+
+        # Apply explicit kwargs first
+        if filter is not None:
+            _query.filter(filter)
+        if orderby is not None:
+            _query.orderby(orderby)
+        if select is not None:
+            _query.select(select)
+        if limit is not None:
+            _query.limit(limit)
+        if skip is not None:
+            _query.skip(skip)
+
+        # Apply positional args for backwards compatibility
         for arg in args:
             if isinstance(arg, ODataPropertyFilter):
                 _query.filter(arg)
             elif isinstance(arg, ODataPropertyOrderBy):
                 _query.orderby(arg)
             elif isinstance(arg, ODataProperty):
                 _query.select(arg)
-        verbose = False
-        output_format = "dataframe"
+
+        # Apply any remaining kwargs as query parameters
         for k, val in kwargs.items():
-            if k == "limit":
-                _query.limit(val)
-            elif k == "skip":
-                _query.skip(val)
-            elif k == "verbose":
-                verbose = val
-            elif k == "output":
-                output_format = val
-            else:
-                _query.parameters(**{k: val})
+            _query.parameters(**{k: val})
+
         _query.format("application/json")
 
         if verbose:
             _query.show()
-        if output_format == "text":
+        if output == "text":
             data = _query.collect(output="text")
         else:
             data = _query.collect()