Document HTTP/1.1 API.

Author: Lukasa

docs/source/advanced.rst

@@ -13,25 +13,54 @@ may want to keep your connections alive only as long as you know you'll need
 them. In HTTP/2 this is generally not something you should do unless you're
 very confident you won't need the connection again anytime soon. However, if
 you decide you want to avoid keeping the connection open, you can use the
-:class:`HTTP20Connection <hyper.HTTP20Connection>` as a context manager::
+:class:`HTTP20Connection <hyper.HTTP20Connection>` and
+:class:`HTTP11Connection <hyper.HTTP11Connection>` as context managers::
 
     with HTTP20Connection('twitter.com:443') as conn:
         conn.request('GET', '/')
         data = conn.get_response().read()
 
     analyse(data)
 
-You may not use any :class:`HTTP20Response <hyper.HTTP20Response>` objects
-obtained from a connection after that connection is closed. Interacting with
-these objects when a connection has been closed is considered undefined
-behaviour.
+You may not use any :class:`HTTP20Response <hyper.HTTP20Response>` or
+:class:`HTTP11Response <hyper.HTTP11Response>` objects obtained from a
+connection after that connection is closed. Interacting with these objects when
+a connection has been closed is considered undefined behaviour.
+
+Chunked Responses
+-----------------
+
+Plenty of APIs return chunked data, and it's often useful to iterate directly
+over the chunked data. ``hyper`` lets you iterate over each data frame of a
+HTTP/2 response, and each chunk of a HTTP/1.1 response delivered with
+``Transfer-Encoding: chunked``::
+
+    for chunk in response.read_chunked():
+        do_something_with_chunk(chunk)
+
+There are some important caveats with this iteration: mostly, it's not
+guaranteed that each chunk will be non-empty. In HTTP/2, it's entirely legal to
+send zero-length data frames, and this API will pass those through unchanged.
+Additionally, by default this method will decompress a response that has a
+compressed ``Content-Encoding``: if you do that, each element of the iterator
+will no longer be a single chunk, but will instead be whatever the decompressor
+returns for that chunk.
+
+If that's problematic, you can set the ``decode_content`` parameter to
+``False`` and, if necessary, handle the decompression yourself::
+
+    for compressed_chunk in response.read_chunked(decode_content=False):
+        decompress(compressed_chunk)
+
+Very easy!
 
 Multithreading
 --------------
 
-Currently, ``hyper``'s :class:`HTTP20Connection <hyper.HTTP20Connection>` class
-is **not** thread-safe. Thread-safety is planned for ``hyper``'s core objects,
-but in this early alpha it is not a high priority.
+Currently, ``hyper``'s :class:`HTTP20Connection <hyper.HTTP20Connection>` and
+:class:`HTTP11Connection <hyper.HTTP11Connection>` classes are **not**
+thread-safe. Thread-safety is planned for ``hyper``'s core objects, but in this
+early alpha it is not a high priority.
 
 To use ``hyper`` in a multithreaded context the recommended thing to do is to
 place each connection in its own thread. Each thread should then have a request

docs/source/api.rst

@@ -19,6 +19,12 @@ Primary HTTP/2 Interface
 .. autoclass:: hyper.HTTP20Push
    :inherited-members:
 
+.. autoclass:: hyper.HTTP11Connection
+   :inherited-members:
+
+.. autoclass:: hyper.HTTP11Response
+   :inherited-members:
+
 Headers
 -------
 

docs/source/index.rst

@@ -26,7 +26,8 @@ Simple. ``hyper`` is written in 100% pure Python, which means no C extensions.
 For recent versions of Python (3.4 and onward, and 2.7.9 and onward) it's
 entirely self-contained with no external dependencies.
 
-``hyper`` supports Python 3.4 and Python 2.7.9.
+``hyper`` supports Python 3.4 and Python 2.7.9, and can speak HTTP/2 and
+HTTP/1.1.
 
 Caveat Emptor!
 --------------

docs/source/quickstart.rst

@@ -3,8 +3,10 @@
 Quickstart Guide
 ================
 
-First, congratulations on picking ``hyper`` for your HTTP/2 needs. ``hyper``
-is the premier (and, as far as we're aware, the only) Python HTTP/2 library.
+First, congratulations on picking ``hyper`` for your HTTP needs. ``hyper``
+is the premier (and, as far as we're aware, the only) Python HTTP/2 library,
+as well as a very servicable HTTP/1.1 library.
+
 In this section, we'll walk you through using ``hyper``.
 
 Installing hyper
@@ -46,8 +48,8 @@ instructions from the `cryptography`_ project, replacing references to
 
 .. _cryptography: https://cryptography.io/en/latest/installation/#installation
 
-Making Your First Request
--------------------------
+Making Your First HTTP/2 Request
+--------------------------------
 
 With ``hyper`` installed, you can start making HTTP/2 requests. At this
 stage, ``hyper`` can only be used with services that *definitely* support
@@ -109,6 +111,41 @@ For example::
 
 ``hyper`` will ensure that each response is matched to the correct request.
 
+Making Your First HTTP/1.1 Request
+-----------------------------------
+
+With ``hyper`` installed, you can start making HTTP/2 requests. At this
+stage, ``hyper`` can only be used with services that *definitely* support
+HTTP/2. Before you begin, ensure that whichever service you're contacting
+definitely supports HTTP/2. For the rest of these examples, we'll use
+Twitter.
+
+You can also use ``hyper`` to make HTTP/1.1 requests. The code is very similar.
+For example, to get the Twitter homepage::
+
+    >>> from hyper import HTTP11Connection
+    >>> c = HTTP11Connection('twitter.com:443')
+    >>> c.request('GET', '/')
+    >>> resp = c.get_response()
+
+The key difference between HTTP/1.1 and HTTP/2 is that when you make HTTP/1.1
+requests you do not get a stream ID. This is, of course, because HTTP/1.1 does
+not have streams.
+
+Things behave exactly like they do in the HTTP/2 case, right down to the data
+reading::
+
+    >>> resp.getheader('content-encoding')
+    'deflate'
+    >>> resp.headers
+    HTTPHeaderMap([(b'x-xss-protection', b'1; mode=block')...
+    >>> resp.status
+    200
+    >>> body = resp.read()
+    b'<!DOCTYPE html>\n<!--[if IE 8]><html clas ....
+
+That's all it takes.
+
 Requests Integration
 --------------------