# httptools

> A collection of framework independent HTTP protocol utils.

- **URL**: https://www.freshcrate.ai/projects/httptools
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `v0.8.0` (2026-05-25)
- **License**: Unknown
- **Source**: https://github.com/MagicStack/httptools
- **Homepage**: https://pypi.org/project/httptools/
- **Language**: Python
- **GitHub**: 1,320 stars, 107 forks
- **Registry**: pypi (`httptools`)
- **Tags**: `pypi`

## Description

![Tests](https://github.com/MagicStack/httptools/workflows/Tests/badge.svg)

httptools is a Python binding for the nodejs HTTP parser.

The package is available on PyPI: `pip install httptools`.


# APIs

httptools contains two classes `httptools.HttpRequestParser`,
`httptools.HttpResponseParser` (fulfilled through
[llhttp](https://github.com/nodejs/llhttp)) and a function for
parsing URLs `httptools.parse_url` (through
[http-parse](https://github.com/nodejs/http-parser) for now).
See unittests for examples.


```python

class HttpRequestParser:

    def __init__(self, protocol):
        """HttpRequestParser

        protocol -- a Python object with the following methods
        (all optional):

          - on_message_begin()
          - on_url(url: bytes)
          - on_header(name: bytes, value: bytes)
          - on_headers_complete()
          - on_body(body: bytes)
          - on_message_complete()
          - on_chunk_header()
          - on_chunk_complete()
          - on_status(status: bytes)
        """

    def get_http_version(self) -> str:
        """Return an HTTP protocol version."""

    def should_keep_alive(self) -> bool:
        """Return ``True`` if keep-alive mode is preferred."""

    def should_upgrade(self) -> bool:
        """Return ``True`` if the parsed request is a valid Upgrade request.
	The method exposes a flag set just before on_headers_complete.
	Calling this method earlier will only yield `False`.
	"""

    def feed_data(self, data: bytes):
        """Feed data to the parser.

        Will eventually trigger callbacks on the ``protocol``
        object.

        On HTTP upgrade, this method will raise an
        ``HttpParserUpgrade`` exception, with its sole argument
        set to the offset of the non-HTTP data in ``data``.
        """

    def get_method(self) -> bytes:
        """Return HTTP request method (GET, HEAD, etc)"""


class HttpResponseParser:

    """Has all methods except ``get_method()`` that
    HttpRequestParser has."""

    def get_status_code(self) -> int:
        """Return the status code of the HTTP response"""


def parse_url(url: bytes):
    """Parse URL strings into a structured Python object.

    Returns an instance of ``httptools.URL`` class with the
    following attributes:

      - schema: bytes
      - host: bytes
      - port: int
      - path: bytes
      - query: bytes
      - fragment: bytes
      - userinfo: bytes
    """
```


# Development

1. Clone this repository with
   `git clone --recursive git@github.com:MagicStack/httptools.git`

2. Create a virtual environment with Python 3:
   `python3 -m venv envname`

3. Activate the environment with `source envname/bin/activate`

4. Run `make` and `make test`.


# License

MIT.

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v0.8.0` | 2026-05-25 | High | Changes =======  * Add http-parser and llhttp licenses into the wheels (#135)   (by @justeph in c398a157)  * Mark cython module as free-threading compatible (#139)   (by @kumaraditya303 in 28d1db15)  * Fix all typing issues (#134)   (by @Kludex in a9bda0ed)  * Bump llhttp to 9.4.1 (#145)   (by @fantix in e3e8d71e)  * Security: fix URL truncation issue (#144)   (by @fantix in a0283f07 for #142)  * Allow building with latest setuptools (#138)   (by @OldManYellsAtCloud in c403ad1 |
| `0.7.1` | 2026-04-21 | Low | Imported from PyPI (0.7.1) |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |
| `v0.7.1` | 2025-10-10 | Low | This is identical to 0.7.0 whose CI failed uploading |

## Citation

- HTML: https://www.freshcrate.ai/projects/httptools
- Markdown: https://www.freshcrate.ai/projects/httptools.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/httptools/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._