Expand API docs and add missing test coverage

.gitignore

@@ -5,6 +5,7 @@
 _build
 build
 dist
+/docs/html
 MANIFEST
 .coverage
 coverage

README.rst

@@ -64,17 +64,15 @@ Lint:
     pep8 treq
     pyflakes treq
 
-Build docs:
+Build docs::
 
-::
-
-    cd docs; make html
+    tox -e docs
 
-.. |build| image:: https://secure.travis-ci.org/twisted/treq.svg?branch=master
-.. _build: http://travis-ci.org/twisted/treq
+.. |build| image:: https://api.travis-ci.org/twisted/treq.svg?branch=master
+.. _build: https://travis-ci.org/twisted/treq
 
 .. |coverage| image:: https://codecov.io/github/twisted/treq/coverage.svg?branch=master
 .. _coverage: https://codecov.io/github/twisted/treq
 
-.. |pypi| image:: http://img.shields.io/pypi/v/treq.svg
+.. |pypi| image:: https://img.shields.io/pypi/v/treq.svg
 .. _pypi: https://pypi.python.org/pypi/treq

docs/api.rst

@@ -1,5 +1,10 @@
+API Reference
+=============
+
+This page lists all of the interfaces exposed by the `treq` package.
+
 Making Requests
-===============
+---------------
 
 .. module:: treq
 
@@ -12,73 +17,63 @@ Making Requests
 .. autofunction:: delete
 
 Accessing Content
-=================
+-----------------
 
 .. autofunction:: collect
 .. autofunction:: content
 .. autofunction:: text_content
 .. autofunction:: json_content
 
-Responses
-=========
-
-.. module:: treq.response
-
-.. class:: Response
-
-    .. method:: collect(collector)
-
-        Incrementally collect the body of the response.
-
-        :param collector: A single argument callable that will be called
-            with chunks of body data as it is received.
+HTTPClient Objects
+------------------
 
-        :returns: A `Deferred` that fires when the entire body has been
-            received.
+.. module:: treq.client
 
-    .. method:: content()
+The :class:`treq.client.HTTPClient` class provides the same interface as the :mod:`treq` module itself.
 
-        Read the entire body all at once.
+.. autoclass:: HTTPClient
+    :members:
+    :undoc-members:
 
-        :returns: A `Deferred` that fires with a `bytes` object when the entire
-            body has been received.
+Augmented Response Objects
+--------------------------
 
-    .. method:: text(encoding='ISO-8859-1')
+:func:`treq.request`, :func:`treq.get`, etc. return an object which implements :class:`twisted.web.iweb.IResponse`, plus a few additional convenience methods:
 
-        Read the entire body all at once as text.
-        :param encoding: An encoding for the body, if none is given the
-            encoding will be guessed, defaulting to this argument.
-
-        :returns: A `Deferred` that fires with a `unicode` object when the
-            entire body has been received.
-
-    .. method:: json()
+.. module:: treq.response
 
-        Read the entire body all at once and decode it as JSON.
+.. class:: _Response
 
-        :returns: A `Deferred` that fires with the result of `json.loads` on
-            the body after it has been received.
+    .. automethod:: collect
+    .. automethod:: content
+    .. automethod:: json
+    .. automethod:: text
+    .. automethod:: history
+    .. automethod:: cookies
 
-    .. method:: history()
+    Inherited from :class:`twisted.web.iweb.IResponse`:
 
-        Get a list of all responses that (such as intermediate redirects),
-        that ultimately ended in the current response.
+    :ivar version:
+    :ivar code:
+    :ivar phrase:
+    :ivar headers:
+    :ivar length:
+    :ivar request:
+    :ivar previousResponse:
 
-        :returns: A `list` of :class:`treq.response.Response` objects.
+    .. method:: deliverBody(protocol)
+    .. method:: setPreviousResponse(response)
 
-    .. method:: cookies()
+Test Helpers
+------------
 
-        :returns: A `CookieJar`.
+.. automodule:: treq.testing
+    :members:
 
-    Inherited from twisted.web.iweb.IResponse.
+MultiPartProducer Objects
+-------------------------
 
-    .. attribute:: version
-    .. attribute:: code
-    .. attribute:: phrase
-    .. attribute:: headers
-    .. attribute:: length
-    .. attribute:: request
-    .. attribute:: previousResponse
+:class:`treq.multipart.MultiPartProducer` is used internally when making requests which involve files.
 
-    .. method:: deliverBody(protocol)
-    .. method:: setPreviousResponse(response)
+.. automodule:: treq.multipart
+    :members:

docs/conf.py

@@ -25,7 +25,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc']
+extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -48,7 +48,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = open('../treq/_version').readline().strip()
+from treq import __version__ as release
 version = '.'.join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
@@ -241,3 +241,8 @@
 #texinfo_show_urls = 'footnote'
 
 RTD_NEW_THEME = True
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3.5', None),
+    'twisted': ('https://twistedmatrix.com/documents/current/api/', None),
+}

docs/howto.rst

@@ -1,16 +1,18 @@
+Use Cases
+=========
+
 Handling Streaming Responses
 ----------------------------
 
-In addition to `receiving responses <http://twistedmatrix.com/documents/current/web/howto/client.html#auto4>`_
-with ``IResponse.deliverBody``.
-
-treq provides a helper function :py:func:`treq.collect` which takes a
-``response``, and a single argument function which will be called with all new
-data available from the response.  Much like ``IProtocol.dataReceived``,
+In addition to `receiving responses <https://twistedmatrix.com/documents/current/web/howto/client.html#receiving-responses>`_
+with :meth:`IResponse.deliverBody`, treq provides a helper function
+:py:func:`treq.collect` which takes a
+``response`` and a single argument function which will be called with all new
+data available from the response.  Much like :meth:`IProtocol.dataReceived`,
 :py:func:`treq.collect` knows nothing about the framing of your data and will
 simply call your collector function with any data that is currently available.
 
