Smithy HTTP

Common errors

• ModuleNotFoundError: No module named 'smithy_http'

  cause The `smithy-http` package has not been installed in your current Python environment.
  fix Run `pip install smithy-http` to install the library.

• TypeError: argument 'body' must be BytesIO, not <class 'bytes'>

  cause The `HttpRequest` or `HttpResponse` constructor expects a `BytesIO` object for the `body` argument, not raw bytes.
  fix Wrap your bytes data in a `io.BytesIO` object. For example, `body=BytesIO(b'your_data')`.

• AttributeError: 'HttpRequest' object has no attribute 'send'

  cause Users attempting to send an `HttpRequest` object directly, misunderstanding that `smithy-http` is a data model library, not an HTTP client.
  fix `smithy-http` objects represent HTTP messages but do not perform network operations. Use an actual HTTP client library (e.g., `aiohttp` or `httpx`) to send and receive these messages.

Warnings

• breaking As a 0.x.x library, `smithy-http`'s API is subject to change without strict backward compatibility guarantees. Expect potential breaking changes between minor versions as the library matures towards a 1.0 release.
  Fix: Refer to the `smithy-python` project's changelog for specific migration steps when upgrading to newer 0.x.x versions.
• gotcha `smithy-http` is a low-level library providing HTTP primitives (request/response objects, headers). It is NOT an HTTP client (like `requests` or `httpx`) and does not perform actual network requests. It's designed to be integrated into other frameworks or clients.
  Fix: Do not expect `smithy-http` to send or receive data over the network. It merely defines the structure for HTTP messages. You'll need to use a separate HTTP client library (e.g., `aiohttp`, `urllib3`) to handle the network I/O with `smithy-http` objects.
• gotcha `smithy-http` is heavily typed. Constructors and methods often require specific Python types (e.g., `str` for URLs, `BytesIO` for bodies). Providing incorrect types will lead to `TypeError` exceptions.
  Fix: Always refer to the type hints in the library's source code or documentation. For request/response bodies, use `io.BytesIO` containing bytes, not strings directly.

Install

• pip install smithy-http Install smithy-http

Imports

• HttpRequest

  from smithy_http.request import HttpRequest

  Represents an outgoing HTTP request message.
• HttpResponse

  from smithy_http.response import HttpResponse

  Represents an incoming HTTP response message.
• Headers

  from smithy_http.headers import Headers

  A case-insensitive dictionary-like object for HTTP headers.
• Middleware

  from smithy_http.middleware import Middleware

  Base abstract class for HTTP middleware components.

Quickstart

This quickstart demonstrates how to construct basic `HttpRequest` and `HttpResponse` objects using `smithy-http`'s core components. It highlights how to set the HTTP method, URL, headers, and body for both request and response entities. Note that `smithy-http` does not perform actual network calls; it provides the data structures for them.

from smithy_http.request import HttpRequest
from smithy_http.response import HttpResponse
from smithy_http.headers import Headers
from io import BytesIO

# --- Construct an HttpRequest ---
url = "https://example.com/path"
method = "POST"
headers = Headers({"Content-Type": "application/json", "Accept": "application/json"})
body_content = b'{"key": "value"}'
body = BytesIO(body_content)

request = HttpRequest(
    method=method,
    url=url,
    headers=headers,
    body=body
)

print(f"Request Method: {request.method}")
print(f"Request URL: {request.url}")
print(f"Request Headers: {dict(request.headers)}")
request.body.seek(0)
print(f"Request Body: {request.body.read().decode('utf-8')}")

# --- Construct an HttpResponse ---
status_code = 200
response_headers = Headers({"Content-Type": "application/json"})
response_body_content = b'{"message": "success"}'
response_body = BytesIO(response_body_content)

response = HttpResponse(
    status_code=status_code,
    headers=response_headers,
    body=response_body
)

print(f"\nResponse Status Code: {response.status_code}")
print(f"Response Headers: {dict(response.headers)}")
response.body.seek(0)
print(f"Response Body: {response.body.read().decode('utf-8')}")