|
jpayne@69
|
1 Metadata-Version: 2.1
|
|
jpayne@69
|
2 Name: h11
|
|
jpayne@69
|
3 Version: 0.14.0
|
|
jpayne@69
|
4 Summary: A pure-Python, bring-your-own-I/O implementation of HTTP/1.1
|
|
jpayne@69
|
5 Home-page: https://github.com/python-hyper/h11
|
|
jpayne@69
|
6 Author: Nathaniel J. Smith
|
|
jpayne@69
|
7 Author-email: njs@pobox.com
|
|
jpayne@69
|
8 License: MIT
|
|
jpayne@69
|
9 Classifier: Development Status :: 3 - Alpha
|
|
jpayne@69
|
10 Classifier: Intended Audience :: Developers
|
|
jpayne@69
|
11 Classifier: License :: OSI Approved :: MIT License
|
|
jpayne@69
|
12 Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
jpayne@69
|
13 Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
jpayne@69
|
14 Classifier: Programming Language :: Python :: 3
|
|
jpayne@69
|
15 Classifier: Programming Language :: Python :: 3 :: Only
|
|
jpayne@69
|
16 Classifier: Programming Language :: Python :: 3.7
|
|
jpayne@69
|
17 Classifier: Programming Language :: Python :: 3.8
|
|
jpayne@69
|
18 Classifier: Programming Language :: Python :: 3.9
|
|
jpayne@69
|
19 Classifier: Programming Language :: Python :: 3.10
|
|
jpayne@69
|
20 Classifier: Topic :: Internet :: WWW/HTTP
|
|
jpayne@69
|
21 Classifier: Topic :: System :: Networking
|
|
jpayne@69
|
22 Requires-Python: >=3.7
|
|
jpayne@69
|
23 License-File: LICENSE.txt
|
|
jpayne@69
|
24 Requires-Dist: typing-extensions ; python_version < "3.8"
|
|
jpayne@69
|
25
|
|
jpayne@69
|
26 h11
|
|
jpayne@69
|
27 ===
|
|
jpayne@69
|
28
|
|
jpayne@69
|
29 .. image:: https://travis-ci.org/python-hyper/h11.svg?branch=master
|
|
jpayne@69
|
30 :target: https://travis-ci.org/python-hyper/h11
|
|
jpayne@69
|
31 :alt: Automated test status
|
|
jpayne@69
|
32
|
|
jpayne@69
|
33 .. image:: https://codecov.io/gh/python-hyper/h11/branch/master/graph/badge.svg
|
|
jpayne@69
|
34 :target: https://codecov.io/gh/python-hyper/h11
|
|
jpayne@69
|
35 :alt: Test coverage
|
|
jpayne@69
|
36
|
|
jpayne@69
|
37 .. image:: https://readthedocs.org/projects/h11/badge/?version=latest
|
|
jpayne@69
|
38 :target: http://h11.readthedocs.io/en/latest/?badge=latest
|
|
jpayne@69
|
39 :alt: Documentation Status
|
|
jpayne@69
|
40
|
|
jpayne@69
|
41 This is a little HTTP/1.1 library written from scratch in Python,
|
|
jpayne@69
|
42 heavily inspired by `hyper-h2 <https://hyper-h2.readthedocs.io/>`_.
|
|
jpayne@69
|
43
|
|
jpayne@69
|
44 It's a "bring-your-own-I/O" library; h11 contains no IO code
|
|
jpayne@69
|
45 whatsoever. This means you can hook h11 up to your favorite network
|
|
jpayne@69
|
46 API, and that could be anything you want: synchronous, threaded,
|
|
jpayne@69
|
47 asynchronous, or your own implementation of `RFC 6214
|
|
jpayne@69
|
48 <https://tools.ietf.org/html/rfc6214>`_ -- h11 won't judge you.
|
|
jpayne@69
|
49 (Compare this to the current state of the art, where every time a `new
|
|
jpayne@69
|
50 network API <https://trio.readthedocs.io/>`_ comes along then someone
|
|
jpayne@69
|
51 gets to start over reimplementing the entire HTTP protocol from
|
|
jpayne@69
|
52 scratch.) Cory Benfield made an `excellent blog post describing the
|
|
jpayne@69
|
53 benefits of this approach
|
|
jpayne@69
|
54 <https://lukasa.co.uk/2015/10/The_New_Hyper/>`_, or if you like video
|
|
jpayne@69
|
55 then here's his `PyCon 2016 talk on the same theme
|
|
jpayne@69
|
56 <https://www.youtube.com/watch?v=7cC3_jGwl_U>`_.
|
|
jpayne@69
|
57
|
|
jpayne@69
|
58 This also means that h11 is not immediately useful out of the box:
|
|
jpayne@69
|
59 it's a toolkit for building programs that speak HTTP, not something
|
|
jpayne@69
|
60 that could directly replace ``requests`` or ``twisted.web`` or
|
|
jpayne@69
|
61 whatever. But h11 makes it much easier to implement something like
|
|
jpayne@69
|
62 ``requests`` or ``twisted.web``.
|
|
jpayne@69
|
63
|
|
jpayne@69
|
64 At a high level, working with h11 goes like this:
|
|
jpayne@69
|
65
|
|
jpayne@69
|
66 1) First, create an ``h11.Connection`` object to track the state of a
|
|
jpayne@69
|
67 single HTTP/1.1 connection.
|
|
jpayne@69
|
68
|
|
jpayne@69
|
69 2) When you read data off the network, pass it to
|
|
jpayne@69
|
70 ``conn.receive_data(...)``; you'll get back a list of objects
|
|
jpayne@69
|
71 representing high-level HTTP "events".
|
|
jpayne@69
|
72
|
|
jpayne@69
|
73 3) When you want to send a high-level HTTP event, create the
|
|
jpayne@69
|
74 corresponding "event" object and pass it to ``conn.send(...)``;
|
|
jpayne@69
|
75 this will give you back some bytes that you can then push out
|
|
jpayne@69
|
76 through the network.
|
|
jpayne@69
|
77
|
|
jpayne@69
|
78 For example, a client might instantiate and then send a
|
|
jpayne@69
|
79 ``h11.Request`` object, then zero or more ``h11.Data`` objects for the
|
|
jpayne@69
|
80 request body (e.g., if this is a POST), and then a
|
|
jpayne@69
|
81 ``h11.EndOfMessage`` to indicate the end of the message. Then the
|
|
jpayne@69
|
82 server would then send back a ``h11.Response``, some ``h11.Data``, and
|
|
jpayne@69
|
83 its own ``h11.EndOfMessage``. If either side violates the protocol,
|
|
jpayne@69
|
84 you'll get a ``h11.ProtocolError`` exception.
|
|
jpayne@69
|
85
|
|
jpayne@69
|
86 h11 is suitable for implementing both servers and clients, and has a
|
|
jpayne@69
|
87 pleasantly symmetric API: the events you send as a client are exactly
|
|
jpayne@69
|
88 the ones that you receive as a server and vice-versa.
|
|
jpayne@69
|
89
|
|
jpayne@69
|
90 `Here's an example of a tiny HTTP client
|
|
jpayne@69
|
91 <https://github.com/python-hyper/h11/blob/master/examples/basic-client.py>`_
|
|
jpayne@69
|
92
|
|
jpayne@69
|
93 It also has `a fine manual <https://h11.readthedocs.io/>`_.
|
|
jpayne@69
|
94
|
|
jpayne@69
|
95 FAQ
|
|
jpayne@69
|
96 ---
|
|
jpayne@69
|
97
|
|
jpayne@69
|
98 *Whyyyyy?*
|
|
jpayne@69
|
99
|
|
jpayne@69
|
100 I wanted to play with HTTP in `Curio
|
|
jpayne@69
|
101 <https://curio.readthedocs.io/en/latest/tutorial.html>`__ and `Trio
|
|
jpayne@69
|
102 <https://trio.readthedocs.io>`__, which at the time didn't have any
|
|
jpayne@69
|
103 HTTP libraries. So I thought, no big deal, Python has, like, a dozen
|
|
jpayne@69
|
104 different implementations of HTTP, surely I can find one that's
|
|
jpayne@69
|
105 reusable. I didn't find one, but I did find Cory's call-to-arms
|
|
jpayne@69
|
106 blog-post. So I figured, well, fine, if I have to implement HTTP from
|
|
jpayne@69
|
107 scratch, at least I can make sure no-one *else* has to ever again.
|
|
jpayne@69
|
108
|
|
jpayne@69
|
109 *Should I use it?*
|
|
jpayne@69
|
110
|
|
jpayne@69
|
111 Maybe. You should be aware that it's a very young project. But, it's
|
|
jpayne@69
|
112 feature complete and has an exhaustive test-suite and complete docs,
|
|
jpayne@69
|
113 so the next step is for people to try using it and see how it goes
|
|
jpayne@69
|
114 :-). If you do then please let us know -- if nothing else we'll want
|
|
jpayne@69
|
115 to talk to you before making any incompatible changes!
|
|
jpayne@69
|
116
|
|
jpayne@69
|
117 *What are the features/limitations?*
|
|
jpayne@69
|
118
|
|
jpayne@69
|
119 Roughly speaking, it's trying to be a robust, complete, and non-hacky
|
|
jpayne@69
|
120 implementation of the first "chapter" of the HTTP/1.1 spec: `RFC 7230:
|
|
jpayne@69
|
121 HTTP/1.1 Message Syntax and Routing
|
|
jpayne@69
|
122 <https://tools.ietf.org/html/rfc7230>`_. That is, it mostly focuses on
|
|
jpayne@69
|
123 implementing HTTP at the level of taking bytes on and off the wire,
|
|
jpayne@69
|
124 and the headers related to that, and tries to be anal about spec
|
|
jpayne@69
|
125 conformance. It doesn't know about higher-level concerns like URL
|
|
jpayne@69
|
126 routing, conditional GETs, cross-origin cookie policies, or content
|
|
jpayne@69
|
127 negotiation. But it does know how to take care of framing,
|
|
jpayne@69
|
128 cross-version differences in keep-alive handling, and the "obsolete
|
|
jpayne@69
|
129 line folding" rule, so you can focus your energies on the hard /
|
|
jpayne@69
|
130 interesting parts for your application, and it tries to support the
|
|
jpayne@69
|
131 full specification in the sense that any useful HTTP/1.1 conformant
|
|
jpayne@69
|
132 application should be able to use h11.
|
|
jpayne@69
|
133
|
|
jpayne@69
|
134 It's pure Python, and has no dependencies outside of the standard
|
|
jpayne@69
|
135 library.
|
|
jpayne@69
|
136
|
|
jpayne@69
|
137 It has a test suite with 100.0% coverage for both statements and
|
|
jpayne@69
|
138 branches.
|
|
jpayne@69
|
139
|
|
jpayne@69
|
140 Currently it supports Python 3 (testing on 3.7-3.10) and PyPy 3.
|
|
jpayne@69
|
141 The last Python 2-compatible version was h11 0.11.x.
|
|
jpayne@69
|
142 (Originally it had a Cython wrapper for `http-parser
|
|
jpayne@69
|
143 <https://github.com/nodejs/http-parser>`_ and a beautiful nested state
|
|
jpayne@69
|
144 machine implemented with ``yield from`` to postprocess the output. But
|
|
jpayne@69
|
145 I had to take these out -- the new *parser* needs fewer lines-of-code
|
|
jpayne@69
|
146 than the old *parser wrapper*, is written in pure Python, uses no
|
|
jpayne@69
|
147 exotic language syntax, and has more features. It's sad, really; that
|
|
jpayne@69
|
148 old state machine was really slick. I just need a few sentences here
|
|
jpayne@69
|
149 to mourn that.)
|
|
jpayne@69
|
150
|
|
jpayne@69
|
151 I don't know how fast it is. I haven't benchmarked or profiled it yet,
|
|
jpayne@69
|
152 so it's probably got a few pointless hot spots, and I've been trying
|
|
jpayne@69
|
153 to err on the side of simplicity and robustness instead of
|
|
jpayne@69
|
154 micro-optimization. But at the architectural level I tried hard to
|
|
jpayne@69
|
155 avoid fundamentally bad decisions, e.g., I believe that all the
|
|
jpayne@69
|
156 parsing algorithms remain linear-time even in the face of pathological
|
|
jpayne@69
|
157 input like slowloris, and there are no byte-by-byte loops. (I also
|
|
jpayne@69
|
158 believe that it maintains bounded memory usage in the face of
|
|
jpayne@69
|
159 arbitrary/pathological input.)
|
|
jpayne@69
|
160
|
|
jpayne@69
|
161 The whole library is ~800 lines-of-code. You can read and understand
|
|
jpayne@69
|
162 the whole thing in less than an hour. Most of the energy invested in
|
|
jpayne@69
|
163 this so far has been spent on trying to keep things simple by
|
|
jpayne@69
|
164 minimizing special-cases and ad hoc state manipulation; even though it
|
|
jpayne@69
|
165 is now quite small and simple, I'm still annoyed that I haven't
|
|
jpayne@69
|
166 figured out how to make it even smaller and simpler. (Unfortunately,
|
|
jpayne@69
|
167 HTTP does not lend itself to simplicity.)
|
|
jpayne@69
|
168
|
|
jpayne@69
|
169 The API is ~feature complete and I don't expect the general outlines
|
|
jpayne@69
|
170 to change much, but you can't judge an API's ergonomics until you
|
|
jpayne@69
|
171 actually document and use it, so I'd expect some changes in the
|
|
jpayne@69
|
172 details.
|
|
jpayne@69
|
173
|
|
jpayne@69
|
174 *How do I try it?*
|
|
jpayne@69
|
175
|
|
jpayne@69
|
176 .. code-block:: sh
|
|
jpayne@69
|
177
|
|
jpayne@69
|
178 $ pip install h11
|
|
jpayne@69
|
179 $ git clone git@github.com:python-hyper/h11
|
|
jpayne@69
|
180 $ cd h11/examples
|
|
jpayne@69
|
181 $ python basic-client.py
|
|
jpayne@69
|
182
|
|
jpayne@69
|
183 and go from there.
|
|
jpayne@69
|
184
|
|
jpayne@69
|
185 *License?*
|
|
jpayne@69
|
186
|
|
jpayne@69
|
187 MIT
|
|
jpayne@69
|
188
|
|
jpayne@69
|
189 *Code of conduct?*
|
|
jpayne@69
|
190
|
|
jpayne@69
|
191 Contributors are requested to follow our `code of conduct
|
|
jpayne@69
|
192 <https://github.com/python-hyper/h11/blob/master/CODE_OF_CONDUCT.md>`_ in
|
|
jpayne@69
|
193 all project spaces.
|