-Here is an example which simply a ``file`` object's write method to
+Here is an example which simply a file object's write method to
 :py:func:`treq.collect` to save the response body to a file.
 
 .. literalinclude:: examples/download_file.py
@@ -23,7 +25,7 @@ Query Parameters
 ----------------
 
 :py:func:`treq.request` supports a ``params`` keyword argument which will
-be urlencoded and added to the ``url`` argument in addition to any query
+be URL-encoded and added to the ``url`` argument in addition to any query
 parameters that may already exist.
 
 The ``params`` argument may be either a ``dict`` or a ``list`` of
@@ -41,7 +43,7 @@ Full example: :download:`query_params.py <examples/query_params.py>`
 Auth
 ----
 
-HTTP Basic authentication as specified in `RFC 2617`_ is easily supported by
+HTTP Basic authentication as specified in :rfc:`2617` is easily supported by
 passing an ``auth`` keyword argument to any of the request functions.
 
 The ``auth`` argument should be a tuple of the form ``('username', 'password')``.
@@ -52,8 +54,6 @@ The ``auth`` argument should be a tuple of the form ``('username', 'password')``
 
 Full example: :download:`basic_auth.py <examples/basic_auth.py>`
 
-.. _RFC 2617: http://www.ietf.org/rfc/rfc2617.txt
-
 Redirects
 ---------
 
@@ -77,7 +77,7 @@ any of the request methods.
 Full example: :download:`disable_redirects.py <examples/disable_redirects.py>`
 
 You can even access the complete history of treq response objects by calling
-the `history()` method on the the response.
+the :meth:`~treq.response._Response.history()` method on the response.
 
 .. literalinclude:: examples/response_history.py
     :linenos:
@@ -91,10 +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.
 
-The the object returned by :py:func:`treq.cookies` supports the same key/value
-access as `requests cookies <http://requests.readthedocs.org/en/latest/user/quickstart/#cookies>`_
+The object returned by :py:meth:`~treq.response._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
     :linenos:

docs/index.rst

@@ -1,16 +1,16 @@
 treq: High-level Twisted HTTP Client API
 ========================================
 
-treq depends on Twisted 12.3.0 or later and optionally pyOpenSSL.
-Python 3 support requires at least Twisted 15.5.
+treq depends on Twisted 16.0.0 or later and optionally pyOpenSSL.
+It functions on Python 2.7 and Python 3.3+.
 
 Why?
 ----
 
 `requests`_ by `Kenneth Reitz`_ is a wonderful library.
 I want the same ease of use when writing Twisted applications.
 treq is not of course a perfect clone of `requests`.
-I have tried to stay true to the do-what-I-mean spirit of the `requests` API and also kept the API familiar to users of `Twisted`_ and ``twisted.web.client.Agent`` on which treq is based.
+I have tried to stay true to the do-what-I-mean spirit of the `requests` API and also kept the API familiar to users of `Twisted`_ and :class:`twisted.web.client.Agent` on which treq is based.
 
 .. _requests: http://python-requests.org/
 .. _Kenneth Reitz: https://www.gittip.com/kennethreitz/
@@ -28,7 +28,7 @@ GET
 
 .. literalinclude:: examples/basic_get.py
     :linenos:
-    :lines: 7-11
+    :lines: 7-10
 
 Full example: :download:`basic_get.py <examples/basic_get.py>`
 
@@ -45,17 +45,17 @@ Full example: :download:`basic_post.py <examples/basic_post.py>`
 Why not 100% requests-alike?
 ----------------------------
 
-Initially when I started off working on treq I thought the API should look exactly like `requests`_ except anything that would involve the network would return a ``Deferred``.
+Initially when I started off working on treq I thought the API should look exactly like `requests`_ except anything that would involve the network would return a `Deferred`.
 
 Over time while attempting to mimic the `requests`_ API it became clear that not enough code could be shared between `requests`_ and treq for it to be worth the effort to translate many of the usage patterns from `requests`_.
 
 With the current version of treq I have tried to keep the API simple, yet remain familiar to users of Twisted and its lower-level HTTP libraries.
 
 
-Feature Parity w/ Requests
---------------------------
+Feature Parity with Requests
+----------------------------
 
-Even though mimicing the `requests`_ API is not a goal, supporting most of it's features is.
+Even though mimicking the `requests`_ API is not a goal, supporting most of its features is.
 Here is a list of `requests`_ features and their status in treq.
 
 +----------------------------------+----------+----------+
@@ -92,21 +92,14 @@ Here is a list of `requests`_ features and their status in treq.
 | Python 3.x                       | yes      | yes      |
 +----------------------------------+----------+----------+
 
-Howto
------
+Table of Contents
+-----------------
 
 .. toctree::
     :maxdepth: 3
 
     howto
-
-API Documentation
------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   api
+    api
 
 Indices and tables
 ==================

setup.py

@@ -44,6 +44,6 @@
         classifiers=classifiers,
         description="A requests-like API built on top of twisted.web's Agent",
         license="MIT/X",
-        url="http://github.com/twisted/treq",
+        url="https://github.com/twisted/treq",
         long_description=readme
     )

src/treq/api.py

@@ -101,6 +101,9 @@ def request(method, url, **kwargs):
         (i.e. Ignore  RFC2616 section 10.3 and follow redirects from
         POST requests).  Default: ``False``
 
+    :param bool unbuffered: Pass ``True`` to to disable response buffering.  By
+        default treq buffers the entire response body in memory.
+
     :rtype: Deferred that fires with an IResponse provider.
 
     """