# awshttp
Minimal Python library for making AWS SigV4 signed HTTP requests.
Perfect for Lambda functions and scripts that need to call AWS APIs with automatic credential detection.
**Automate AWS Console actions programmatically!** Capture API calls from your browser's Network tab and replay them in Python.
## Installation
```sh
# Using pip
pip install awshttp
# Using uv (recommended)
uv pip install awshttp
```
## Usage
```python
import awshttp
# GET request
response = awshttp.get(
uri='https://my-api.execute-api.us-east-1.amazonaws.com/prod/endpoint',
service='execute-api'
)
print(response.json())
# POST request
response = awshttp.post(
uri='https://my-api.execute-api.us-east-1.amazonaws.com/prod/endpoint',
service='execute-api',
data='{"key": "value"}',
headers={'content-type': 'application/json'}
)
# PUT request with JSON helper
response = awshttp.put_json(
uri='https://uxc.us-east-1.api.aws/v1/account-color',
service='uxc',
region='us-east-1',
data={'color': 'green'}
)
# Or use the main request function
response = awshttp.request(
uri='https://my-api.execute-api.us-east-1.amazonaws.com/prod/endpoint',
method='POST',
service='execute-api',
data='{"key": "value"}',
headers={'content-type': 'application/json'}
)
```
## Features
- Automatic AWS credential detection (IAM roles, environment variables, ~/.aws/credentials)
- Support for all AWS services (including undocumented Console APIs)
- Simple requests-like interface
- Retry logic with exponential backoff
- JSON helpers for API calls
- Environment variable configuration
- Minimal dependencies (boto3, requests)
## Automating Web Console Actions
Many AWS Console features don't have official CLI/SDK support. Use browser DevTools to capture the API calls:
1. Open AWS Console in your browser
2. Open DevTools (F12) → Network tab
3. Perform the action you want to automate
4. Find the API call in the Network tab
5. Copy the URL, method, headers, and body
6. Replicate with awshttp!
**Example: Change AWS Console account color**
```python
import awshttp
# This API isn't in the AWS SDK, but we can call it directly!
response = awshttp.put_json(
uri='https://uxc.us-east-1.api.aws/v1/account-color',
service='uxc', # Service name from the URL
region='us-east-1',
data={'color': 'green'}
)
print(f"Status: {response.status_code}")
print(f"Response: {response.text}")
```
**Tips for finding service names:**
- Look at the URL: `https://SERVICE.REGION.api.aws/...`
- Common services: `uxc` (console UI), `execute-api` (API Gateway), `s3`, `ec2`
- Check the `authorization` header in DevTools for the service name
**Advanced usage with retry:**
```python
# Retry failed requests automatically
@awshttp.with_retry(retries=5, backoff=2.0)
def reliable_api_call():
return awshttp.post_json(
uri='https://api.example.com/endpoint',
service='execute-api',
data={'action': 'process'},
timeout=30
)
response = reliable_api_call()
```
## API Reference
### awshttp.request(uri, method='GET', service='execute-api', region=None, headers=None, data='', verify=True, allow_redirects=False, timeout=None, session=None)
Main function for making signed AWS requests.
**Parameters:**
- `uri` (str): Full URL to request
- `method` (str): HTTP method (GET, POST, PUT, DELETE, PATCH)
- `service` (str): AWS service name for signing
- `region` (str | None): AWS region (auto-detects if None)
- `headers` (dict | None): HTTP headers
- `data` (str | bytes): Request body
- `verify` (bool): Verify SSL certificates
- `allow_redirects` (bool): Follow redirects
- `timeout` (float | None): Request timeout in seconds
- `session` (boto3.Session | None): Boto3 session for credential reuse
**Returns:** `requests.Response` object
### Convenience methods
- `awshttp.get(uri, **kwargs)` - GET request
- `awshttp.post(uri, data='', **kwargs)` - POST request
- `awshttp.put(uri, data='', **kwargs)` - PUT request
- `awshttp.delete(uri, **kwargs)` - DELETE request
- `awshttp.patch(uri, data='', **kwargs)` - PATCH request
- `awshttp.post_json(uri, data={}, **kwargs)` - POST with JSON serialization
- `awshttp.put_json(uri, data={}, **kwargs)` - PUT with JSON serialization
### Retry decorator
```python
@awshttp.with_retry(retries=3, backoff=1.0)
def my_api_call():
return awshttp.get('https://api.example.com/endpoint')
```
### Environment variables
- `AWSHTTP_TIMEOUT` - Default timeout in seconds
- `AWSHTTP_VERIFY_SSL` - SSL verification (true/false)
## Project Structure
```
awshttp/
├── awshttp/ # Main package
├── tests/ # Test suite
├── examples/ # Usage examples
├── docs/ # Documentation
└── .github/ # GitHub Actions workflows
```
## Development
```bash
# Using uv (recommended)
uv sync --all-extras
uv run pytest tests/
# Or using make
make dev # Install with dev dependencies
make test # Run tests
make build # Build package
```
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "awshttp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "aws, sigv4, http, requests, lambda, api-gateway",
"author": "Sam Fakhreddine",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cc/38/a0f532df213366a9238c217acdc1b42104bfea04267c589d6843ac38bd72/awshttp-0.1.2.tar.gz",
"platform": null,
"description": "# awshttp\n\nMinimal Python library for making AWS SigV4 signed HTTP requests.\n\nPerfect for Lambda functions and scripts that need to call AWS APIs with automatic credential detection.\n\n**Automate AWS Console actions programmatically!** Capture API calls from your browser's Network tab and replay them in Python.\n\n## Installation\n\n```sh\n# Using pip\npip install awshttp\n\n# Using uv (recommended)\nuv pip install awshttp\n```\n\n## Usage\n\n```python\nimport awshttp\n\n# GET request\nresponse = awshttp.get(\n uri='https://my-api.execute-api.us-east-1.amazonaws.com/prod/endpoint',\n service='execute-api'\n)\nprint(response.json())\n\n# POST request\nresponse = awshttp.post(\n uri='https://my-api.execute-api.us-east-1.amazonaws.com/prod/endpoint',\n service='execute-api',\n data='{\"key\": \"value\"}',\n headers={'content-type': 'application/json'}\n)\n\n# PUT request with JSON helper\nresponse = awshttp.put_json(\n uri='https://uxc.us-east-1.api.aws/v1/account-color',\n service='uxc',\n region='us-east-1',\n data={'color': 'green'}\n)\n\n# Or use the main request function\nresponse = awshttp.request(\n uri='https://my-api.execute-api.us-east-1.amazonaws.com/prod/endpoint',\n method='POST',\n service='execute-api',\n data='{\"key\": \"value\"}',\n headers={'content-type': 'application/json'}\n)\n```\n\n## Features\n\n- Automatic AWS credential detection (IAM roles, environment variables, ~/.aws/credentials)\n- Support for all AWS services (including undocumented Console APIs)\n- Simple requests-like interface\n- Retry logic with exponential backoff\n- JSON helpers for API calls\n- Environment variable configuration\n- Minimal dependencies (boto3, requests)\n\n## Automating Web Console Actions\n\nMany AWS Console features don't have official CLI/SDK support. Use browser DevTools to capture the API calls:\n\n1. Open AWS Console in your browser\n2. Open DevTools (F12) \u2192 Network tab\n3. Perform the action you want to automate\n4. Find the API call in the Network tab\n5. Copy the URL, method, headers, and body\n6. Replicate with awshttp!\n\n**Example: Change AWS Console account color**\n\n```python\nimport awshttp\n\n# This API isn't in the AWS SDK, but we can call it directly!\nresponse = awshttp.put_json(\n uri='https://uxc.us-east-1.api.aws/v1/account-color',\n service='uxc', # Service name from the URL\n region='us-east-1',\n data={'color': 'green'}\n)\n\nprint(f\"Status: {response.status_code}\")\nprint(f\"Response: {response.text}\")\n```\n\n**Tips for finding service names:**\n- Look at the URL: `https://SERVICE.REGION.api.aws/...`\n- Common services: `uxc` (console UI), `execute-api` (API Gateway), `s3`, `ec2`\n- Check the `authorization` header in DevTools for the service name\n\n**Advanced usage with retry:**\n\n```python\n# Retry failed requests automatically\n@awshttp.with_retry(retries=5, backoff=2.0)\ndef reliable_api_call():\n return awshttp.post_json(\n uri='https://api.example.com/endpoint',\n service='execute-api',\n data={'action': 'process'},\n timeout=30\n )\n\nresponse = reliable_api_call()\n```\n\n## API Reference\n\n### awshttp.request(uri, method='GET', service='execute-api', region=None, headers=None, data='', verify=True, allow_redirects=False, timeout=None, session=None)\n\nMain function for making signed AWS requests.\n\n**Parameters:**\n- `uri` (str): Full URL to request\n- `method` (str): HTTP method (GET, POST, PUT, DELETE, PATCH)\n- `service` (str): AWS service name for signing\n- `region` (str | None): AWS region (auto-detects if None)\n- `headers` (dict | None): HTTP headers\n- `data` (str | bytes): Request body\n- `verify` (bool): Verify SSL certificates\n- `allow_redirects` (bool): Follow redirects\n- `timeout` (float | None): Request timeout in seconds\n- `session` (boto3.Session | None): Boto3 session for credential reuse\n\n**Returns:** `requests.Response` object\n\n### Convenience methods\n\n- `awshttp.get(uri, **kwargs)` - GET request\n- `awshttp.post(uri, data='', **kwargs)` - POST request\n- `awshttp.put(uri, data='', **kwargs)` - PUT request\n- `awshttp.delete(uri, **kwargs)` - DELETE request\n- `awshttp.patch(uri, data='', **kwargs)` - PATCH request\n- `awshttp.post_json(uri, data={}, **kwargs)` - POST with JSON serialization\n- `awshttp.put_json(uri, data={}, **kwargs)` - PUT with JSON serialization\n\n### Retry decorator\n\n```python\n@awshttp.with_retry(retries=3, backoff=1.0)\ndef my_api_call():\n return awshttp.get('https://api.example.com/endpoint')\n```\n\n### Environment variables\n\n- `AWSHTTP_TIMEOUT` - Default timeout in seconds\n- `AWSHTTP_VERIFY_SSL` - SSL verification (true/false)\n\n## Project Structure\n\n```\nawshttp/\n\u251c\u2500\u2500 awshttp/ # Main package\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 examples/ # Usage examples\n\u251c\u2500\u2500 docs/ # Documentation\n\u2514\u2500\u2500 .github/ # GitHub Actions workflows\n```\n\n## Development\n\n```bash\n# Using uv (recommended)\nuv sync --all-extras\nuv run pytest tests/\n\n# Or using make\nmake dev # Install with dev dependencies\nmake test # Run tests\nmake build # Build package\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Minimal AWS SigV4 signed HTTP requests library",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/sam-fakhreddine/awshttp",
"Issues": "https://github.com/sam-fakhreddine/awshttp/issues",
"Repository": "https://github.com/sam-fakhreddine/awshttp"
},
"split_keywords": [
"aws",
" sigv4",
" http",
" requests",
" lambda",
" api-gateway"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "72fa4b319f34605fb2a54145356eafeaf63301f13f27c9fb3a4c38580039a89c",
"md5": "f54c6456a2f4e4abd9f19384defb49fc",
"sha256": "b9fbc50bdfba7ffe1a884aa9240edc62cddcf22fae943af93e4f1e7dc0885099"
},
"downloads": -1,
"filename": "awshttp-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f54c6456a2f4e4abd9f19384defb49fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6522,
"upload_time": "2025-10-24T01:20:56",
"upload_time_iso_8601": "2025-10-24T01:20:56.676920Z",
"url": "https://files.pythonhosted.org/packages/72/fa/4b319f34605fb2a54145356eafeaf63301f13f27c9fb3a4c38580039a89c/awshttp-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cc38a0f532df213366a9238c217acdc1b42104bfea04267c589d6843ac38bd72",
"md5": "56206a1c4b1513f54c4f1cccd05537fd",
"sha256": "ce9a157cc71d69f592f7421b1a5fd8a74879c8ba64010f79515feea2a8d93065"
},
"downloads": -1,
"filename": "awshttp-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "56206a1c4b1513f54c4f1cccd05537fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6448,
"upload_time": "2025-10-24T01:20:57",
"upload_time_iso_8601": "2025-10-24T01:20:57.440116Z",
"url": "https://files.pythonhosted.org/packages/cc/38/a0f532df213366a9238c217acdc1b42104bfea04267c589d6843ac38bd72/awshttp-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 01:20:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sam-fakhreddine",
"github_project": "awshttp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "configargparse",
"specs": []
},
{
"name": "configparser",
"specs": []
},
{
"name": "botocore",
"specs": []
}
],
"lcname": "awshttp"
}
JSON
