jpayne@69: Metadata-Version: 2.1 jpayne@69: Name: h11 jpayne@69: Version: 0.14.0 jpayne@69: Summary: A pure-Python, bring-your-own-I/O implementation of HTTP/1.1 jpayne@69: Home-page: https://github.com/python-hyper/h11 jpayne@69: Author: Nathaniel J. Smith jpayne@69: Author-email: njs@pobox.com jpayne@69: License: MIT jpayne@69: Classifier: Development Status :: 3 - Alpha jpayne@69: Classifier: Intended Audience :: Developers jpayne@69: Classifier: License :: OSI Approved :: MIT License jpayne@69: Classifier: Programming Language :: Python :: Implementation :: CPython jpayne@69: Classifier: Programming Language :: Python :: Implementation :: PyPy jpayne@69: Classifier: Programming Language :: Python :: 3 jpayne@69: Classifier: Programming Language :: Python :: 3 :: Only jpayne@69: Classifier: Programming Language :: Python :: 3.7 jpayne@69: Classifier: Programming Language :: Python :: 3.8 jpayne@69: Classifier: Programming Language :: Python :: 3.9 jpayne@69: Classifier: Programming Language :: Python :: 3.10 jpayne@69: Classifier: Topic :: Internet :: WWW/HTTP jpayne@69: Classifier: Topic :: System :: Networking jpayne@69: Requires-Python: >=3.7 jpayne@69: License-File: LICENSE.txt jpayne@69: Requires-Dist: typing-extensions ; python_version < "3.8" jpayne@69: jpayne@69: h11 jpayne@69: === jpayne@69: jpayne@69: .. image:: https://travis-ci.org/python-hyper/h11.svg?branch=master jpayne@69: :target: https://travis-ci.org/python-hyper/h11 jpayne@69: :alt: Automated test status jpayne@69: jpayne@69: .. image:: https://codecov.io/gh/python-hyper/h11/branch/master/graph/badge.svg jpayne@69: :target: https://codecov.io/gh/python-hyper/h11 jpayne@69: :alt: Test coverage jpayne@69: jpayne@69: .. image:: https://readthedocs.org/projects/h11/badge/?version=latest jpayne@69: :target: http://h11.readthedocs.io/en/latest/?badge=latest jpayne@69: :alt: Documentation Status jpayne@69: jpayne@69: This is a little HTTP/1.1 library written from scratch in Python, jpayne@69: heavily inspired by `hyper-h2 `_. jpayne@69: jpayne@69: It's a "bring-your-own-I/O" library; h11 contains no IO code jpayne@69: whatsoever. This means you can hook h11 up to your favorite network jpayne@69: API, and that could be anything you want: synchronous, threaded, jpayne@69: asynchronous, or your own implementation of `RFC 6214 jpayne@69: `_ -- h11 won't judge you. jpayne@69: (Compare this to the current state of the art, where every time a `new jpayne@69: network API `_ comes along then someone jpayne@69: gets to start over reimplementing the entire HTTP protocol from jpayne@69: scratch.) Cory Benfield made an `excellent blog post describing the jpayne@69: benefits of this approach jpayne@69: `_, or if you like video jpayne@69: then here's his `PyCon 2016 talk on the same theme jpayne@69: `_. jpayne@69: jpayne@69: This also means that h11 is not immediately useful out of the box: jpayne@69: it's a toolkit for building programs that speak HTTP, not something jpayne@69: that could directly replace ``requests`` or ``twisted.web`` or jpayne@69: whatever. But h11 makes it much easier to implement something like jpayne@69: ``requests`` or ``twisted.web``. jpayne@69: jpayne@69: At a high level, working with h11 goes like this: jpayne@69: jpayne@69: 1) First, create an ``h11.Connection`` object to track the state of a jpayne@69: single HTTP/1.1 connection. jpayne@69: jpayne@69: 2) When you read data off the network, pass it to jpayne@69: ``conn.receive_data(...)``; you'll get back a list of objects jpayne@69: representing high-level HTTP "events". jpayne@69: jpayne@69: 3) When you want to send a high-level HTTP event, create the jpayne@69: corresponding "event" object and pass it to ``conn.send(...)``; jpayne@69: this will give you back some bytes that you can then push out jpayne@69: through the network. jpayne@69: jpayne@69: For example, a client might instantiate and then send a jpayne@69: ``h11.Request`` object, then zero or more ``h11.Data`` objects for the jpayne@69: request body (e.g., if this is a POST), and then a jpayne@69: ``h11.EndOfMessage`` to indicate the end of the message. Then the jpayne@69: server would then send back a ``h11.Response``, some ``h11.Data``, and jpayne@69: its own ``h11.EndOfMessage``. If either side violates the protocol, jpayne@69: you'll get a ``h11.ProtocolError`` exception. jpayne@69: jpayne@69: h11 is suitable for implementing both servers and clients, and has a jpayne@69: pleasantly symmetric API: the events you send as a client are exactly jpayne@69: the ones that you receive as a server and vice-versa. jpayne@69: jpayne@69: `Here's an example of a tiny HTTP client jpayne@69: `_ jpayne@69: jpayne@69: It also has `a fine manual `_. jpayne@69: jpayne@69: FAQ jpayne@69: --- jpayne@69: jpayne@69: *Whyyyyy?* jpayne@69: jpayne@69: I wanted to play with HTTP in `Curio jpayne@69: `__ and `Trio jpayne@69: `__, which at the time didn't have any jpayne@69: HTTP libraries. So I thought, no big deal, Python has, like, a dozen jpayne@69: different implementations of HTTP, surely I can find one that's jpayne@69: reusable. I didn't find one, but I did find Cory's call-to-arms jpayne@69: blog-post. So I figured, well, fine, if I have to implement HTTP from jpayne@69: scratch, at least I can make sure no-one *else* has to ever again. jpayne@69: jpayne@69: *Should I use it?* jpayne@69: jpayne@69: Maybe. You should be aware that it's a very young project. But, it's jpayne@69: feature complete and has an exhaustive test-suite and complete docs, jpayne@69: so the next step is for people to try using it and see how it goes jpayne@69: :-). If you do then please let us know -- if nothing else we'll want jpayne@69: to talk to you before making any incompatible changes! jpayne@69: jpayne@69: *What are the features/limitations?* jpayne@69: jpayne@69: Roughly speaking, it's trying to be a robust, complete, and non-hacky jpayne@69: implementation of the first "chapter" of the HTTP/1.1 spec: `RFC 7230: jpayne@69: HTTP/1.1 Message Syntax and Routing jpayne@69: `_. That is, it mostly focuses on jpayne@69: implementing HTTP at the level of taking bytes on and off the wire, jpayne@69: and the headers related to that, and tries to be anal about spec jpayne@69: conformance. It doesn't know about higher-level concerns like URL jpayne@69: routing, conditional GETs, cross-origin cookie policies, or content jpayne@69: negotiation. But it does know how to take care of framing, jpayne@69: cross-version differences in keep-alive handling, and the "obsolete jpayne@69: line folding" rule, so you can focus your energies on the hard / jpayne@69: interesting parts for your application, and it tries to support the jpayne@69: full specification in the sense that any useful HTTP/1.1 conformant jpayne@69: application should be able to use h11. jpayne@69: jpayne@69: It's pure Python, and has no dependencies outside of the standard jpayne@69: library. jpayne@69: jpayne@69: It has a test suite with 100.0% coverage for both statements and jpayne@69: branches. jpayne@69: jpayne@69: Currently it supports Python 3 (testing on 3.7-3.10) and PyPy 3. jpayne@69: The last Python 2-compatible version was h11 0.11.x. jpayne@69: (Originally it had a Cython wrapper for `http-parser jpayne@69: `_ and a beautiful nested state jpayne@69: machine implemented with ``yield from`` to postprocess the output. But jpayne@69: I had to take these out -- the new *parser* needs fewer lines-of-code jpayne@69: than the old *parser wrapper*, is written in pure Python, uses no jpayne@69: exotic language syntax, and has more features. It's sad, really; that jpayne@69: old state machine was really slick. I just need a few sentences here jpayne@69: to mourn that.) jpayne@69: jpayne@69: I don't know how fast it is. I haven't benchmarked or profiled it yet, jpayne@69: so it's probably got a few pointless hot spots, and I've been trying jpayne@69: to err on the side of simplicity and robustness instead of jpayne@69: micro-optimization. But at the architectural level I tried hard to jpayne@69: avoid fundamentally bad decisions, e.g., I believe that all the jpayne@69: parsing algorithms remain linear-time even in the face of pathological jpayne@69: input like slowloris, and there are no byte-by-byte loops. (I also jpayne@69: believe that it maintains bounded memory usage in the face of jpayne@69: arbitrary/pathological input.) jpayne@69: jpayne@69: The whole library is ~800 lines-of-code. You can read and understand jpayne@69: the whole thing in less than an hour. Most of the energy invested in jpayne@69: this so far has been spent on trying to keep things simple by jpayne@69: minimizing special-cases and ad hoc state manipulation; even though it jpayne@69: is now quite small and simple, I'm still annoyed that I haven't jpayne@69: figured out how to make it even smaller and simpler. (Unfortunately, jpayne@69: HTTP does not lend itself to simplicity.) jpayne@69: jpayne@69: The API is ~feature complete and I don't expect the general outlines jpayne@69: to change much, but you can't judge an API's ergonomics until you jpayne@69: actually document and use it, so I'd expect some changes in the jpayne@69: details. jpayne@69: jpayne@69: *How do I try it?* jpayne@69: jpayne@69: .. code-block:: sh jpayne@69: jpayne@69: $ pip install h11 jpayne@69: $ git clone git@github.com:python-hyper/h11 jpayne@69: $ cd h11/examples jpayne@69: $ python basic-client.py jpayne@69: jpayne@69: and go from there. jpayne@69: jpayne@69: *License?* jpayne@69: jpayne@69: MIT jpayne@69: jpayne@69: *Code of conduct?* jpayne@69: jpayne@69: Contributors are requested to follow our `code of conduct jpayne@69: `_ in jpayne@69: all project spaces.