Build 2 — Async API Client Library

# Build 2 — Async API Client Library ## The brief Build a Python library for a public API. Async-first; with retries, timeouts, rate limiting; typed; tested. ## Choose your API Easy ones (no auth): - GitHub public API (rate-limited but no key needed for many endpoints). - JSONPlaceholder (https://jsonplaceholder.typicode.com). - Public weather API (Open-Meteo). - HackerNews API. With auth (more realistic): - Stripe API (test mode). - OpenAI API. - Twilio. ## Step 1: Project setup (10 min) ```bash uv init github-api-client uv add httpx tenacity pydantic uv add --dev pytest pytest-asyncio pytest-httpx pyright ``` ``` github-api-client/ ├── pyproject.toml ├── src/ │ └── github_api/ │ ├── __init__.py │ ├── client.py │ ├── models.py │ └── exceptions.py └── tests/ ├── test_client.py └── conftest.py ``` ## Step 2: Define models (15 min) ```python # src/github_api/models.py from pydantic import BaseModel from datetime import datetime class User(BaseModel): login: str id: int avatar_url: str name: str | None = None bio: str | None = None public_repos: int followers: int created_at: datetime class Repo(BaseModel): id: int name: str full_name: str description: str | None stargazers_count: int language: str | None created_at: datetime ``` ## Step 3: Define exceptions (5 min) ```python # src/github_api/exceptions.py class GitHubAPIError(Exception): """Base exception.""" class NotFoundError(GitHubAPIError): """User/repo not found.""" class RateLimitError(GitHubAPIError): """Rate limit exceeded.""" class AuthError(GitHubAPIError): """Authentication failed.""" ``` ## Step 4: Implement the client (30 min) ```python # src/github_api/client.py import asyncio from typing import Self import httpx from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type from .models import User, Repo from .exceptions import NotFoundError, RateLimitError, AuthError, GitHubAPIError class GitHubClient: """Async client for GitHub API.""" BASE_URL = "https://api.github.com" def __init__( self, token: str | None = None, timeout: float = 10.0, max_concurrent: int = 10, ): self.token = token self.timeout = timeout self._client: httpx.AsyncClient | None = None self._semaphore = asyncio.Semaphore(max_concurrent) async def __aenter__(self) -> Self: headers = {"Accept": "application/vnd.github+json"} if self.token: headers["Authorization"] = f"Bearer {self.token}" self._client = httpx.AsyncClient( base_url=self.BASE_URL, headers=headers, timeout=self.timeout, ) return self async def __aexit__(self, *args): if self._client: await self._client.aclose() @retry( stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10), retry=retry_if_exception_type((httpx.HTTPError,)), ) async def _get(self, path: str) -> dict: async with self._semaphore: assert self._client is not None response = await self._client.get(path) if response.status_code == 404: raise NotFoundError(f"Not found: {path}") elif response.status_code == 401: raise AuthError("Invalid token") elif response.status_code == 403 and "rate limit" in response.text.lower(): raise RateLimitError("Rate limit exceeded") elif response.status_code >= 400: raise GitHubAPIError(f"API error {response.status_code}: {response.text}") return response.json() async def get_user(self, username: str) -> User: data = await self._get(f"/users/{username}") return User(**data) async def get_repo(self, owner: str, name: str) -> Repo: data = await self._get(f"/repos/{owner}/{name}") return Repo(**data) async def get_user_repos(self, username: str, limit: int = 30) -> list[Repo]: data = await self._get(f"/users/{username}/repos?per_page={limit}") return [Repo(**item) for item in data] ``` Notes: - `__aenter__` / `__aexit__`: async context manager. - Semaphore for bounded concurrency. - Tenacity for retries on network errors. - Pydantic models for parsed responses. - Specific exceptions for different failures. ## Step 5: Tests with mocked HTTP (25 min) ```python # tests/conftest.py import pytest from pytest_httpx import HTTPXMock @pytest.fixture def mock_user_data(): return { "login": "octocat", "id": 1, "avatar_url": "https://example.com/avatar.png", "name": "Octocat", "bio": "GitHub mascot", "public_repos": 8, "followers": 9001, "created_at": "2008-01-14T04:33:35Z", } # tests/test_client.py import pytest from github_api.client import GitHubClient from github_a