Usage
=====

Installation
------------

req2 can be installed using pip:

.. code-block::

  pip install req2

Quick start
-----------

.. code-block:: python
  
  import req2
  
  response = req2.get("https://example.com", timeout=5)
  response.raise_for_status()
  print("Status:", response.status_code)
  print("DNS lookup took", response.timings["dns"], "seconds")

Sessions mirror the familiar :mod:`requests` API:

.. code-block:: python

  import req2

  with req2.session() as session:
    session.params["api_key"] = "secret"
    session.headers["User-Agent"] = "req2-example"
    result = session.post("https://api.example.com/items", json={"name": "widget", "price": 10.0})
    result.raise_for_status()
    print(result.json())

A sample get request:

.. code-block:: python

  import req2

  url = "https://example.com/get"
  headers = {"accept": "application/json"}

  response = req2.get(url, headers=headers)

  print("Status:", response.status_code)
  print("JSON response:", response.json())
  print("All response times:", response.timings)

Streaming downloads
-------------------

When ``stream=True`` is supplied, ``req2`` stores the body in a spool file so
that large responses do not exhaust memory. The data remains available via
``Response.raw`` or ``Response.iter_content``:

.. code-block:: python

  response = req2.get("https://example.com/large", stream=True)
  for chunk in response.iter_content(chunk_size=8192):
    process(chunk)

After the stream has been consumed, ``Response.content`` caches the full body in
memory to match Requests semantics.

Redirects and cookies
---------------------

``req2`` follows redirects and maintains cookies in a :class:`http.cookiejar.CookieJar`
attached to the session. Hooks, authentication callbacks, multipart form uploads,
JSON payloads, and environment-aware proxies are all supported.