gugilla-aakash/hakiapi

Purpose and public entry points

HakiAPI is a Python 3.10+ SDK foundation for building resilient HTTP API clients, with bundled GitHub, Gmail, and Google Calendar clients. Public imports are organized through hakiapi/__init__.py; consumers either instantiate bundled clients or subclass the synchronous base client. Runnable usage references are example_oauth.py and examples/example_github.py.

Synchronous request core

BaseAPIClient centralizes session lifecycle, base-URL request routing, authentication attachment, timeouts, response parsing, raw-response access, and HTTP-status mapping. Endpoint methods in bundled or downstream clients should stay thin and call its verb methods.

• hakiapi/core/base_client.py

• hakiapi/core/exceptions.py

• hakiapi/core/retry.py

Flow: client endpoint → _request() → requests.Session with mounted urllib3 retry adapters → external API → JSON/text or typed exception.

Authentication and OAuth boundary

Authentication strategies plug into requests through AuthBase: bearer, header/query API keys, HMAC signing, and OAuth-backed bearer injection. Google OAuth is separate from API transport: it manages browser authorization, localhost redirect capture, CSRF state validation, token exchange, persistence, and optional explicit refresh.

• hakiapi/core/auth.py

• hakiapi/core/oauth/google.py

• hakiapi/core/oauth/token_store.py

The OAuth integration touches Google authorization/token endpoints, the local browser, and a one-shot localhost HTTP server. Token persistence is local filesystem JSON with atomic replacement and restrictive permissions.

Resilience and failure semantics

Retries occur before final error mapping for retryable HTTP statuses and network failures. Typed exceptions provide a uniform boundary for application code across client implementations. A standalone, thread-safe circuit breaker wraps synchronous callables and transitions CLOSED → OPEN → HALF_OPEN to prevent repeated downstream failures.

• hakiapi/core/retry.py

• hakiapi/core/exceptions.py

• hakiapi/core/circuit_breaker.py

Pagination abstraction

A lazy paginator repeatedly invokes a client with raw_response=True, interprets response-specific item and continuation conventions, and yields items without making pagination part of each endpoint implementation. It supports Link-header and token-based styles used by the bundled services.

• hakiapi/core/paginator.py

• hakiapi/core/base_client.py

Async transport path

AsyncBaseAPIClient is an independent asyncio/httpx implementation, not a wrapper around the sync core. It recreates retry/backoff, typed exceptions, endpoint SSRF protections, disabled redirect following, response-size limits, and async context-manager cleanup. httpx is an optional runtime dependency.

• hakiapi/core/async_base_client.py

• hakiapi/core/exceptions.py

Bundled service adapters

Bundled clients specialize the common core with service URLs, authentication conventions, resource-oriented methods, and service-specific pagination. GitHub adds REST and GraphQL execution, including GraphQL payload-error detection; Gmail and Calendar expose resource groupings for their Google APIs.

• hakiapi/clients/github.py

• hakiapi/clients/gmail.py

• hakiapi/clients/google_calendar.py

External service boundaries are GitHub REST/GraphQL APIs, Gmail API, Google Calendar API, and Google OAuth endpoints. Packaging/release infrastructure is defined in pyproject.toml and .github/workflows/release.yml.