astra-client 0.1.0

Async HTTP client with clean API and automatic error handling

astra-client

Async HTTP client for Python with clean API and automatic error handling

---

Key Features

• Zero-boilerplate URLs — write "google.com" instead of "https://google.com"
• Automatic error handling — 4xx/5xx responses raise typed exceptions, no manual checks needed
• Async context managers — clean resource lifecycle with async with
• Full HTTP verb coverage — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
• Typed exception hierarchy — catch exactly what you need, from NotFoundError to AstraHttpError
• Python 3.10+ — modern type hints throughout (X | None, dict[str, Any])

---

Installation

pip install astra-client

uv add astra-client

---

Quick Start

import asyncio
import astra

async def main():
    async with astra.ClientSession() as session:
        async with session.get("httpbin.org/get") as response:
            print(response.status)
            data = await response.json()
            print(data)

asyncio.run(main())

No scheme? No problem. astra-client automatically prepends https:// if missing.

POST with JSON

async with astra.ClientSession() as session:
    async with session.post(
        "httpbin.org/post",
        json={"name": "astra", "fast": True},
    ) as response:
        print(await response.json())

Custom headers & base URL

async with astra.ClientSession(
    base_url="https://api.example.com",
    headers={"Authorization": "Bearer TOKEN"},
    timeout=10.0,
) as session:
    async with session.get("/users/me") as response:
        user = await response.json()

---

Error Handling

astra-client raises typed exceptions automatically — no need to call raise_for_status() manually.

import astra

async def fetch():
    try:
        async with astra.ClientSession() as session:
            async with session.get("httpbin.org/status/404") as response:
                ...
    except astra.NotFoundError:
        print("Resource not found")
    except astra.UnauthorizedError:
        print("Invalid credentials")
    except astra.TooManyRequestsError:
        print("Rate limit hit — slow down")
    except astra.TimeoutError:
        print("Request timed out")
    except astra.ConnectionError:
        print("Could not reach the server")
    except astra.AstraHttpError as e:
        print(f"Unexpected error: {e}")

Exception Hierarchy

AstraHttpError
├── NetworkError
│   ├── ConnectionError
│   ├── TimeoutError
│   ├── TooManyRedirectsError
│   └── InvalidURLError
└── HTTPStatusError
    ├── ClientError          (4xx)
    │   ├── BadRequestError          400
    │   ├── UnauthorizedError        401
    │   ├── ForbiddenError           403
    │   ├── NotFoundError            404
    │   ├── MethodNotAllowedError    405
    │   ├── UnprocessableEntityError 422
    │   └── TooManyRequestsError     429
    └── ServerError          (5xx)
        ├── InternalServerError      500
        ├── BadGatewayError          502
        ├── ServiceUnavailableError  503
        └── GatewayTimeoutError      504

---

Response API

async with session.get("httpbin.org/json") as response:
    response.status        # int — HTTP status code
    response.headers       # httpx.Headers

    text = await response.text()   # str
    data = await response.json()   # Any
    raw  = await response.read()   # bytes

---

Requirements

• Python 3.10+
• httpx >= 0.28.1

---

License

astra-client is released under the MIT License.