positive-engineer / httpsuite

🧳 Collection of tools to parse, manipulate, and compile raw HTTP/1.1 messages.

httpsuite is a collection of tools to parse, manipulate, and compile raw HTTP messages. Built to be used as a dependency for larger projects that require parsing, modifying, requesting, and responding to raw HTTP requests.

Installing

pip install httpsuite

This package was intentionally built to have no external dependencies outside of the Python Standard Library. If you plan on contribute, then make sure to install the dev-requirements.txt.

Documentation

Read the documentation here.

Use

httpsuite provides two main objects, Request and Response. Both objects can be initialized with either __init__ or parse:

from httpsuite import Request, Response
import json

request = Request(
    method="GET",
    target="/",
    protocol="HTTP/1.1",
    headers={"Host": "www.google.com", "Connection": "keep-alive",},
    body=json.dumps({"hello": "world"}),
)

response = Response(
    protocol="HTTP/1.1",
    status=200,
    status_msg="OK",
    headers={"Host": "www.google.com", "Connection": "keep-alive",},
    body=json.dumps({"hello": "world"}),
)

or

from httpsuite import Request, Response

request = Request.parse(
    (
        b"GET / HTTP/1.1\r\n"
        b"Host: www.google.com\r\n"
        b"Connection: keep-alive\r\n"
        b"\r\n"
        b'{"hello": "world"}'
    )
)

response = Response.parse(
    (
        b"HTTP/1.1 200 OK\r\n"
        b"Host: www.google.com\r\n"
        b"Connection: keep-alive\r\n"
        b"\r\n"
        b'{"hello": "world"}'
    )
)

Request and Responses objects can be directly modified as one would expect, with no limitations as to the type:

request.method = "POST"
request.headers += {"Accept": "*/*"}

response.status = 100
response.status_msg = b"Continue"

Internally, every item of a request or response is saved as an Item, a special object type that allows easy setting and comparisons on the fly:

response.status == 100      # >>> True
response.status == "100"    # >>> True
response.status == b"100"   # >>> True

Once the object is modified to the users preference, utilizing the Request and Response object is as easy as calling a property (specifically .raw):

print(request.raw)
# >>> b'POST / HTTP/1.1\r\nHost: www.google.com\r\nConnection: keep-alive\r\nAccept: */*\r\n\r\n{"hello": "world"}'

print(response.raw)
# >>> b'HTTP/1.1 100 Continue\r\nHost: www.google.com\r\nConnection: keep-alive\r\n\r\n{"hello": "world"}'

Uniquely, the __str__ method for Request and Response return the objects with arrows to make obvious of its type:

print(request)
print(response)

→ POST / HTTP/1.1
→ Host: www.google.com
→ Connection: keep-alive
→ Accept: */*
→
→ {"hello": "world"}

← HTTP/1.1 100 Continue
← Host: www.google.com
← Connection: keep-alive
←
← {"hello": "world"}

For more information and examples of httpsuite, check out the docs.