<commit_before>h11
===

This is a little HTTP/1.1 library written from scratch in Python,
heavily inspired by `hyper-h2
<https://lukasa.co.uk/2015/10/The_New_Hyper/>`_.

This is a pure protocol library; like h2, it contains no IO code
whatsoever. I highly recommend `that blog post for context on what
this means and the motivation for doing things this way
<https://lukasa.co.uk/2015/10/The_New_Hyper/>`_. But basically the
idea is that by doing things this way, 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 <https://tools.ietf.org/html/rfc6214>`_ -- h11 won't judge
you. Compare this to the current state of the art, where every time a
`new network API <https://curio.readthedocs.io/>`_ comes along then
someone gets to start over reimplementing the entire HTTP protocol
from scratch.

h11 is a toolkit for building tools that speak HTTP, not something
directly useful to an end-user: we're not going to replace
``requests`` or ``twisted.web`` or whatever, but if you're
*implementing* something like ``requests`` or ``twisted.web`` then you
might find h11 useful. At a high level, working with it involves:

1) Creating 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(...)`` and 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 object, pass it to ``conn.send(...)``, and this will
   convert it to 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, and 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 an exception.

It's suitable for implementing both servers and clients, and has a
pleasingly 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
<https://github.com/njsmith/h11/blob/master/tiny-client-demo.py>`_


FAQ
---

*Whyyyyy?*

NIH is fun! Also I got mildly annoyed at some trivial and probably
easily fixable issues in `aiohttp <https://aiohttp.readthedocs.io/>`_,
so rather than spend a few hours debugging them I spent a few days
writing my own HTTP stack from scratch.

*...that's a terrible reason.*

Well, ok... I also wanted to play with `Curio
<https://curio.readthedocs.io/en/latest/tutorial.html>`_, which has no
HTTP library, and I was feeling inspired by Curio's elegantly
featureful minimalism and Corey's call-to-arms blog-post.

And, most importantly, I was sick and needed a gloriously pointless
yak-shaving project to distract me from all the things I should have
been doing instead. Perhaps it won't turn out to be quite as pointless
as all that, but either way at least I learned some stuff.

*Should I use it?*

Probably not; it's just a few-days-old hack at this point.

*Should I play with it?*

Please do! It's fun!

*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
<https://tools.ietf.org/html/rfc7230>`_. 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 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<commit_msg>README README README<commit_after>h11
===

This is a little HTTP/1.1 library written from scratch in Python,
heavily inspired by `hyper-h2
<https://lukasa.co.uk/2015/10/The_New_Hyper/>`_.

This is a pure protocol library; like h2, it contains no IO code
whatsoever. I highly recommend `that blog post for context on what
this means and the motivation for doing things this way
<https://lukasa.co.uk/2015/10/The_New_Hyper/>`_. But basically the
idea is that by doing things this way, 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 <https://tools.ietf.org/html/rfc6214>`_ -- h11 won't judge
you. Compare this to the current state of the art, where every time a
`new network API <https://curio.readthedocs.io/>`_ comes along then
someone gets to start over reimplementing the entire HTTP protocol
from scratch.

h11 is a toolkit for building tools that speak HTTP, not something
directly useful to an end-user: we're not going to replace
``requests`` or ``twisted.web`` or whatever, but if you're
*implementing* something like ``requests`` or ``twisted.web`` then you
might find h11 useful. At a high level, working with it involves:

1) Creating 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(...)`` and 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 object, pass it to ``conn.send(...)``, and this will
   convert it to 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, and 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 an exception.

It's suitable for implementing both servers and clients, and has a
pleasingly 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
<https://github.com/njsmith/h11/blob/master/tiny-client-demo.py>`_


FAQ
---

*Whyyyyy?*

NIH is fun! Also I got mildly annoyed at some trivial and probably
easily fixable issues in `aiohttp <https://aiohttp.readthedocs.io/>`_,
so rather than spend a few hours debugging them I spent a few days
writing my own HTTP stack from scratch.

*...that's a terrible reason.*

Well, ok... I also wanted to play with `Curio
<https://curio.readthedocs.io/en/latest/tutorial.html>`_, which has no
HTTP library, and I was feeling inspired by Curio's elegantly
featureful minimalism and Cory's call-to-arms blog-post.

And, most importantly, I was sick and needed a gloriously pointless
yak-shaving project to distract me from all the things I should have
been doing instead. Perhaps it won't turn out to be quite as pointless
as all that, but either way at least I learned some stuff.

*Should I use it?*

Probably not; it's just a few-days-old hack at this point.

*Should I play with it?*

Please do! It's fun!

*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
<https://tools.ietf.org/html/rfc7230>`_. 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 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
{'fraction_non_alphanumeric': 0.08178158027176648, 'fraction_numerical': 0.016859587317564168, 'mean_word_length': 4.1650422352176735, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 2, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1002374', 'n_tokens_mistral': 2460, 'n_tokens_neox': 2296, 'n_words': 1189}