{"id":10235,"library":"smithy-http","title":"Smithy HTTP","description":"Smithy-http provides foundational HTTP components and primitives for Smithy tooling in Python. It defines standard interfaces for HTTP requests, responses, headers, and middleware, ensuring compliance with Smithy's protocol specifications. This library is primarily a building block for Smithy-generated Python clients and other Smithy-compliant services. The current version is 0.4.0, and releases are generally tied to the development cadence of the broader `smithy-python` project.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-http/","tags":["http","smithy","protocol","client","low-level","codegen"],"install":[{"cmd":"pip install smithy-http","lang":"bash","label":"Install smithy-http"}],"dependencies":[],"imports":[{"note":"Represents an outgoing HTTP request message.","symbol":"HttpRequest","correct":"from smithy_http.request import HttpRequest"},{"note":"Represents an incoming HTTP response message.","symbol":"HttpResponse","correct":"from smithy_http.response import HttpResponse"},{"note":"A case-insensitive dictionary-like object for HTTP headers.","symbol":"Headers","correct":"from smithy_http.headers import Headers"},{"note":"Base abstract class for HTTP middleware components.","symbol":"Middleware","correct":"from smithy_http.middleware import Middleware"}],"quickstart":{"code":"from smithy_http.request import HttpRequest\nfrom smithy_http.response import HttpResponse\nfrom smithy_http.headers import Headers\nfrom io import BytesIO\n\n# --- Construct an HttpRequest ---\nurl = \"https://example.com/path\"\nmethod = \"POST\"\nheaders = Headers({\"Content-Type\": \"application/json\", \"Accept\": \"application/json\"})\nbody_content = b'{\"key\": \"value\"}'\nbody = BytesIO(body_content)\n\nrequest = HttpRequest(\n    method=method,\n    url=url,\n    headers=headers,\n    body=body\n)\n\nprint(f\"Request Method: {request.method}\")\nprint(f\"Request URL: {request.url}\")\nprint(f\"Request Headers: {dict(request.headers)}\")\nrequest.body.seek(0)\nprint(f\"Request Body: {request.body.read().decode('utf-8')}\")\n\n# --- Construct an HttpResponse ---\nstatus_code = 200\nresponse_headers = Headers({\"Content-Type\": \"application/json\"})\nresponse_body_content = b'{\"message\": \"success\"}'\nresponse_body = BytesIO(response_body_content)\n\nresponse = HttpResponse(\n    status_code=status_code,\n    headers=response_headers,\n    body=response_body\n)\n\nprint(f\"\\nResponse Status Code: {response.status_code}\")\nprint(f\"Response Headers: {dict(response.headers)}\")\nresponse.body.seek(0)\nprint(f\"Response Body: {response.body.read().decode('utf-8')}\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the `smithy-python` project's changelog for specific migration steps when upgrading to newer 0.x.x versions.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install smithy-http` to install the library.","cause":"The `smithy-http` package has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'smithy_http'"},{"fix":"Wrap your bytes data in a `io.BytesIO` object. For example, `body=BytesIO(b'your_data')`.","cause":"The `HttpRequest` or `HttpResponse` constructor expects a `BytesIO` object for the `body` argument, not raw bytes.","error":"TypeError: argument 'body' must be BytesIO, not <class 'bytes'>"},{"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.","cause":"Users attempting to send an `HttpRequest` object directly, misunderstanding that `smithy-http` is a data model library, not an HTTP client.","error":"AttributeError: 'HttpRequest' object has no attribute 'send'"}]}