| single |
h11
===
:alt: Automated test status
:alt: Test coverage
:alt: Documentation Status
This is a little HTTP/1.1 library written from scratch in Python,
heavily inspired by `hyper-h2 `_.
It's a "bring-your-own-I/O" library; h11 contains no IO code
whatsoever. This means you can hook h11 up to your favorite network
API, and that could be anything you want: synchronous, threaded,
asynchronous, or your own implementation of [RFC 6214
] -- h11 won't judge you.
(Compare this to the current state of the art, where every time a [new
network API] comes along then someone
gets to start over reimplementing the entire HTTP protocol from
scratch.) Cory Benfield made an [excellent blog post describing the
benefits of this approach
], or if you like video
then here's his [PyCon 2016 talk on the same theme
].
This also means that h11 is not immediately useful out of the box:
it's a toolkit for building programs that speak HTTP, not something
that could directly replace requests or ``twisted.web`` or
whatever. But h11 makes it much easier to implement something like
requests or ``twisted.web``.
At a high level, working with h11 goes like this:
1) First, create an ``h11.Connection`` object to track the state of a
single HTTP/1.1 connection.
2) When you read data off the network, pass it to
``conn.receive_data(...)``; you'll get back a list of objects
representing high-level HTTP "events".
3) When you want to send a high-level HTTP event, create the
corresponding "event" object and pass it to ``conn.send(...)``;
this will give you back some bytes that you can then push out
through the network.
For example, a client might instantiate and then send a
``h11.Request`` object, then zero or more ``h11.Data`` objects for the
request body (e.g., if this is a POST), and then a
``h11.EndOfMessage`` to indicate the end of the message. Then the
server would then send back a ``h11.Response``, some ``h11.Data``, and
its own ``h11.EndOfMessage``. If either side violates the protocol,
you'll get a ``h11.ProtocolError`` exception.
h11 is suitable for implementing both servers and clients, and has a
pleasantly symmetric API: the events you send as a client are exactly
the ones that you receive as a server and vice-versa.
[Here's an example of a tiny HTTP client
]
It also has [a fine manual].
FAQ
---
*Whyyyyy?*
I wanted to play with HTTP in [Curio
] and [Trio
], which at the time didn't have any
HTTP libraries. So I thought, no big deal, Python has, like, a dozen
different implementations of HTTP, surely I can find one that's
reusable. I didn't find one, but I did find Cory's call-to-arms
blog-post. So I figured, well, fine, if I have to implement HTTP from
scratch, at least I can make sure no-one *else* has to ever again.
*Should I use it?*
Maybe. You should be aware that it's a very young project. But, it's
feature complete and has an exhaustive test-suite and complete docs,
so the next step is for people to try using it and see how it goes
:-). If you do then please let us know -- if nothing else we'll want
to talk to you before making any incompatible changes!
*What are the features/limitations?*
Roughly speaking, it's trying to be a robust, complete, and non-hacky
implementation of the first "chapter" of the HTTP/1.1 spec: `RFC 7230:
HTTP/1.1 Message Syntax and Routing
`_. That is, it mostly focuses on
implementing HTTP at the level of taking bytes on and off the wire,
and the headers related to that, and tries to be anal about spec
conformance. It doesn't know about higher-level concerns like URL
routing, conditional GETs, cross-origin cookie policies, or content
negotiation. But it does know how to take care of framing,
cross-version differences in keep-alive handling, and the "obsolete
line folding" rule, so you can focus your energies on the hard /
interesting parts for your application, and it tries to support the
full specification in the sense that any useful HTTP/1.1 conformant
|