---
id: smithy-http
version: "0.4.4"
license: Apache License 2.0
license_treatment: permissive
maintenance: active
---

# smithy-http — HTTP components for Smithy tooling.

License: permissive · Maintenance: active · Downloads: 423.5K/mo

## What it is and what it does

smithy-http is a low-level HTTP component library for the Smithy code generation framework's Python tooling. It defines interfaces and primitives that Smithy-generated SDK clients use to handle HTTP transport, and provides testing utilities so developers can verify client behavior without making real network requests.

The package's main entry point is MockHTTPClient, a test double that implements the HTTPClient interface and lets you queue responses, capture requests, and inspect call counts. It's designed to integrate with Smithy client configuration so you can swap in the mock during test setup. The package also includes helper functions like create_test_request() for constructing test HTTP objects and raises MockHTTPClientError when no responses are available.

Use it for:

- Unit test Smithy-generated SDK clients by mocking HTTP responses without network I/O
- Verify request structure and headers sent by a Smithy client before it reaches the network
- Simulate error conditions and edge-case HTTP responses to test client error handling
- Inspect captured requests after a client call to assert the correct operation was invoked

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides HTTP primitives, interfaces, and testing utilities for Smithy-generated Python clients, including a MockHTTPClient for testing without network calls.

Yes, if you are developing or testing code that uses a Smithy-generated Python client. The MockHTTPClient is a standard testing utility for that ecosystem. Pre-Alpha status and active maintenance are acceptable for a foundational library with no known vulnerabilities. Install only if you need Smithy client testing; it is not a general-purpose HTTP library.

## Install

pip install smithy-http
uv add smithy-http
poetry add smithy-http

## Installing smithy-http

Before you install: Active maintenance with a release 1 day old. Single runtime dependency (smithy-core) keeps install friction low. Pre-Alpha status signals this is early-stage tooling.

License in practice: Apache License 2.0 (permissive) places no significant restrictions on use, modification, or redistribution in proprietary or open-source projects.

Quickstart:

pip install smithy-http

from smithy_http.testing import MockHTTPClient

mock_client = MockHTTPClient()
mock_client.add_response(status=200, headers=[("Content-Type", "application/json")], body=b'{"message": "success"}')
# Pass mock_client to your Smithy client config for testing

Requires Python 3.12 or later; intended for use with Smithy-generated Python clients.

Verify before relying:

- Whether MockHTTPClient supports async/await patterns beyond the shown example
- Scope of HTTP functionality covered by the primitives layer beyond testing utilities
- Compatibility guarantees with smithy-core versions given the Pre-Alpha status

## Package facts

- License: Apache License 2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 423.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

smithy http client testing, mock http client python, smithy sdk http primitives, http testing utilities, smithy-python transport layer, mock http responses testing, smithy client mocking, smithy-ecosystem, test-doubles, sdk-tooling

[View on SkillFed](https://skillfed.io/packages/smithy-http) · [View on PyPI](https://pypi.org/project/smithy-http/)