diff --git a/docs/api.rst b/docs/api.rst index 31f8f946..6fa69386 100644 --- a/docs/api.rst +++ b/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 ========= diff --git a/docs/examples/custom_agent.py b/docs/examples/custom_agent.py new file mode 100644 index 00000000..40e91165 --- /dev/null +++ b/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, []) + diff --git a/docs/howto.rst b/docs/howto.rst index 3b597227..cc3dca6a 100644 --- a/docs/howto.rst +++ b/docs/howto.rst @@ -22,7 +22,7 @@ Full example: :download:`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 `_ .. literalinclude:: examples/using_cookies.py @@ -102,16 +103,21 @@ access as `requests cookies ` -Agent Customization -------------------- +Customizing the Twisted Agent +----------------------------- -treq creates its own `twisted.web.client.Agent -`_ -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 ` diff --git a/treq/api.py b/treq/api.py index 069ca3cb..68bc77e6 100644 --- a/treq/api.py +++ b/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) diff --git a/treq/test/test_api.py b/treq/test/test_api.py index 9afcc8b1..1590d1da 100644 --- a/treq/test/test_api.py +++ b/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)