# requests-async
[](https://badge.fury.io/py/requests-async)
[](https://pypi.org/project/requests-async/)
[](https://pypi.org/project/requests-async/)
A simple, elegant async HTTP client for Python, built on top of [httpx](https://www.python-httpx.org/). Get the power of async HTTP requests with a familiar requests-like interface - just add `await`!
## Why requests-async?
- 🚀 **Blazing Fast**: Built on httpx for maximum performance
- 🔄 **Drop-in Replacement**: Same API as requests, just add `await`
- 📦 **Simple**: Minimal learning curve if you know requests
- 🛡️ **Reliable**: Built on battle-tested httpx foundation
- 🎯 **Focused**: Does one thing exceptionally well
## Installation
```bash
pip install requests-async
```
## Quick Start
### Basic Usage
```python
import asyncio
import requests_async
async def main():
# Simple GET request
response = await requests_async.get('https://httpbin.org/get')
print(response.json())
# POST with JSON data
response = await requests_async.post(
'https://httpbin.org/post',
json={'key': 'value'}
)
print(response.status_code)
asyncio.run(main())
```
### Using Proxies
requests-async supports both HTTP and SOCKS5 proxies:
```python
import asyncio
import requests_async
async def main():
# HTTP proxy
http_proxy = "http://user:pass@proxy:port"
async with requests_async.AsyncSession(proxies=http_proxy) as session:
response = await session.get('https://httpbin.org/ip')
print(response.json())
# SOCKS5 proxy
socks5_proxy = "socks5://user:pass@proxy:port"
async with requests_async.AsyncSession(proxies=socks5_proxy) as session:
response = await session.get('https://httpbin.org/ip')
print(response.json())
# Different proxies for different protocols
proxies = {
"http://": "http://proxy:port",
"https://": "https://proxy:port"
}
async with requests_async.AsyncSession(proxies=proxies) as session:
response = await session.get('https://httpbin.org/ip')
print(response.json())
asyncio.run(main())
```
## API Reference
### Convenience Functions
All functions return an `httpx.Response` object with the same interface as requests.
```python
# All HTTP methods supported
response = await requests_async.get(url, **kwargs)
response = await requests_async.post(url, **kwargs)
response = await requests_async.put(url, **kwargs)
response = await requests_async.delete(url, **kwargs)
response = await requests_async.patch(url, **kwargs)
response = await requests_async.head(url, **kwargs)
response = await requests_async.options(url, **kwargs)
response = await requests_async.request(method, url, **kwargs)
```
### AsyncSession Class
For better performance with multiple requests:
```python
async with requests_async.AsyncSession(timeout=30.0, headers=headers) as session:
response = await session.get(url)
```
**AsyncSession Parameters:**
- `timeout`: Request timeout in seconds (default: 30.0)
- `headers`: Default headers for all requests
- `proxies`: Proxy configuration (string or dict)
- String: `"http://proxy:port"` or `"socks5://proxy:port"`
- Dict: `{"http://": "http://proxy:port", "https://": "https://proxy:port"}`
- `**kwargs`: Any additional httpx.AsyncClient parameters
### Response Object
The response object is an `httpx.Response` with all the familiar methods:
```python
response.status_code # HTTP status code
response.headers # Response headers
response.text # Response text
response.content # Response bytes
response.json() # Parse JSON response
response.raise_for_status() # Raise exception for 4xx/5xx status codes
```
## Examples
### Different Data Types
```python
# JSON data
await requests_async.post(url, json={'key': 'value'})
# Form data
await requests_async.post(url, data={'key': 'value'})
# Files
with open('file.txt', 'rb') as f:
await requests_async.post(url, files={'file': f})
# Custom headers
await requests_async.get(url, headers={'Authorization': 'Bearer token'})
# Query parameters
await requests_async.get(url, params={'q': 'search', 'limit': 10})
```
### Error Handling
```python
import requests_async
from httpx import HTTPError, TimeoutException
try:
response = await requests_async.get('https://httpbin.org/status/404')
response.raise_for_status() # Raises exception for 4xx/5xx
except HTTPError as e:
print(f"HTTP error: {e}")
except TimeoutException:
print("Request timed out")
```
### Advanced Usage
```python
# Custom timeout and headers
async with requests_async.AsyncSession(
timeout=60.0,
headers={'User-Agent': 'MyBot/1.0'}
) as session:
# These headers will be used for all requests
response = await session.get('https://api.example.com/data')
# Override timeout for specific request
response = await session.post(
'https://api.example.com/upload',
json=large_data,
timeout=120.0
)
```
## Comparison with requests
| Feature | requests | requests-async |
|---------|----------|----------------|
| Sync/Async | Synchronous | Asynchronous |
| Performance | Good | Excellent |
| API | `requests.get()` | `await requests_async.get()` |
| Sessions | `requests.Session()` | `async with requests_async.AsyncSession()` |
| Error Handling | requests exceptions | httpx exceptions |
## Migration from requests
Simply replace `requests` with `requests_async` and add `await`:
```python
# Before (requests)
response = requests.get('https://api.example.com')
# After (requests-async)
response = await requests_async.get('https://api.example.com')
```
For sessions:
```python
# Before (requests)
with requests.Session() as session:
response = session.get('https://api.example.com')
# After (requests-async)
async with requests_async.AsyncSession() as session:
response = await session.get('https://api.example.com')
```
## Development
### Running Tests
```bash
# Install development dependencies
pip install pytest pytest-asyncio
# Run tests
pytest
# Run with coverage
pip install pytest-cov
pytest --cov=requests_async
```
### API Testing Script
```bash
# Test all endpoints
python examples/api_test.py
```
## Requirements
- Python 3.7+
- httpx >= 0.23.0
## License
MIT License. See [LICENSE](LICENSE) for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Changelog
### 0.2.1
- Complete rewrite for simplicity and performance
- Cleaner API design
- Better documentation
- Simplified codebase
### 0.1.0
- Initial release
Raw data
{
"_id": null,
"home_page": null,
"name": "requests-async",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "http, async, requests, client, httpx, asyncio",
"author": "requests-async contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/be/c0/2cce791ad80f8f5c13b23c03db82d3d57b1a62d5bd12e2b20236bc74635e/requests_async-0.2.2.tar.gz",
"platform": null,
"description": "# requests-async\n\n[](https://badge.fury.io/py/requests-async)\n[](https://pypi.org/project/requests-async/)\n[](https://pypi.org/project/requests-async/)\n\nA simple, elegant async HTTP client for Python, built on top of [httpx](https://www.python-httpx.org/). Get the power of async HTTP requests with a familiar requests-like interface - just add `await`!\n\n## Why requests-async?\n\n- \ud83d\ude80 **Blazing Fast**: Built on httpx for maximum performance\n- \ud83d\udd04 **Drop-in Replacement**: Same API as requests, just add `await`\n- \ud83d\udce6 **Simple**: Minimal learning curve if you know requests\n- \ud83d\udee1\ufe0f **Reliable**: Built on battle-tested httpx foundation\n- \ud83c\udfaf **Focused**: Does one thing exceptionally well\n\n## Installation\n\n```bash\npip install requests-async\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport asyncio\nimport requests_async\n\nasync def main():\n # Simple GET request\n response = await requests_async.get('https://httpbin.org/get')\n print(response.json())\n \n # POST with JSON data\n response = await requests_async.post(\n 'https://httpbin.org/post',\n json={'key': 'value'}\n )\n print(response.status_code)\n\nasyncio.run(main())\n```\n\n### Using Proxies\n\nrequests-async supports both HTTP and SOCKS5 proxies:\n\n```python\nimport asyncio\nimport requests_async\n\nasync def main():\n # HTTP proxy\n http_proxy = \"http://user:pass@proxy:port\"\n async with requests_async.AsyncSession(proxies=http_proxy) as session:\n response = await session.get('https://httpbin.org/ip')\n print(response.json())\n \n # SOCKS5 proxy\n socks5_proxy = \"socks5://user:pass@proxy:port\"\n async with requests_async.AsyncSession(proxies=socks5_proxy) as session:\n response = await session.get('https://httpbin.org/ip')\n print(response.json())\n \n # Different proxies for different protocols\n proxies = {\n \"http://\": \"http://proxy:port\",\n \"https://\": \"https://proxy:port\"\n }\n async with requests_async.AsyncSession(proxies=proxies) as session:\n response = await session.get('https://httpbin.org/ip')\n print(response.json())\n\nasyncio.run(main())\n```\n\n## API Reference\n\n### Convenience Functions\n\nAll functions return an `httpx.Response` object with the same interface as requests.\n\n```python\n# All HTTP methods supported\nresponse = await requests_async.get(url, **kwargs)\nresponse = await requests_async.post(url, **kwargs)\nresponse = await requests_async.put(url, **kwargs)\nresponse = await requests_async.delete(url, **kwargs)\nresponse = await requests_async.patch(url, **kwargs)\nresponse = await requests_async.head(url, **kwargs)\nresponse = await requests_async.options(url, **kwargs)\nresponse = await requests_async.request(method, url, **kwargs)\n```\n\n### AsyncSession Class\n\nFor better performance with multiple requests:\n\n```python\nasync with requests_async.AsyncSession(timeout=30.0, headers=headers) as session:\n response = await session.get(url)\n```\n\n**AsyncSession Parameters:**\n- `timeout`: Request timeout in seconds (default: 30.0)\n- `headers`: Default headers for all requests\n- `proxies`: Proxy configuration (string or dict)\n - String: `\"http://proxy:port\"` or `\"socks5://proxy:port\"`\n - Dict: `{\"http://\": \"http://proxy:port\", \"https://\": \"https://proxy:port\"}`\n- `**kwargs`: Any additional httpx.AsyncClient parameters\n\n### Response Object\n\nThe response object is an `httpx.Response` with all the familiar methods:\n\n```python\nresponse.status_code # HTTP status code\nresponse.headers # Response headers\nresponse.text # Response text\nresponse.content # Response bytes\nresponse.json() # Parse JSON response\nresponse.raise_for_status() # Raise exception for 4xx/5xx status codes\n```\n\n## Examples\n\n### Different Data Types\n\n```python\n# JSON data\nawait requests_async.post(url, json={'key': 'value'})\n\n# Form data\nawait requests_async.post(url, data={'key': 'value'})\n\n# Files\nwith open('file.txt', 'rb') as f:\n await requests_async.post(url, files={'file': f})\n\n# Custom headers\nawait requests_async.get(url, headers={'Authorization': 'Bearer token'})\n\n# Query parameters\nawait requests_async.get(url, params={'q': 'search', 'limit': 10})\n```\n\n### Error Handling\n\n```python\nimport requests_async\nfrom httpx import HTTPError, TimeoutException\n\ntry:\n response = await requests_async.get('https://httpbin.org/status/404')\n response.raise_for_status() # Raises exception for 4xx/5xx\nexcept HTTPError as e:\n print(f\"HTTP error: {e}\")\nexcept TimeoutException:\n print(\"Request timed out\")\n```\n\n### Advanced Usage\n\n```python\n# Custom timeout and headers\nasync with requests_async.AsyncSession(\n timeout=60.0,\n headers={'User-Agent': 'MyBot/1.0'}\n) as session:\n \n # These headers will be used for all requests\n response = await session.get('https://api.example.com/data')\n \n # Override timeout for specific request\n response = await session.post(\n 'https://api.example.com/upload',\n json=large_data,\n timeout=120.0\n )\n```\n\n## Comparison with requests\n\n| Feature | requests | requests-async |\n|---------|----------|----------------|\n| Sync/Async | Synchronous | Asynchronous |\n| Performance | Good | Excellent |\n| API | `requests.get()` | `await requests_async.get()` |\n| Sessions | `requests.Session()` | `async with requests_async.AsyncSession()` |\n| Error Handling | requests exceptions | httpx exceptions |\n\n## Migration from requests\n\nSimply replace `requests` with `requests_async` and add `await`:\n\n```python\n# Before (requests)\nresponse = requests.get('https://api.example.com')\n\n# After (requests-async) \nresponse = await requests_async.get('https://api.example.com')\n```\n\nFor sessions:\n\n```python\n# Before (requests)\nwith requests.Session() as session:\n response = session.get('https://api.example.com')\n\n# After (requests-async)\nasync with requests_async.AsyncSession() as session:\n response = await session.get('https://api.example.com')\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install pytest pytest-asyncio\n\n# Run tests\npytest\n\n# Run with coverage\npip install pytest-cov\npytest --cov=requests_async\n```\n\n### API Testing Script\n\n```bash\n# Test all endpoints\npython examples/api_test.py\n```\n\n## Requirements\n\n- Python 3.7+\n- httpx >= 0.23.0\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Changelog\n\n### 0.2.1\n- Complete rewrite for simplicity and performance\n- Cleaner API design\n- Better documentation\n- Simplified codebase\n\n### 0.1.0\n- Initial release\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple async HTTP client with requests-like interface, powered by httpx",
"version": "0.2.2",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/requests-async/issues",
"Documentation": "https://github.com/yourusername/requests-async#readme",
"Homepage": "https://github.com/yourusername/requests-async",
"Source": "https://github.com/yourusername/requests-async"
},
"split_keywords": [
"http",
" async",
" requests",
" client",
" httpx",
" asyncio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b47225ae0cfa5eb16c04e7432ca581ea178241d82687a1af0e28e32b444be1fe",
"md5": "d836f60ee069a97b1f63292ec49951ee",
"sha256": "d4c0d948eb2bf92b606fb830f0983708a6a0778b61a4f24d6b211715a19a1d79"
},
"downloads": -1,
"filename": "requests_async-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d836f60ee069a97b1f63292ec49951ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6707,
"upload_time": "2025-08-02T17:11:02",
"upload_time_iso_8601": "2025-08-02T17:11:02.083221Z",
"url": "https://files.pythonhosted.org/packages/b4/72/25ae0cfa5eb16c04e7432ca581ea178241d82687a1af0e28e32b444be1fe/requests_async-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bec02cce791ad80f8f5c13b23c03db82d3d57b1a62d5bd12e2b20236bc74635e",
"md5": "a832c5521483f9f80603f53efd84ae79",
"sha256": "bbd16582b1c038df21a1c2d58a9a8cef32f1eed9d204da05deab66da6f65d385"
},
"downloads": -1,
"filename": "requests_async-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "a832c5521483f9f80603f53efd84ae79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7723,
"upload_time": "2025-08-02T17:11:03",
"upload_time_iso_8601": "2025-08-02T17:11:03.468710Z",
"url": "https://files.pythonhosted.org/packages/be/c0/2cce791ad80f8f5c13b23c03db82d3d57b1a62d5bd12e2b20236bc74635e/requests_async-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 17:11:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "requests-async",
"github_not_found": true,
"lcname": "requests-async"
}
JSON
