Reference

Complete API reference, comparisons, and practical examples

Comparison with Other Libraries

AtomHTTP delivers the broadest feature set among Python HTTP clients: progress callbacks, full interceptor chain, concurrent helpers, Blob/ArrayBuffer support, and fine‑grained limits — all with a clean, modern API.

Feature
AtomHTTP		requestsaiohttphttpx
Async/Await
Upload Progress
Download Progress
InterceptorsFullLimited
validateStatusBuilt-in
Blob/ArrayBufferresponse_typecontentread()content
Base URL
Concurrent Helpers.all()/.spread()ThreadPoolmanualmanual
Type HintsFullPartial

AtomHTTP combines the best features from existing libraries while adding unique capabilities like progress tracking, a full interceptor system, and comprehensive type hints. It is the only Python HTTP client that provides upload/download progress callbacks out of the box.

Feature Comparison

Compare AtomHTTP with other popular HTTP clients side by side. Each tab shows the same feature implemented in different libraries.

Upload Progress Tracking

Supported

Upload and download progress tracking with real-time callbacks

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import asyncio
from atomhttp import AtomHTTP

def on_upload(loaded, total):
    percent = (loaded / total) * 100
    print(f"Upload: {percent:.1f}% ({loaded}/{total} bytes)")

async def upload_file():
    client = AtomHTTP({'baseURL': 'https://httpbin.org'})

    with open('test.txt', 'rb') as f:
        resp = await client.post(
            '/post',
            data=f,
            on_upload_progress=on_upload
        )

    print("AtomHTTP Status:", resp.status)
    await client.close()

asyncio.run(upload_file())

Concurrent Requests

Supported

Execute multiple requests in parallel

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import asyncio
from atomhttp import AtomHTTP

async def fetch_posts():
    client = AtomHTTP({'baseURL': 'https://jsonplaceholder.typicode.com'})
    
    tasks = [
        client.get('/posts/1'),
        client.get('/posts/2'),
        client.get('/posts/3')
    ]
    
    responses = await AtomHTTP.all(tasks)
    
    for resp in responses:
        print(f"AtomHTTP: Post {resp.data['id']} → {resp.data['title'][:30]}...")
    
    await client.close()

asyncio.run(fetch_posts())

Status Validation

Supported

Automatic HTTP status code validation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import asyncio
from atomhttp import AtomHTTP
from atomhttp.errors import AtomHTTPRequestError

async def check_status():
    client = AtomHTTP({
        'baseURL': 'https://httpbin.org',
        'validateStatus': lambda status: status == 200
    })
    
    try:
        resp1 = await client.get('/status/200')
        print(f"AtomHTTP: Status {resp1.status} OK")
        
        resp2 = await client.get('/status/404')
        print(f"This won't print")
        
    except AtomHTTPRequestError as e:
        print(f"AtomHTTP: Request failed with status {e.response.status}")
    
    await client.close()

asyncio.run(check_status())

Binary Data (Blob)

Supported

Binary data handling (images, PDFs, etc.)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import asyncio
from atomhttp import AtomHTTP

async def download_image():
    client = AtomHTTP()
    
    response = await client.get(
        'https://httpbin.org/image/png',
        response_type='blob'
    )
    
    with open('atomhttp_image.png', 'wb') as f:
        f.write(response.data)
    
    print(f"AtomHTTP: Saved {len(response.data)} bytes")
    await client.close()

asyncio.run(download_image())

Request/Response Interceptors

Supported

Modify requests/responses globally

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import asyncio
from atomhttp import AtomHTTP

async def main():
    client = AtomHTTP()
    
    async def log_interceptor(config):
        print(f"Request: {config.method} {config.url}")
        return config
    
    client.interceptors.use(log_interceptor)
    
    response = await client.get('https://httpbin.org/get')
    await client.close()

asyncio.run(main())

Custom Headers

Supported

Custom headers support

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import asyncio
from atomhttp import AtomHTTP

async def custom_headers():
    client = AtomHTTP()
    
    response = await client.get(
        'https://httpbin.org/headers',
        headers={
            'Authorization': 'Bearer my-token-123',
            'X-Custom-Header': 'my-value'
        }
    )
    
    headers = response.data.get('headers', {})
    print(f"AtomHTTP: Authorization = {headers.get('Authorization')}")
    await client.close()

asyncio.run(custom_headers())

Why AtomHTTP Stands Out

AtomHTTP is the only library that combines all these features in one package:

Upload Progress

Real-time upload progress callbacks

Download Progress

Track download progress with ease

Interceptors

Request/response middleware

Status Validation

Built-in validateStatus

Concurrent Helpers

.all() and .spread() methods

Blob/ArrayBuffer

Simple binary data handling

AtomHTTP is the only Python HTTP client that can handle file uploads with progress tracking, concurrent requests with .all()/.spread(), automatic status validation, binary data with response_type="blob", and request/response interceptors — all in a single library.

API Methods Reference

Complete reference of all available methods on the AtomHTTP client and helper functions.

MethodDescriptionExample
client.get(url, params)HTTP GET requestawait client.get("/users")
client.post(url, data)HTTP POST requestawait client.post("/users", data={...})
AtomHTTP.all(tasks)Execute concurrent requestsresponses = await AtomHTTP.all(tasks)
client.close()Clean up resourcesawait client.close()

Error Codes Reference

AtomHTTP provides standardized error codes for programmatic error handling.

Error CodeDescriptionException Type
ERR_BAD_REQUESTBad request (4xx) or malformed requestAtomHTTPRequestError
ERR_NETWORKNetwork connectivity issuesAtomHTTPNetworkError
ECONNABORTEDRequest exceeded timeout limitAtomHTTPTimeoutError

Response Types

AtomHTTP supports multiple response types for different use cases.

json

Parse response as JSON (dict/list). Default option for API calls.

text

Return response as plain text string. Good for HTML, CSV, plain text.

blob

Return response as bytes. Perfect for images, PDFs, ZIP files.

stream

Return async iterator. Best for very large files and video streaming.