Open Concern about webservice module defaulting content_only to True in "base.requests"

[Ricardoalso]

Module

webservice

Describe the bug

Defaulting content_only to True in "base.requests" seems wrong IMHO.
A standard call to an endpoint self._request("GET", "/test") returns raw bytes instead of a typical HTTP response object

To Reproduce

Call _request(self, method, url=None, url_params=None, **kwargs)

Expected behavior
When calling _request we should get an HTTP response object

Additional context
Check originating PR #138 with the "Open Concern" section

Click to expand original PR content

**However** / **Open Concern**

Defaulting content_only to True in "base.requests" seems wrong IMHO (current PR follows the same pattern)

content_only = kwargs.pop("content_only", True)

The function returns two entirely different data types depending on a boolean flag. If content_only is True, it returns a bytes object (request.content). If content_only is False, it returns a requests.Response object (request).

Because it defaults to True, a standard call to an endpoint self._request("GET", "/test") returns raw bytes instead of a typical HTTP response object. To access network metadata (such as headers or cookies), the caller must explicitly pass content_only=False. This violates the Principle of Least Astonishment.

Open question ⚠️
Should we keep the current compatibility contract for now (defaulting to bytes)? In this addon, the default behavior has historically been “bytes content”, and existing tests + doc. assert this.

Wanting raw content as the "normal" case and wanting the actual HTTP Response object as a "special context." is strange, but I don't have the full context in here. In global network programming, a Response object is the baseline rule 🤔

All of Requests’ functionality can be accessed by these 7 methods. They all return an instance of the Response object.

https://requests.readthedocs.io/en/latest/api/#main-interface

@gurneyalex @simahawk @etobella