1![Tests](https://github.com/MagicStack/httptools/workflows/Tests/badge.svg)
2
3httptools is a Python binding for the nodejs HTTP parser.
4
5The package is available on PyPI: `pip install httptools`.
6
7
8# APIs
9
10httptools contains two classes `httptools.HttpRequestParser`,
11`httptools.HttpResponseParser` (fulfilled through
12[llhttp](https://github.com/nodejs/llhttp)) and a function for
13parsing URLs `httptools.parse_url` (through
14[http-parse](https://github.com/nodejs/http-parser) for now).
15See unittests for examples.
16
17
18```python
19
20class HttpRequestParser:
21
22    def __init__(self, protocol):
23        """HttpRequestParser
24
25        protocol -- a Python object with the following methods
26        (all optional):
27
28          - on_message_begin()
29          - on_url(url: bytes)
30          - on_header(name: bytes, value: bytes)
31          - on_headers_complete()
32          - on_body(body: bytes)
33          - on_message_complete()
34          - on_chunk_header()
35          - on_chunk_complete()
36          - on_status(status: bytes)
37        """
38
39    def get_http_version(self) -> str:
40        """Return an HTTP protocol version."""
41
42    def should_keep_alive(self) -> bool:
43        """Return ``True`` if keep-alive mode is preferred."""
44
45    def should_upgrade(self) -> bool:
46        """Return ``True`` if the parsed request is a valid Upgrade request.
47	The method exposes a flag set just before on_headers_complete.
48	Calling this method earlier will only yield `False`.
49	"""
50
51    def feed_data(self, data: bytes):
52        """Feed data to the parser.
53
54        Will eventually trigger callbacks on the ``protocol``
55        object.
56
57        On HTTP upgrade, this method will raise an
58        ``HttpParserUpgrade`` exception, with its sole argument
59        set to the offset of the non-HTTP data in ``data``.
60        """
61
62    def get_method(self) -> bytes:
63        """Return HTTP request method (GET, HEAD, etc)"""
64
65
66class HttpResponseParser:
67
68    """Has all methods except ``get_method()`` that
69    HttpRequestParser has."""
70
71    def get_status_code(self) -> int:
72        """Return the status code of the HTTP response"""
73
74
75def parse_url(url: bytes):
76    """Parse URL strings into a structured Python object.
77
78    Returns an instance of ``httptools.URL`` class with the
79    following attributes:
80
81      - schema: bytes
82      - host: bytes
83      - port: int
84      - path: bytes
85      - query: bytes
86      - fragment: bytes
87      - userinfo: bytes
88    """
89```
90
91
92# Development
93
941. Clone this repository with
95   `git clone --recursive git@github.com:MagicStack/httptools.git`
96
972. Create a virtual environment with Python 3:
98   `python3 -m venv envname`
99
1003. Activate the environment with `source envname/bin/activate`
101
1024. Install development requirements with `pip install -e .[test]`
103
1045. Run `make` and `make test`.
105
106
107# License
108
109MIT.
110