feat: support configurable request methods

Author: IvanildoBarauna

src/api_to_dataframe/controller/client_builder.py

@@ -1,13 +1,15 @@
-from api_to_dataframe.models.retainer import retry_strategies, Strategies
+from typing import Any, Dict, Optional
+
 from api_to_dataframe.models.get_data import GetData
+from api_to_dataframe.models.retainer import Strategies, retry_strategies
 from api_to_dataframe.utils.logger import logger
 
 
-class ClientBuilder:
+class ClientBuilder:  # pylint: disable=too-many-instance-attributes
     def __init__(  # pylint: disable=too-many-positional-arguments,too-many-arguments
         self,
         endpoint: str,
-        headers: dict = None,
+        headers: Optional[Dict[str, str]] = None,
         retry_strategy: Strategies = Strategies.NO_RETRY_STRATEGY,
         retries: int = 3,
         initial_delay: int = 1,
@@ -57,6 +59,78 @@ def __init__(  # pylint: disable=too-many-positional-arguments,too-many-argument
         self.retries = retries
         self.delay = initial_delay
 
+        self._method: str = "GET"
+        self._params: Optional[Dict[str, Any]] = None
+        self._json_payload: Optional[Any] = None
+        self._data_payload: Optional[Any] = None
+        self._files_payload: Optional[Any] = None
+        self._auth: Optional[Any] = None
+        self._session: Optional[Any] = None
+
+    def with_method(self, method: str):
+        """Configure the HTTP method for the request."""
+
+        if not isinstance(method, str) or not method.strip():
+            error_msg = "method must be a non-empty string"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        self._method = method.strip().upper()
+        return self
+
+    def with_params(self, params: Optional[Dict[str, Any]]):
+        """Configure query parameters to be sent with the request."""
+
+        if params is not None and not isinstance(params, dict):
+            error_msg = "params must be a dictionary or None"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        self._params = params
+        return self
+
+    def with_payload(
+        self,
+        *,
+        json: Optional[Any] = None,
+        data: Optional[Any] = None,
+        files: Optional[Any] = None,
+    ):
+        """Configure payload content for the request body."""
+
+        self._json_payload = json
+        self._data_payload = data
+        self._files_payload = files
+        return self
+
+    def with_auth(self, auth: Optional[Any]):
+        """Configure authentication details for the request."""
+
+        self._auth = auth
+        return self
+
+    def with_session(self, session: Optional[Any]):
+        """Configure a custom session implementation for the request."""
+
+        if session is not None and not hasattr(session, "request"):
+            error_msg = "session must provide a request method"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        self._session = session
+        return self
+
+    def with_headers(self, headers: Optional[Dict[str, str]]):
+        """Override headers after initialization while keeping fluent style."""
+
+        if headers is not None and not isinstance(headers, dict):
+            error_msg = "headers must be a dictionary or None"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        self.headers = headers or {}
+        return self
+
     @retry_strategies
     def get_api_data(self):
         """
@@ -73,6 +147,13 @@ def get_api_data(self):
             endpoint=self.endpoint,
             headers=self.headers,
             connection_timeout=self.connection_timeout,
+            method=self._method,
+            params=self._params,
+            json=self._json_payload,
+            data=self._data_payload,
+            files=self._files_payload,
+            auth=self._auth,
+            session=self._session,
         )
 
         return response.json()

src/api_to_dataframe/models/get_data.py

@@ -1,21 +1,53 @@
-import requests
+from typing import Any, Dict, Optional
+
 import pandas as pd
+import requests
+
 from api_to_dataframe.utils.logger import logger
 
 
 class GetData:
     @staticmethod
-    def get_response(endpoint: str, headers: dict, connection_timeout: int):
-        # Make the request
-        response = requests.get(endpoint, timeout=connection_timeout, headers=headers)
+    def get_response(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        endpoint: str,
+        headers: Optional[Dict[str, str]],
+        connection_timeout: int,
+        method: str = "GET",
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Any] = None,
+        data: Optional[Any] = None,
+        files: Optional[Any] = None,
+        auth: Optional[Any] = None,
+        session: Optional[requests.Session] = None,
+    ):
+        """Execute an HTTP request and return the raw response."""
+
+        if not isinstance(method, str) or not method.strip():
+            error_msg = "method must be a non-empty string"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        request_callable = session.request if session else requests.request
+
+        response = request_callable(
+            method=method.upper(),
+            url=endpoint,
+            timeout=connection_timeout,
+            headers=headers,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            auth=auth,
+        )
 
-        # Attempt to raise for status to catch errors
         response.raise_for_status()
 
         return response
 
     @staticmethod
     def to_dataframe(response):
+        """Convert an API response payload into a pandas DataFrame."""
         df = pd.DataFrame(response)
 
         # Check if DataFrame is empty

tests/test_controller_client_builder.py

@@ -7,21 +7,15 @@
 
 @pytest.fixture()
 def client_setup():
+    """Create a default ClientBuilder instance for tests."""
     new_client = ClientBuilder(
         endpoint="https://economia.awesomeapi.com.br/last/USD-BRL"
     )
     return new_client
 
 
-@pytest.fixture()
-def response_setup():
-    new_client = ClientBuilder(
-        endpoint="https://economia.awesomeapi.com.br/last/USD-BRL"
-    )
-    return new_client.get_api_data()
-
-
 def test_constructor_raises():
+    """Ensure constructor validations raise errors for invalid inputs."""
     with pytest.raises(ValueError):
         ClientBuilder(endpoint="")
 
@@ -59,13 +53,14 @@ def test_constructor_raises():
 
 
 def test_constructor_with_param(client_setup):  # pylint: disable=redefined-outer-name
+    """Ensure constructor stores the provided endpoint value."""
     expected_result = "https://economia.awesomeapi.com.br/last/USD-BRL"
     new_client = client_setup
     assert new_client.endpoint == expected_result
 
 
 def test_constructor_with_headers():
-    """Test ClientBuilder with custom headers"""
+    """Test ClientBuilder with custom headers."""
     custom_headers = {"Authorization": "Bearer token123", "Content-Type": "application/json"}
     client = ClientBuilder(
         endpoint="https://economia.awesomeapi.com.br/last/USD-BRL",
@@ -75,7 +70,7 @@ def test_constructor_with_headers():
 
 
 def test_constructor_with_retry_strategy():
-    """Test ClientBuilder with different retry strategies"""
+    """Test ClientBuilder with different retry strategies."""
     client = ClientBuilder(
         endpoint="https://economia.awesomeapi.com.br/last/USD-BRL",
         retry_strategy=RetryStrategies.LINEAR_RETRY_STRATEGY,
@@ -87,20 +82,34 @@ def test_constructor_with_retry_strategy():
     assert client.delay == 2
 
 
+@responses.activate
 def test_response_to_json(client_setup):  # pylint: disable=redefined-outer-name
+    """Ensure API responses are converted to JSON objects."""
     new_client = client_setup
+    expected_response = {"key": "value"}
+
+    responses.add(
+        responses.GET,
+        new_client.endpoint,
+        json=expected_response,
+        status=200,
+    )
+
     response = new_client.get_api_data()  # pylint: disable=protected-access
     assert isinstance(response, dict)
+    assert response == expected_response
 
 
-def test_to_dataframe(response_setup):  # pylint: disable=redefined-outer-name
-    df = ClientBuilder.api_to_dataframe(response_setup)
+def test_to_dataframe():
+    """Ensure responses can be converted into DataFrames."""
+    sample_response = [{"currency": "USD", "bid": "5.0"}]
+    df = ClientBuilder.api_to_dataframe(sample_response)
     assert isinstance(df, pd.DataFrame)
 
 
 @responses.activate
 def test_get_api_data_with_mocked_response():
-    """Test get_api_data with mocked API response"""
+    """Test get_api_data with mocked API response."""
     endpoint = "https://api.test.com/data"
     expected_data = {"key": "value", "nested": {"id": 123}}
 
@@ -118,3 +127,77 @@ def test_get_api_data_with_mocked_response():
     assert response == expected_data
     assert len(responses.calls) == 1
     assert responses.calls[0].request.url == endpoint
+
+
+def test_with_method_configures_request_method():
+    """Ensure with_method configures the HTTP method for requests."""
+
+    client = ClientBuilder(endpoint="https://api.test.com").with_method("post")
+    assert client._method == "POST"  # pylint: disable=protected-access
+
+
+def test_with_params_validates_input_type():
+    """Ensure with_params only accepts dictionaries."""
+
+    client = ClientBuilder(endpoint="https://api.test.com")
+    assert client.with_params({"page": 1}) is client
+
+    with pytest.raises(ValueError):
+        client.with_params([("page", 1)])
+
+
+def test_with_payload_replaces_existing_payload():
+    """Ensure with_payload stores json, data and file payloads."""
+
+    client = ClientBuilder(endpoint="https://api.test.com")
+    client.with_payload(json={"name": "Jane"}, data=None)
+
+    assert client._json_payload == {"name": "Jane"}  # pylint: disable=protected-access
+    assert client._data_payload is None  # pylint: disable=protected-access
+
+
+def test_with_session_validates_interface():
+    """Ensure with_session requires an object exposing request."""
+
+    client = ClientBuilder(endpoint="https://api.test.com")
+
+    class DummySession:
+        """Expose a request method to mimic a real session."""
+
+        def request(self, **kwargs):  # pragma: no cover - dummy implementation
+            return kwargs
+
+    session = DummySession()
+    assert client.with_session(session) is client
+
+    with pytest.raises(ValueError):
+        client.with_session(object())
+
+
+@responses.activate
+def test_fluent_configuration_executes_request():
+    """Ensure fluent configuration works when executing requests."""
+
+    endpoint = "https://api.test.com/submit"
+    payload = {"name": "John"}
+    expected_response = {"status": "created"}
+
+    responses.add(
+        responses.POST,
+        endpoint,
+        json=expected_response,
+        status=201,
+    )
+
+    client = (
+        ClientBuilder(endpoint=endpoint)
+        .with_method("POST")
+        .with_payload(json=payload)
+        .with_params({"verbose": "true"})
+    )
+
+    response = client.get_api_data()
+
+    assert response == expected_response
+    assert responses.calls[0].request.method == "POST"
+    assert "verbose=true" in responses.calls[0].request.url