Emphasize client

docs/api.rst

@@ -1,6 +1,11 @@
 Making Requests
 ===============
 
+The :py:mod:`treq` module provides several shortcut functions for making
+requests.  These functions all create a default 
+:py:class:`treq.client.HTTPClient` instance and pass their arguments to
+the appropriate :py:class:`~treq.client.HTTPClient` method.
+
 .. module:: treq
 
 .. autofunction:: request
@@ -19,6 +24,16 @@ Accessing Content
 .. autofunction:: text_content
 .. autofunction:: json_content
 
+The HTTP Client
+===============
+
+.. module:: treq.client
+
+.. class:: HTTPClient(agent, cookiejar=None, data_to_body_producer=IBodyProducer)
+
+:py:class:`~treq.client.HTTPClient` has methods that match the signatures of the
+shortcut request functions in the :py:mod:`treq` module.
+
 Responses
 =========
 

docs/examples/custom_agent.py

@@ -0,0 +1,19 @@
+from treq.client import HTTPClient
+from _utils import print_response
+from twisted.internet.task import react
+from twisted.web.client import Agent
+
+def make_custom_agent(reactor):
+    return Agent(reactor)
+
+def main(reactor, *args):
+    agent = make_custom_agent(reactor)
+    http_client = HTTPClient(agent)
+    d = http_client.get(
+        'https://secure.example.net/area51',
+        auth=('admin', "you'll never guess!"))
+    d.addCallback(print_response)
+    return d
+
+react(main, [])
+

docs/howto.rst

@@ -22,7 +22,7 @@ Full example: :download:`download_file.py <examples/download_file.py>`
 Query Parameters
 ----------------
 
-:py:func:`treq.request` supports a ``params`` keyword argument which will
+:py:func:`treq.HTTPClient.request` supports a ``params`` keyword argument which will
 be urlencoded and added to the ``url`` argument in addition to any query
 parameters that may already exist.
 
@@ -91,9 +91,10 @@ Cookies
 
 Cookies can be set by passing a ``dict`` or ``cookielib.CookieJar`` instance
 via the ``cookies`` keyword argument.  Later cookies set by the server can be
-retrieved using the :py:func:`treq.cookies` function.
+retrieved using the :py:meth:`~treq.response.Response.cookies` method of the 
+response.
 
-The the object returned by :py:func:`treq.cookies` supports the same key/value
+The the object returned by :py:meth:`~treq.Response.cookies` supports the same key/value
 access as `requests cookies <http://requests.readthedocs.org/en/latest/user/quickstart/#cookies>`_
 
 .. literalinclude:: examples/using_cookies.py
@@ -102,16 +103,21 @@ access as `requests cookies <http://requests.readthedocs.org/en/latest/user/quic
 
 Full example: :download:`using_cookies.py <examples/using_cookies.py>`
 
-Agent Customization
--------------------
+Customizing the Twisted Agent
+-----------------------------
 
-treq creates its own `twisted.web.client.Agent
-<https://twistedmatrix.com/documents/current/api/twisted.web.client.Agent.html>`_
-with reasonable defaults, but you may want to provide your own custom agent.
-A custom agent can be passed to the various treq request methods using the
-``agent`` keyword argument.
+The main :py:mod:`treq` module has helper functions that automatically instantiate
+an instance of :py:class:`treq.client.HTTPClient`.  You can create an instance
+of :py:class:`~treq.client.HTTPClient` directly in order to customize the 
+paramaters used to initialize it.
+Internally, the :py:class:`~treq.client.HTTPClient` wraps an instance of 
+:py:class:`twisted.web.client.Agent`.  When you create an instance of 
+:py:class:`~treq.client.HTTPClient`, you must initialize it with an instance of
+:py:class:`~twisted.web.client.Agent`.  This allows you to customize its
+behavior.
 
-.. code-block:: python
+.. literalinclude:: examples/custom_agent.py
+    :linenos:
+    :lines: 6-19
 
-    custom_agent = Agent(reactor, connectTimeout=42)
-    treq.get(url, agent=custom_agent)
+Full example: :download:`custom_agent.py <examples/custom_agent.py>`

treq/api.py

@@ -106,11 +106,9 @@ def request(method, url, **kwargs):
 #
 
 def _client(*args, **kwargs):
-    agent = kwargs.get('agent')
-    if agent is None:
-        reactor = default_reactor(kwargs.get('reactor'))
-        pool = default_pool(reactor,
-                            kwargs.get('pool'),
-                            kwargs.get('persistent'))
-        agent = Agent(reactor, pool=pool)
+    reactor = default_reactor(kwargs.get('reactor'))
+    pool = default_pool(reactor,
+                        kwargs.get('pool'),
+                        kwargs.get('persistent'))
+    agent = Agent(reactor, pool=pool)
     return HTTPClient(agent)

treq/test/test_api.py

@@ -1,6 +1,7 @@
 import mock
 
 from treq.test.util import TestCase
+
 import treq
 from treq._utils import set_global_pool
 
@@ -43,11 +44,3 @@ def test_cached_pool(self):
         treq.get('http://test.com')
 
         self.Agent.assert_called_with(mock.ANY, pool=pool)
-
-    def test_custom_agent(self):
-        """
-        A custom Agent is used if specified.
-        """
-        custom_agent = mock.Mock()
-        treq.get('https://www.example.org/', agent=custom_agent)
-        self.HTTPClient.assert_called_with(custom_agent)