|
| 1 | +.. _user: |
| 2 | + |
| 3 | +Quickstart Guide |
| 4 | +================ |
| 5 | + |
| 6 | +First, congratulations on picking ``hyper`` for your HTTP/2.0 needs. ``hyper`` |
| 7 | +is the premier (and, as far as we're aware, the only) Python HTTP/2.0 library. |
| 8 | +In this section, we'll walk you through using ``hyper``. |
| 9 | + |
| 10 | +Installing hyper |
| 11 | +---------------- |
| 12 | + |
| 13 | +To begin, you will need to install ``hyper``. This can be done like so: |
| 14 | + |
| 15 | +.. code-block:: bash |
| 16 | +
|
| 17 | + $ pip install hyper |
| 18 | +
|
| 19 | +If ``pip`` is not available to you, you can try: |
| 20 | + |
| 21 | +.. code-block:: bash |
| 22 | +
|
| 23 | + $ easy_install hyper |
| 24 | +
|
| 25 | +If that fails, download the library from its GitHub page and install it using: |
| 26 | + |
| 27 | +.. code-block:: bash |
| 28 | +
|
| 29 | + $ python setup.py install |
| 30 | +
|
| 31 | +Installation Requirements |
| 32 | +~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 33 | + |
| 34 | +Due to limitations in the Python standard library, ``hyper`` supports a very |
| 35 | +limited range of Python versions. Currently, that means you'll need to be using |
| 36 | +Python 3.3 or higher to use ``hyper``. Other than that, there are no other |
| 37 | +requirements for using ``hyper``. |
| 38 | + |
| 39 | +Making Your First Request |
| 40 | +------------------------- |
| 41 | + |
| 42 | +With ``hyper`` installed, you can start making HTTP/2.0 requests. At this |
| 43 | +stage, ``hyper`` can only be used with services that *definitely* support |
| 44 | +HTTP/2.0. Before you begin, ensure that whichever service you're contacting |
| 45 | +definitely supports HTTP/2.0. For the rest of these examples, we'll use |
| 46 | +Twitter. |
| 47 | + |
| 48 | +Begin by getting the Twitter homepage:: |
| 49 | + |
| 50 | + >>> from hyper import HTTP20Connection |
| 51 | + >>> c = HTTP20Connection('twitter.com:443') |
| 52 | + >>> c.request('GET', '/') |
| 53 | + 1 |
| 54 | + >>> resp = c.getresponse() |
| 55 | + |
| 56 | +Used in this way, ``hyper`` behaves exactly like ``http.client``. You can make |
| 57 | +sequential requests using the exact same API you're accustomed to. The only |
| 58 | +difference is that |
| 59 | +:meth:`HTTP20Connection.request() <hyper.HTTP20Connection.request>` returns a |
| 60 | +value, unlike the equivalent ``http.client`` function. The return value is the |
| 61 | +HTTP/2.0 *stream identifier*. If you're planning to use ``hyper`` in this very |
| 62 | +simple way, you can choose to ignore it, but it's potentially useful. We'll |
| 63 | +come back to it. |
| 64 | + |
| 65 | +Once you've got the data, things continue to behave exactly like |
| 66 | +``http.client``:: |
| 67 | + |
| 68 | + >>> resp.getheader('content-encoding') |
| 69 | + 'deflate' |
| 70 | + >>> resp.getheaders() |
| 71 | + [('x-xss-protection', '1; mode=block')... |
| 72 | + >>> resp.status |
| 73 | + 200 |
| 74 | + |
| 75 | +Based on the ``Content-Encoding`` header, we know that the body is compressed. |
| 76 | +Currently, ``hyper`` doesn't support decoding that body, so you'll need to do |
| 77 | +it yourself:: |
| 78 | + |
| 79 | + >>> body = resp.read() |
| 80 | + >>> import zlib |
| 81 | + >>> zlib.decompress(body) |
| 82 | + b'<!DOCTYPE html>\n<!--[if IE 8]><html clas .... |
| 83 | + |
| 84 | +That's all it takes. |
| 85 | + |
| 86 | +Streams |
| 87 | +------- |
| 88 | + |
| 89 | +In HTTP/2.0, connections are divided into multiple streams. Each stream carries |
| 90 | +a single request-response pair. You may start multiple requests before reading |
| 91 | +the response from any of them, and switch between them using their stream IDs. |
| 92 | + |
| 93 | +For example:: |
| 94 | + |
| 95 | + >>> from hyper import HTTP20Connection |
| 96 | + >>> c = HTTP20Connection('twitter.com:443') |
| 97 | + >>> first = c.request('GET', '/') |
| 98 | + >>> second = c.request('GET', '/lukasaoz') |
| 99 | + >>> third = c.request('GET', '/about') |
| 100 | + >>> second_response = c.getresponse(second) |
| 101 | + >>> first_response = c.getresponse(first) |
| 102 | + >>> third_response = c.getresponse(third) |
| 103 | + |
| 104 | +``hyper`` will ensure that each response is matched to the correct request. |
0 commit comments