============
Response
============

The ``Response`` object is returned by all ``HttpClient`` request methods. It provides a unified
interface to access the status code, headers, body, and timing information of an HTTP response.

.. code-block:: python

   response = client.get("https://jsonplaceholder.typicode.com/todos/1")

   print(response.status_code)   # 200
   print(response.headers)       # {'Content-Type': 'application/json', ...}
   print(response.body)          # b'{\n  "userId": 1, ...}'
   print(response.elapsed)       # 0.123
   print(response.elapsed_time)  # 123

----

Attributes
----------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Attribute
     - Type
     - Description
   * - ``status_code``
     - ``int``
     - HTTP status code of the response (e.g. ``200``, ``404``).
   * - ``headers``
     - ``dict``
     - Dictionary of HTTP response headers.
   * - ``body``
     - ``bytes``
     - Raw response body as bytes.
   * - ``elapsed``
     - ``float``
     - Time taken to complete the request, in **seconds**. May be ``None`` if not measured.
   * - ``elapsed_time``
     - ``int``
     - Time taken to complete the request, in **milliseconds**. Derived from ``elapsed``. Returns ``None`` if ``elapsed`` is not available.

.. note::

   ``elapsed`` and ``elapsed_time`` represent the same duration in different units.
   Use ``elapsed`` for precise float arithmetic and ``elapsed_time`` for display purposes.

----

Methods
-------

text()
~~~~~~

Returns the response body decoded as a UTF-8 string.

.. code-block:: python

   print(response.text())  # '{\n  "userId": 1, ...}'

**Returns:** ``str``

----

json()
~~~~~~

Parses and returns the response body as a JSON object.

.. code-block:: python

   data = response.json()
   print(data["userId"])  # 1

**Returns:** ``Any`` — the parsed JSON value (dict, list, str, int, etc.)

**Raises:** ``ValueError`` if the response body is not valid JSON.

.. code-block:: python

   try:
       data = response.json()
   except ValueError:
       print("Response is not valid JSON")

----

is_ok()
~~~~~~~

Returns ``True`` if the status code is in the ``2xx`` range, ``False`` otherwise.

.. code-block:: python

   if response.is_ok():
       print("Request succeeded")
   else:
       print("Request failed with status:", response.status_code)

**Returns:** ``bool``

----

raise_for_status()
~~~~~~~~~~~~~~~~~~

Raises an exception if the status code indicates a client error (``4xx``) or server
error (``5xx``). Does nothing for ``2xx`` and ``3xx`` responses.

.. code-block:: python

   response = client.get("https://example.com/not-found")
   response.raise_for_status()  # raises Exception: HTTP Error: 404

**Raises:** ``Exception`` with the message ``HTTP Error: <status_code>``.

.. warning::

   The behavior of ``raise_for_status()`` differs from the ``requests`` library.
   In ``requests``, it raises an ``HTTPError`` with a detailed message including the
   URL and reason phrase. In ``lightreq``, it raises a plain ``Exception`` with only
   the status code. Avoid using bare ``except Exception`` alongside this method, as it
   may silently catch unrelated errors.

----

Usage Patterns
--------------

Checking success before processing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   response = client.get("https://api.example.com/data")

   if response.is_ok():
       data = response.json()
   else:
       print("Unexpected status:", response.status_code)

Guard with raise_for_status
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   try:
       response = client.get("https://api.example.com/data")
       response.raise_for_status()
       data = response.json()
   except Exception as e:
       print("Request failed:", e)

Inspecting timing
~~~~~~~~~~~~~~~~~

.. code-block:: python

   response = client.get("https://api.example.com/data")

   print(f"Completed in {response.elapsed_time} ms")  # e.g. "Completed in 123 ms"