zerohttp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ZeroHTTP is a lightweight HTTP client library for Python that provides a simple interface for making HTTP requests with various authentication methods. The library is built using Python's standard urllib modules and supports both Basic and Bearer authentication, along with OAuth2 interactive flows for Microsoft Entra (Azure AD).

Development Commands

Installation and Setup

# Install the package in development mode
pip install -e .

# Install dependencies
pip install -r requirements.txt

Build and Package

# Build the package
python -m build

# Install build dependencies if needed
pip install --upgrade build

Architecture Overview

The library follows a modular architecture with the following key components:

Core HTTP Client (src/zerohttp/http.py)

• HTTPClient: Main client class that handles HTTP requests (GET, POST)
• Response: Wrapper for HTTP responses with JSON parsing capability
• Param: Helper class for URL parameter handling
• Uses Python's built-in urllib.request for HTTP operations
• Supports automatic authentication header injection
• Handles both JSON and form-encoded request bodies

Authentication System (src/zerohttp/auth/)

• BasicAuthentication: Handles username/password authentication using base64 encoding
• BearerAuthentication: Manages token-based Bearer authentication
• InteractiveProvider: OAuth2 flow implementation for interactive authentication
• All authentication classes implement __str__ method for proper header formatting

Provider Integration (src/zerohttp/providers/)

• Entra: Microsoft Entra ID OAuth2 provider for user authentication flows
• EntraApp: Microsoft Entra ID application authentication using client credentials
• Includes local HTTP server for OAuth2 callback handling
• Automatic browser launching for interactive authentication

Key Design Patterns

Authentication Integration

The HTTPClient accepts an auth parameter that can be any authentication object. When making requests, it automatically adds the appropriate Authorization header:

# Authentication objects expose their type and token
auth.type  # "Basic" or "Bearer"
auth.token  # The actual credentials

OAuth2 Interactive Flow

The interactive authentication flow:

1. Starts a local HTTP server on localhost:8000
2. Opens browser for user authentication
3. Waits for callback with authorization code
4. Exchanges code for access token
5. Returns BearerAuthentication object

URL Building

• Supports base_url for common endpoint prefixes
• Automatic parameter encoding and URL construction
• link() method for URL generation without making requests
• webbrowser() method for direct browser opening

Development Notes

Package Structure

• Uses src/ layout with proper package configuration
• pyproject.toml defines build metadata using setuptools
• Package exports configured in src/zerohttp/__init__.py

Dependencies

• Minimal external dependencies (only setuptools for building)
• Relies on Python standard library for HTTP operations
• Compatible with Python 3.12+

Error Handling

• HTTP errors are re-raised after printing response content
• OAuth2 flows raise RuntimeError for authentication failures
• Server startup/shutdown handled in separate threads

Common Usage Patterns

Basic HTTP Requests

from zerohttp import HTTPClient

client = HTTPClient(base_url="https://api.example.com")
response = client.get("/users", params=[("page", "1"), ("limit", "10")])
data = response.json()

Authentication

from zerohttp import HTTPClient
from zerohttp.auth import BasicAuthentication, BearerAuthentication

# Basic auth
auth = BasicAuthentication("username", "password")
client = HTTPClient(auth=auth)

# Bearer token auth
auth = BearerAuthentication("your-token-here")
client = HTTPClient(auth=auth)

Microsoft Entra Integration

from zerohttp.providers import Entra, EntraApp

# Interactive user authentication
entra = Entra(tenant="your-tenant-id", client=("client-id", "client-secret"), scope="https://graph.microsoft.com/.default")
auth = entra.authenticate()
client = HTTPClient(auth=auth)

# Application authentication
app = EntraApp(tenant="your-tenant-id", client=("client-id", "client-secret"))
auth = app.authenticate()
client = HTTPClient(auth=auth)