headgate 0.3.0__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {headgate-0.3.0 → headgate-0.5.0}/.gitignore +3 -0
- {headgate-0.3.0 → headgate-0.5.0}/CHANGELOG.md +36 -1
- {headgate-0.3.0 → headgate-0.5.0}/PKG-INFO +26 -5
- {headgate-0.3.0 → headgate-0.5.0}/README.md +24 -3
- {headgate-0.3.0 → headgate-0.5.0}/docs/auth.md +1 -1
- headgate-0.5.0/docs/comparison.md +198 -0
- headgate-0.5.0/docs/index.md +201 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/pagination.md +46 -3
- {headgate-0.3.0 → headgate-0.5.0}/docs/security.md +23 -0
- headgate-0.5.0/docs/standards.md +107 -0
- headgate-0.5.0/docs/stylesheets/extra.css +246 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/testing.md +1 -1
- headgate-0.5.0/examples/github_client.py +86 -0
- {headgate-0.3.0 → headgate-0.5.0}/pyproject.toml +3 -2
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/__init__.py +4 -1
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_client.py +7 -2
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/errors.py +15 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pagination/__init__.py +2 -1
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pagination/_pager.py +23 -7
- headgate-0.5.0/src/headgate/pagination/_paginated.py +149 -0
- headgate-0.5.0/tests/examples/test_github_client.py +76 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/__snapshots__/test_api_surface.ambr +28 -12
- {headgate-0.3.0 → headgate-0.5.0}/tests/pagination/test_paginate.py +214 -1
- headgate-0.3.0/src/headgate/pagination/_paginated.py +0 -82
- {headgate-0.3.0 → headgate-0.5.0}/LICENSE +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/breaker.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/caching.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/configuration.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/deadlines.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/design.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/errors.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/mutation-testing.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/observability.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/rate-budgets.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/responses.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/retries.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/docs/streaming.md +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/examples/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/examples/boundary.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/examples/orders_client.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/examples/quickstart.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/examples/series_client.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_attempts.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_auth.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_body.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_codec.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_context.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_origin.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_retry_after.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_seams.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_switch.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_time.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_curl.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_deprecation.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_failures.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_middleware.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_options.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_redirects.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_request_body.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_responses.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_stack.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_url.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_user_agent.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_view.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_breaker.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_registry.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_scope.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_conditional.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_credentials.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/curl.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/health.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/msgspec.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/otel.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pagination/_link.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/py.typed +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pydantic.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_budget.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_budgets.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_feedback.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_fields.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_inflight.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_rate.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_budget.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_classify.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_tracking.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_addresses.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_credentials.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_downgrade.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/streaming/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/streaming/_stream.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_breakers.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_recording.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_time.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/faults.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/auth/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_cached_token_auth.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_credential_stampers.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_flows_are_uniform.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_header_and_query_auth.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_mint_failures.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_charging.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_integration.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_keying.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_state_machine.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_registry.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/_helpers.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_conditional.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_credentials.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_extension_passthrough.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_fallback.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_filters.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_held_bodies.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_integration.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_shared_downloads.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_store_on_accept.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_call_options.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_client.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_deadline.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_error_details.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_error_messages.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_failure_policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_invalid_url.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_middleware.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_options.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_redirect_identity.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_response_size_cap.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_retry_opt_out.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_timeouts_fit_deadline.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_verbs.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/conftest.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/core/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_context.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_origin.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_retry_after.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_errors.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_event_stream.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_msgspec.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_pydantic.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_responses.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/errors/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/errors/__snapshots__/test_error_messages_snapshot.ambr +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/errors/test_error_messages_snapshot.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/examples/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_docs.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_orders_client.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_quickstart.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_series_client.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/_support.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_breaker_gate.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_cache_and_auths.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_deadline.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_destinations.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_hedging.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_pagination_credentials.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_replayable_body.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_retry_and_rate.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_views.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/__snapshots__/test_snapshots.ambr +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/_support.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_accept.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_deprecation.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_otel.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_otel_isolation.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_snapshots.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_with_options.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_api_surface.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_boundaries.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_contracts.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_import_isolation.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_metadata.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/pagination/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/pagination/test_link_header.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/performance/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/performance/test_memory.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/properties/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/properties/test_policy_properties.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/properties/test_url_properties.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_budget.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_client_feedback.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_feedback.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_in_flight.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_rate.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_rate_limit_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_budget_and_classify.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_client_retries.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_faults.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_parking_and_hedging.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_policy.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_properties.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_tracking.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/_servers.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/_web.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/certs/ca.pem +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/certs/server.pem +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_addresses.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_credential_origins.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_origin_properties.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_pinned_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_redirect_hardening.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_ssrf_guard.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/streaming/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/streaming/test_request_bodies.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/streaming/test_stream.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/breakers.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/budgets.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/clients.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/events.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/responses.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/tokens.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/support/wire.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/testing/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_breakers.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_cassettes.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_fake_transport.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_recording.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_time.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/transport/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/transport/test_curl.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/transport/test_health.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/urls/__init__.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_empty_segment.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_path_escaping.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_route_template.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_sanitize_url.py +0 -0
- {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_secret_query_params.py +0 -0
|
@@ -6,6 +6,39 @@ change the public API; such changes are listed under **Changed** and **Removed**
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.5.0] - 2026-10-26
|
|
10
|
+
|
|
11
|
+
Adds `Paginated.collect()`, so a walk becomes a list in one call, bounded by items as well as pages. Nothing changes for
|
|
12
|
+
existing code.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- `Paginated.collect(max_items=None)` returns a walk's items as a list; with `max_items`, at most that many, fetching
|
|
17
|
+
no page past the one that fills it ([#19](https://github.com/kelsayed17/headgate/issues/19)).
|
|
18
|
+
- A [standards page](https://kelsayed17.github.io/headgate/standards/) mapping each RFC and draft headgate follows to
|
|
19
|
+
what it does, and a comparison with about 30 HTTP, retry, rate-limit, cache, breaker and testing libraries.
|
|
20
|
+
|
|
21
|
+
## [0.4.0] - 2026-10-26
|
|
22
|
+
|
|
23
|
+
Bounds `paginate()`: a page budget, and a stop at pages with no items. The stop changes what three pagers do by
|
|
24
|
+
default, so this is a minor release: see **Changed**.
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- A page budget for `paginate()`: `limit=PageLimit(max_pages)` raises the new `PageLimitError` once the budget is spent
|
|
29
|
+
with pages still to come, or with `on_limit="stop"` ends the walk there
|
|
30
|
+
([#14](https://github.com/kelsayed17/headgate/issues/14)).
|
|
31
|
+
- A documentation site at <https://kelsayed17.github.io/headgate/>, built from `docs/`, with a page comparing headgate
|
|
32
|
+
with tenacity, stamina and a hand-rolled client.
|
|
33
|
+
- `examples/github_client.py`: a tested client for a few GitHub REST endpoints.
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
|
|
37
|
+
- `Cursor`, `NextUrl` and `LinkHeader` stop at a page with no items, as `Offset` already did, instead of following its
|
|
38
|
+
link: a link that advances while returning nothing made the walk spend requests for nothing. Pass
|
|
39
|
+
`stop_on_empty=False` for an endpoint that sends empty pages mid-walk
|
|
40
|
+
([#15](https://github.com/kelsayed17/headgate/issues/15)).
|
|
41
|
+
|
|
9
42
|
## [0.3.0] - 2026-10-26
|
|
10
43
|
|
|
11
44
|
Fixes four bugs where a call's deadline, its timeouts, the rate budget and the cache disagreed. One of them makes a
|
|
@@ -215,7 +248,9 @@ Python 3.14.
|
|
|
215
248
|
- The `headgate.msgspec` and `headgate.pydantic` codec flavors, the optional `AsyncCurlTransport` (`headgate[curl]`),
|
|
216
249
|
`headgate.health` snapshots and `headgate.policy.policy_disabled()`.
|
|
217
250
|
|
|
218
|
-
[Unreleased]: https://github.com/kelsayed17/headgate/compare/v0.
|
|
251
|
+
[Unreleased]: https://github.com/kelsayed17/headgate/compare/v0.5.0...HEAD
|
|
252
|
+
[0.5.0]: https://github.com/kelsayed17/headgate/compare/v0.4.0...v0.5.0
|
|
253
|
+
[0.4.0]: https://github.com/kelsayed17/headgate/compare/v0.3.0...v0.4.0
|
|
219
254
|
[0.3.0]: https://github.com/kelsayed17/headgate/compare/159a3c2...v0.3.0
|
|
220
255
|
[0.2.0]: https://github.com/kelsayed17/headgate/compare/f319ad8...159a3c2
|
|
221
256
|
[0.1.0]: https://github.com/kelsayed17/headgate/commit/f319ad8
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: headgate
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: The async API-client base on httpx2: safe retries, rate budgets, per-origin breakers, credential-safe caching, typed events and declared responses.
|
|
5
5
|
Project-URL: Homepage, https://github.com/kelsayed17/headgate
|
|
6
|
-
Project-URL: Documentation, https://github.
|
|
6
|
+
Project-URL: Documentation, https://kelsayed17.github.io/headgate/
|
|
7
7
|
Project-URL: Repository, https://github.com/kelsayed17/headgate
|
|
8
8
|
Project-URL: Issues, https://github.com/kelsayed17/headgate/issues
|
|
9
9
|
Project-URL: Changelog, https://github.com/kelsayed17/headgate/blob/main/CHANGELOG.md
|
|
@@ -43,6 +43,13 @@ Description-Content-Type: text/markdown
|
|
|
43
43
|
|
|
44
44
|
# headgate
|
|
45
45
|
|
|
46
|
+
[](https://pypi.org/project/headgate/)
|
|
47
|
+
[](https://pypi.org/project/headgate/)
|
|
48
|
+
[](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml)
|
|
49
|
+
[](CONTRIBUTING.md)
|
|
50
|
+
[](https://kelsayed17.github.io/headgate/)
|
|
51
|
+
[](LICENSE)
|
|
52
|
+
|
|
46
53
|
**An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass
|
|
47
54
|
`AsyncBaseClient`, declare what each endpoint answers, and every client you build gets the same production behaviour:
|
|
48
55
|
retries that re-send only when it is safe, a shared rate budget that listens to the server, a per-origin circuit
|
|
@@ -52,10 +59,23 @@ events and OpenTelemetry, and errors that say exactly what happened. Each endpoi
|
|
|
52
59
|
A headgate controls how much water gets through a channel. This library does the same for requests, in one place,
|
|
53
60
|
so that no client has to get it right on its own.
|
|
54
61
|
|
|
62
|
+
One base class replaces the stack a production client usually grows: an HTTP library, a retry library, a rate limiter,
|
|
63
|
+
a cache, a circuit breaker, an event-stream parser and a mocking library, plus the glue that makes them agree.
|
|
64
|
+
|
|
65
|
+
**Docs:** <https://kelsayed17.github.io/headgate/>. New here? See [how headgate compares](docs/comparison.md) with
|
|
66
|
+
the libraries it replaces, [the standards it follows](docs/standards.md), and a
|
|
67
|
+
[GitHub API client](examples/github_client.py) written with it.
|
|
68
|
+
|
|
55
69
|
## Requirements and install
|
|
56
70
|
|
|
57
|
-
Python 3.14 or newer
|
|
58
|
-
|
|
71
|
+
Python 3.14 or newer, and `httpx2`, pydantic's fork of httpx.
|
|
72
|
+
|
|
73
|
+
- **Why 3.14:** endpoint paths are [template strings](https://peps.python.org/pep-0750/) (`t"orders/{order_id}"`), so
|
|
74
|
+
each value is escaped into its own path segment by default: `BTC/USD` becomes `BTC%2FUSD` instead of a new path.
|
|
75
|
+
Template strings exist only from Python 3.14.
|
|
76
|
+
- **Why httpx2:** headgate is built and tested on it alone. Its API is httpx's, so moving a client over is mostly
|
|
77
|
+
`import httpx2` where you had `import httpx`. Upstream `httpx` is not supported: passing one of its objects raises a
|
|
78
|
+
`TypeError` naming the mistake. See [why httpx2](docs/comparison.md#why-httpx2).
|
|
59
79
|
|
|
60
80
|
```bash
|
|
61
81
|
pip install headgate # or: uv add headgate. Brings httpx2[http2], hishel and msgspec
|
|
@@ -185,7 +205,7 @@ idempotent POST, a declared business refusal, `Link`-header pages and a streamed
|
|
|
185
205
|
| Response cap | 32 MiB per buffered body, counted after decompression | [configuration](docs/configuration.md#httpoptions) |
|
|
186
206
|
| Caching | Opt-in hishel cache, partitioned by credential, never storing one; coalesced identical GETs; conditional reads | [caching](docs/caching.md) |
|
|
187
207
|
| Streaming and uploads | `stream()` for bodies and server-sent events with resume; raw, streamed and multipart request bodies | [streaming](docs/streaming.md) |
|
|
188
|
-
| Pagination | `paginate()` with `Cursor`, `Offset`, `LinkHeader` or `NextUrl`, lazy, loop-safe | [pagination](docs/pagination.md) |
|
|
208
|
+
| Pagination | `paginate()` with `Cursor`, `Offset`, `LinkHeader` or `NextUrl`, lazy, loop-safe, bounded by pages or items | [pagination](docs/pagination.md) |
|
|
189
209
|
| Errors | One `ClientError` tree; method, URL, request id, attempts, `retryable`, `retry_after`, RFC 9457 problems | [errors](docs/errors.md) |
|
|
190
210
|
| Auth | Static headers, query keys, and a cached minted token with one re-mint on a 401 | [auth](docs/auth.md) |
|
|
191
211
|
| Observability | Typed events, OpenTelemetry spans and metrics, request ids, `Deprecation` / `Sunset` notices, health snapshots | [observability](docs/observability.md) |
|
|
@@ -364,6 +384,7 @@ uv run ty check
|
|
|
364
384
|
uv run python -m pytest --cov # 100% line and branch coverage is required
|
|
365
385
|
uv run python -m pytest benchmarks # the benchmarks, as CI runs them
|
|
366
386
|
uv run mutmut run # mutation testing; slow, run it before a release
|
|
387
|
+
uv run --only-group docs zensical serve # preview the docs site at http://localhost:8000
|
|
367
388
|
```
|
|
368
389
|
|
|
369
390
|
Lint selects every ruff rule, ty treats every rule as an error, and suppression comments are not accepted. See
|
|
@@ -4,6 +4,13 @@
|
|
|
4
4
|
|
|
5
5
|
# headgate
|
|
6
6
|
|
|
7
|
+
[](https://pypi.org/project/headgate/)
|
|
8
|
+
[](https://pypi.org/project/headgate/)
|
|
9
|
+
[](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml)
|
|
10
|
+
[](CONTRIBUTING.md)
|
|
11
|
+
[](https://kelsayed17.github.io/headgate/)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
|
|
7
14
|
**An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass
|
|
8
15
|
`AsyncBaseClient`, declare what each endpoint answers, and every client you build gets the same production behaviour:
|
|
9
16
|
retries that re-send only when it is safe, a shared rate budget that listens to the server, a per-origin circuit
|
|
@@ -13,10 +20,23 @@ events and OpenTelemetry, and errors that say exactly what happened. Each endpoi
|
|
|
13
20
|
A headgate controls how much water gets through a channel. This library does the same for requests, in one place,
|
|
14
21
|
so that no client has to get it right on its own.
|
|
15
22
|
|
|
23
|
+
One base class replaces the stack a production client usually grows: an HTTP library, a retry library, a rate limiter,
|
|
24
|
+
a cache, a circuit breaker, an event-stream parser and a mocking library, plus the glue that makes them agree.
|
|
25
|
+
|
|
26
|
+
**Docs:** <https://kelsayed17.github.io/headgate/>. New here? See [how headgate compares](docs/comparison.md) with
|
|
27
|
+
the libraries it replaces, [the standards it follows](docs/standards.md), and a
|
|
28
|
+
[GitHub API client](examples/github_client.py) written with it.
|
|
29
|
+
|
|
16
30
|
## Requirements and install
|
|
17
31
|
|
|
18
|
-
Python 3.14 or newer
|
|
19
|
-
|
|
32
|
+
Python 3.14 or newer, and `httpx2`, pydantic's fork of httpx.
|
|
33
|
+
|
|
34
|
+
- **Why 3.14:** endpoint paths are [template strings](https://peps.python.org/pep-0750/) (`t"orders/{order_id}"`), so
|
|
35
|
+
each value is escaped into its own path segment by default: `BTC/USD` becomes `BTC%2FUSD` instead of a new path.
|
|
36
|
+
Template strings exist only from Python 3.14.
|
|
37
|
+
- **Why httpx2:** headgate is built and tested on it alone. Its API is httpx's, so moving a client over is mostly
|
|
38
|
+
`import httpx2` where you had `import httpx`. Upstream `httpx` is not supported: passing one of its objects raises a
|
|
39
|
+
`TypeError` naming the mistake. See [why httpx2](docs/comparison.md#why-httpx2).
|
|
20
40
|
|
|
21
41
|
```bash
|
|
22
42
|
pip install headgate # or: uv add headgate. Brings httpx2[http2], hishel and msgspec
|
|
@@ -146,7 +166,7 @@ idempotent POST, a declared business refusal, `Link`-header pages and a streamed
|
|
|
146
166
|
| Response cap | 32 MiB per buffered body, counted after decompression | [configuration](docs/configuration.md#httpoptions) |
|
|
147
167
|
| Caching | Opt-in hishel cache, partitioned by credential, never storing one; coalesced identical GETs; conditional reads | [caching](docs/caching.md) |
|
|
148
168
|
| Streaming and uploads | `stream()` for bodies and server-sent events with resume; raw, streamed and multipart request bodies | [streaming](docs/streaming.md) |
|
|
149
|
-
| Pagination | `paginate()` with `Cursor`, `Offset`, `LinkHeader` or `NextUrl`, lazy, loop-safe | [pagination](docs/pagination.md) |
|
|
169
|
+
| Pagination | `paginate()` with `Cursor`, `Offset`, `LinkHeader` or `NextUrl`, lazy, loop-safe, bounded by pages or items | [pagination](docs/pagination.md) |
|
|
150
170
|
| Errors | One `ClientError` tree; method, URL, request id, attempts, `retryable`, `retry_after`, RFC 9457 problems | [errors](docs/errors.md) |
|
|
151
171
|
| Auth | Static headers, query keys, and a cached minted token with one re-mint on a 401 | [auth](docs/auth.md) |
|
|
152
172
|
| Observability | Typed events, OpenTelemetry spans and metrics, request ids, `Deprecation` / `Sunset` notices, health snapshots | [observability](docs/observability.md) |
|
|
@@ -325,6 +345,7 @@ uv run ty check
|
|
|
325
345
|
uv run python -m pytest --cov # 100% line and branch coverage is required
|
|
326
346
|
uv run python -m pytest benchmarks # the benchmarks, as CI runs them
|
|
327
347
|
uv run mutmut run # mutation testing; slow, run it before a release
|
|
348
|
+
uv run --only-group docs zensical serve # preview the docs site at http://localhost:8000
|
|
328
349
|
```
|
|
329
350
|
|
|
330
351
|
Lint selects every ruff rule, ty treats every rule as an error, and suppression comments are not accepted. See
|
|
@@ -65,7 +65,7 @@ class PartnerAuth(CachedTokenAuth):
|
|
|
65
65
|
|
|
66
66
|
Or `_mint_flow(request)` yields the requests the exchange needs, so they travel through the owning client's own stack
|
|
67
67
|
(its transport, rate budget, retries and error mapping), and ends by yielding `Minted(token, lifetime)`.
|
|
68
|
-
[`examples/orders_client.py`](
|
|
68
|
+
[`examples/orders_client.py`](https://github.com/kelsayed17/headgate/blob/main/examples/orders_client.py) has a complete one. What the flow can count on:
|
|
69
69
|
|
|
70
70
|
- **Each response arrives read**, so `.content`, `.text` and `.json()` work on it. It is read up to 1 MiB
|
|
71
71
|
(`headgate.MAX_MINT_RESPONSE_BYTES`, decompressed); a larger one fails the mint with `ResponseTooLargeError`.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Compared with others
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Compared with others
|
|
6
|
+
|
|
7
|
+
headgate is a Swiss Army knife for HTTP API clients. Most libraries do one job well: send requests, retry, rate-limit,
|
|
8
|
+
cache, break circuits, mock. headgate does all of those jobs in one base class, and makes them agree with each other.
|
|
9
|
+
This page shows what that buys you, library by library, and when another tool is the better pick.
|
|
10
|
+
|
|
11
|
+
<div class="hg-legend" markdown>
|
|
12
|
+
<span>:lucide-circle-check:{ .hg-yes } built in</span>
|
|
13
|
+
<span>:lucide-puzzle:{ .hg-addon } with another library, or code you write</span>
|
|
14
|
+
<span>:lucide-minus:{ .hg-no } not available</span>
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
## HTTP clients
|
|
18
|
+
|
|
19
|
+
requests, niquests, httpx and aiohttp send HTTP requests, and do it well. headgate runs on httpx2 (pydantic's fork of httpx) and
|
|
20
|
+
adds everything a client for someone else's API needs on top. It can also send through
|
|
21
|
+
[curl_cffi](configuration.md#the-curl-transport) when you need libcurl.
|
|
22
|
+
|
|
23
|
+
<div class="hg-matrix hg-compare" markdown>
|
|
24
|
+
|
|
25
|
+
| | requests | niquests | httpx | aiohttp | headgate |
|
|
26
|
+
| --- | --- | --- | --- | --- | --- |
|
|
27
|
+
| Async | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
28
|
+
| HTTP/2 | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
29
|
+
| Retries with backoff | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
30
|
+
| Waits for `Retry-After` | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
31
|
+
| One deadline over every retry | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
32
|
+
| Rate limiting that obeys the server | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
33
|
+
| Circuit breaker | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
34
|
+
| Caching | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
35
|
+
| Pagination | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
36
|
+
| Server-sent events | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
37
|
+
| RFC 9457 problem details parsed | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
38
|
+
| Every credential kept off other hosts | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
39
|
+
| SSRF guard with DNS pinning | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
40
|
+
| Response size cap | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
41
|
+
| Ignores proxy variables and `.netrc` by default | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
42
|
+
| Secrets redacted from error messages | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
43
|
+
| Test fakes | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
44
|
+
| Sync API | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } |
|
|
45
|
+
|
|
46
|
+
</div>
|
|
47
|
+
|
|
48
|
+
When a redirect leaves the origin, requests and httpx drop the `Authorization` header, and aiohttp drops `Cookie` and
|
|
49
|
+
`Proxy-Authorization` too. headgate drops those and every other header and query parameter its auth declares, such as
|
|
50
|
+
an `X-API-Key`, on every hop, next-page links included: see [security](security.md).
|
|
51
|
+
|
|
52
|
+
## The stack headgate replaces
|
|
53
|
+
|
|
54
|
+
| Job | What people usually add | In headgate |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| :lucide-rotate-cw: Retries | tenacity, stamina, backoff, httpx-retries, aiohttp-retry | [`RetryPolicy`](retries.md) |
|
|
57
|
+
| :lucide-gauge: Rate limits | aiolimiter, pyrate-limiter, limits | [`RateBudget`](rate-budgets.md) |
|
|
58
|
+
| :lucide-database-zap: Caching | hishel, requests-cache, aiohttp-client-cache, CacheControl | [`HttpCache`](caching.md), on hishel |
|
|
59
|
+
| :lucide-zap-off: Circuit breaking | pybreaker, aiobreaker, purgatory, circuitbreaker | [`BreakerPolicy`](breaker.md) |
|
|
60
|
+
| :lucide-radio: Server-sent events | httpx-sse, aiohttp-sse-client | [`stream().aiter_events()`](streaming.md#server-sent-events) |
|
|
61
|
+
| :lucide-list-ordered: Pagination | a loop you write per endpoint | [`paginate()`](pagination.md) |
|
|
62
|
+
| :lucide-flask-conical: Test doubles | respx, pytest-httpx, aioresponses, responses | [`headgate.testing`](testing.md); vcrpy cassettes work too |
|
|
63
|
+
| :lucide-activity: Telemetry | OpenTelemetry instrumentation packages | [typed events and an OpenTelemetry observer](observability.md) |
|
|
64
|
+
|
|
65
|
+
Fewer dependencies is the small win. The big one is that the layers know about each other, which separate libraries
|
|
66
|
+
cannot:
|
|
67
|
+
|
|
68
|
+
- **A cache hit is never retried, and spends no rate turn**, because the cache sits below the retry layer and above
|
|
69
|
+
the rate budget.
|
|
70
|
+
- **The retry layer and the rate budget read `Retry-After` the same way**, so the retry's wait and the budget's pause
|
|
71
|
+
end together instead of stacking.
|
|
72
|
+
- **One deadline bounds everything**: every attempt, every backoff, every rate-budget wait and the body read.
|
|
73
|
+
- **A breaker counts only the host's own failures**: a 404 your code asked for, or a call you cancelled, does not open
|
|
74
|
+
it.
|
|
75
|
+
|
|
76
|
+
## Library by library
|
|
77
|
+
|
|
78
|
+
=== "Retries"
|
|
79
|
+
|
|
80
|
+
<div class="hg-matrix hg-compare" markdown>
|
|
81
|
+
|
|
82
|
+
| | tenacity | stamina | backoff | urllib3 `Retry` | headgate |
|
|
83
|
+
| --- | --- | --- | --- | --- | --- |
|
|
84
|
+
| Retries any code, not just HTTP | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } |
|
|
85
|
+
| Async | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
86
|
+
| Knows which HTTP requests are safe to re-send | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
87
|
+
| Waits for `Retry-After` | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
88
|
+
| Total time limit | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
89
|
+
| Retry budget shared across calls | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
90
|
+
| Idempotency keys for safe POST retries | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
91
|
+
| Hedged requests | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
92
|
+
| Instant retries in tests | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
93
|
+
|
|
94
|
+
</div>
|
|
95
|
+
|
|
96
|
+
**Pick stamina or tenacity** to retry something that is not an HTTP call, such as a database query. stamina's
|
|
97
|
+
`on=` hook (25.2 and later) and tenacity's `wait_exception` can honour `Retry-After` with a little code. backoff's
|
|
98
|
+
repository is archived, and it has not been released since 2022.
|
|
99
|
+
|
|
100
|
+
=== "Rate limits"
|
|
101
|
+
|
|
102
|
+
<div class="hg-matrix hg-compare" markdown>
|
|
103
|
+
|
|
104
|
+
| | aiolimiter | pyrate-limiter | headgate |
|
|
105
|
+
| --- | --- | --- | --- |
|
|
106
|
+
| Async | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
107
|
+
| Several rates at once | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
108
|
+
| Shared across processes (Redis, SQLite) | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } |
|
|
109
|
+
| Pauses when the server says 429 or 503 | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
110
|
+
| Reads `RateLimit` and `X-RateLimit-*` headers | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
111
|
+
| Slows down on pushback (adaptive) | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
112
|
+
| Separate lanes per path | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
113
|
+
| Cap on requests in flight | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
114
|
+
|
|
115
|
+
</div>
|
|
116
|
+
|
|
117
|
+
**Pick pyrate-limiter** when many processes or machines must share one quota.
|
|
118
|
+
|
|
119
|
+
=== "Caching"
|
|
120
|
+
|
|
121
|
+
<div class="hg-matrix hg-compare" markdown>
|
|
122
|
+
|
|
123
|
+
| | hishel | requests-cache | aiohttp-client-cache | headgate |
|
|
124
|
+
| --- | --- | --- | --- | --- |
|
|
125
|
+
| Async | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
126
|
+
| Follows `Cache-Control` (RFC 9111) | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } |
|
|
127
|
+
| Your own rules for APIs that send no cache headers | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
128
|
+
| Entries kept apart per credential | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
129
|
+
| Stores only answers your code accepted | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
130
|
+
|
|
131
|
+
</div>
|
|
132
|
+
|
|
133
|
+
headgate's cache **is** hishel, configured with your rules and wrapped so it is safe to share between
|
|
134
|
+
credentials. **Pick hishel directly** when you want the provider's `Cache-Control` to decide; it supports httpx2
|
|
135
|
+
too.
|
|
136
|
+
|
|
137
|
+
=== "Circuit breakers"
|
|
138
|
+
|
|
139
|
+
<div class="hg-matrix hg-compare" markdown>
|
|
140
|
+
|
|
141
|
+
| | pybreaker | aiobreaker | purgatory | headgate |
|
|
142
|
+
| --- | --- | --- | --- | --- |
|
|
143
|
+
| Async | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
144
|
+
| One breaker per host, automatically | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
145
|
+
| Counts only the host's own failures | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
146
|
+
| Retries stop while it is open | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-puzzle:{ .hg-addon } | :lucide-circle-check:{ .hg-yes } |
|
|
147
|
+
| State shared across processes (Redis) | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } |
|
|
148
|
+
|
|
149
|
+
</div>
|
|
150
|
+
|
|
151
|
+
**Pick pybreaker or purgatory** to guard something that is not HTTP, or to share breaker state across machines.
|
|
152
|
+
|
|
153
|
+
=== "Testing"
|
|
154
|
+
|
|
155
|
+
<div class="hg-matrix hg-compare" markdown>
|
|
156
|
+
|
|
157
|
+
| | respx | pytest-httpx | aioresponses | vcrpy | headgate.testing |
|
|
158
|
+
| --- | --- | --- | --- | --- | --- |
|
|
159
|
+
| Canned responses | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } |
|
|
160
|
+
| Record and replay real traffic | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } | :lucide-puzzle:{ .hg-addon } |
|
|
161
|
+
| Failure schedules (fail twice, then succeed) | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-circle-check:{ .hg-yes } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
162
|
+
| A fake clock, so retries and rate waits are instant | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
163
|
+
| Breaker state isolated per test | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-minus:{ .hg-no } | :lucide-circle-check:{ .hg-yes } |
|
|
164
|
+
|
|
165
|
+
</div>
|
|
166
|
+
|
|
167
|
+
respx and pytest-httpx patch httpx, not httpx2, so they do not see a headgate client's requests.
|
|
168
|
+
`headgate.testing` is built for it, and vcrpy 8.3 and later record httpx2; headgate ships
|
|
169
|
+
[filters](testing.md) that keep credentials out of the cassettes.
|
|
170
|
+
|
|
171
|
+
=== "Client frameworks"
|
|
172
|
+
|
|
173
|
+
| | What it is | How headgate differs |
|
|
174
|
+
| --- | --- | --- |
|
|
175
|
+
| **uplink** | declare endpoints with decorators on an interface | headgate endpoints are ordinary methods, and resilience is built in rather than added per decorator |
|
|
176
|
+
| **openapi-python-client** | generates a typed client from an OpenAPI document | use it when you have a spec; headgate is for APIs without one, or where you want control |
|
|
177
|
+
| **Stainless SDKs** (openai, anthropic) | generated SDKs with retries and timeouts built in | headgate brings that quality to a client you write yourself, and understands the same `retry-after-ms` and `x-should-retry` headers |
|
|
178
|
+
|
|
179
|
+
## When to use something else
|
|
180
|
+
|
|
181
|
+
- **Retrying code that is not an HTTP call** (a database query, a file operation): use stamina, or tenacity when you
|
|
182
|
+
need its full flexibility.
|
|
183
|
+
- **Python before 3.14**: headgate needs 3.14 for its template-string paths. Use httpx with stamina, and add rate
|
|
184
|
+
limiting and caching yourself.
|
|
185
|
+
- **Upstream httpx**: headgate runs on httpx2 and refuses httpx objects, to catch the mix-up early. If your code has to
|
|
186
|
+
stay on httpx, headgate is not for you yet.
|
|
187
|
+
- **A synchronous codebase**: headgate is async only. requests or httpx's sync client is the simpler choice.
|
|
188
|
+
- **One or two calls in a script**: a plain httpx2 call is fine. headgate pays off when a client has several endpoints,
|
|
189
|
+
several consumers, or has to survive a provider's bad day.
|
|
190
|
+
- **A quota shared across machines**: headgate's rate budget and breakers live in one process. Use pyrate-limiter or
|
|
191
|
+
purgatory with Redis for that.
|
|
192
|
+
|
|
193
|
+
## Why httpx2
|
|
194
|
+
|
|
195
|
+
headgate is built and tested on [httpx2](https://pypi.org/project/httpx2/), pydantic's fork of httpx, and on nothing
|
|
196
|
+
else. Its API is httpx's, so moving a client over is mostly an import change: `import httpx2` where you had
|
|
197
|
+
`import httpx`, and the same for the exceptions you catch. headgate refuses an `httpx` object anywhere it takes an httpx2
|
|
198
|
+
one, with a `TypeError` naming the mistake, rather than failing later in a confusing way.
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: An async API-client base for Python
|
|
3
|
+
hide:
|
|
4
|
+
- toc
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<div class="hg-hero" markdown>
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
<div markdown>
|
|
12
|
+
|
|
13
|
+
# headgate
|
|
14
|
+
|
|
15
|
+
**An async API-client base for Python, built on [httpx2](https://pypi.org/project/httpx2/).** Subclass
|
|
16
|
+
`AsyncBaseClient`, declare what each endpoint answers, and every client you build gets the same production behaviour.
|
|
17
|
+
Each endpoint method stays one line.
|
|
18
|
+
|
|
19
|
+
[Get started](#install){ .md-button .md-button--primary }
|
|
20
|
+
[How it compares](comparison.md){ .md-button }
|
|
21
|
+
[:fontawesome-brands-github: GitHub](https://github.com/kelsayed17/headgate){ .md-button }
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
</div>
|
|
26
|
+
|
|
27
|
+
<div class="grid cards" markdown>
|
|
28
|
+
|
|
29
|
+
- :lucide-rotate-cw:{ .lg .hg-icon } **Retries that are safe**
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
Idempotent methods only, or a POST under an idempotency key. `Retry-After` is waited exactly, and a budget stops
|
|
34
|
+
retries multiplying an outage.
|
|
35
|
+
|
|
36
|
+
[:lucide-arrow-right: Retries](retries.md)
|
|
37
|
+
|
|
38
|
+
- :lucide-gauge:{ .lg .hg-icon } **A rate budget that listens**
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
One budget shared by every call, paused by `RateLimit` and `X-RateLimit-*` headers and slowed by pushback.
|
|
43
|
+
|
|
44
|
+
[:lucide-arrow-right: Rate budgets](rate-budgets.md)
|
|
45
|
+
|
|
46
|
+
- :lucide-timer:{ .lg .hg-icon } **Deadlines and a breaker**
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
One deadline bounds every attempt, wait and read. A per-origin circuit breaker stops calls to a host that is down.
|
|
51
|
+
|
|
52
|
+
[:lucide-arrow-right: Deadlines](deadlines.md) · [Circuit breaker](breaker.md)
|
|
53
|
+
|
|
54
|
+
- :lucide-key-round:{ .lg .hg-icon } **Credentials that stay home**
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
Credentials are pinned to their origin, an https-to-http redirect is refused, and an SSRF guard is one option away.
|
|
59
|
+
|
|
60
|
+
[:lucide-arrow-right: Security](security.md)
|
|
61
|
+
|
|
62
|
+
- :lucide-database-zap:{ .lg .hg-icon } **A cache that keeps no secrets**
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
hishel's cache, partitioned by credential, never storing one, and storing only what your reader accepted.
|
|
67
|
+
|
|
68
|
+
[:lucide-arrow-right: Caching](caching.md)
|
|
69
|
+
|
|
70
|
+
- :lucide-activity:{ .lg .hg-icon } **Errors and events that explain**
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
Typed errors that say what happened and whether to retry, typed events, and an OpenTelemetry observer.
|
|
75
|
+
|
|
76
|
+
[:lucide-arrow-right: Errors](errors.md) · [Observability](observability.md)
|
|
77
|
+
|
|
78
|
+
</div>
|
|
79
|
+
|
|
80
|
+
## One base class instead of a stack
|
|
81
|
+
|
|
82
|
+
A production API client usually grows a stack: an HTTP library, a retry library, a rate limiter, a cache, a circuit
|
|
83
|
+
breaker, a mocking library, and the glue code that makes them agree on deadlines and credentials. headgate is that
|
|
84
|
+
whole stack, built to work as one.
|
|
85
|
+
|
|
86
|
+
<div class="hg-stack">
|
|
87
|
+
<div class="hg-stack-before">
|
|
88
|
+
<span class="hg-stack-label">The usual stack</span>
|
|
89
|
+
<span class="hg-chip">httpx or aiohttp</span>
|
|
90
|
+
<span class="hg-chip">tenacity or stamina</span>
|
|
91
|
+
<span class="hg-chip">aiolimiter</span>
|
|
92
|
+
<span class="hg-chip">hishel or requests-cache</span>
|
|
93
|
+
<span class="hg-chip">pybreaker</span>
|
|
94
|
+
<span class="hg-chip">httpx-sse</span>
|
|
95
|
+
<span class="hg-chip">respx</span>
|
|
96
|
+
<span class="hg-chip hg-chip-glue">your glue code</span>
|
|
97
|
+
</div>
|
|
98
|
+
<div class="hg-stack-arrow" aria-hidden="true">→</div>
|
|
99
|
+
<div class="hg-stack-after">
|
|
100
|
+
<img src="assets/logo.png" alt="">
|
|
101
|
+
<strong>headgate</strong>
|
|
102
|
+
<span>one dependency, every layer built to work with the others</span>
|
|
103
|
+
</div>
|
|
104
|
+
</div>
|
|
105
|
+
|
|
106
|
+
Each call your client makes passes through every layer, in an order chosen so they cooperate: a cache hit is never
|
|
107
|
+
retried, a retry spends its own rate turn, and one deadline bounds the lot.
|
|
108
|
+
|
|
109
|
+
<ol class="hg-pipeline">
|
|
110
|
+
<li><strong>Deadline</strong><span>one budget of time for the whole call</span></li>
|
|
111
|
+
<li><strong>Circuit breaker</strong><span>fails fast while the host is down</span></li>
|
|
112
|
+
<li><strong>Auth</strong><span>credentials only for your origin</span></li>
|
|
113
|
+
<li><strong>Retries</strong><span>safe re-sends, <code>Retry-After</code> obeyed</span></li>
|
|
114
|
+
<li><strong>Cache</strong><span>a hit stops here</span></li>
|
|
115
|
+
<li><strong>Rate budget</strong><span>paced, and paused when the server asks</span></li>
|
|
116
|
+
<li><strong>Network</strong><span>HTTP/2, size-capped body</span></li>
|
|
117
|
+
<li><strong>Your reader</strong><span>a typed result, or a typed error</span></li>
|
|
118
|
+
</ol>
|
|
119
|
+
|
|
120
|
+
[:lucide-arrow-right: How headgate compares with 20+ libraries](comparison.md){ .md-button }
|
|
121
|
+
[:lucide-arrow-right: The standards it follows](standards.md){ .md-button }
|
|
122
|
+
|
|
123
|
+
## Install
|
|
124
|
+
|
|
125
|
+
=== "pip"
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pip install headgate
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
=== "uv"
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
uv add headgate
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
headgate needs **Python 3.14** or newer: endpoint paths are [template strings](https://peps.python.org/pep-0750/), so
|
|
138
|
+
each value is escaped into its own path segment by default. It runs on **httpx2**, pydantic's fork of httpx; see
|
|
139
|
+
[why httpx2](comparison.md#why-httpx2).
|
|
140
|
+
|
|
141
|
+
## A real client
|
|
142
|
+
|
|
143
|
+
A client for a few GitHub REST endpoints. The full version, with its tests, is
|
|
144
|
+
[`examples/github_client.py`](https://github.com/kelsayed17/headgate/blob/main/examples/github_client.py).
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
from http import HTTPStatus
|
|
148
|
+
|
|
149
|
+
import msgspec
|
|
150
|
+
|
|
151
|
+
from headgate import AsyncBaseClient, Expect, HttpOptions, LinkHeader, Rate, RateBudget, StaticHeaderAuth, nothing
|
|
152
|
+
from headgate.msgspec import decoder
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
class Repository(msgspec.Struct, frozen=True):
|
|
156
|
+
full_name: str
|
|
157
|
+
stargazers_count: int
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class Issue(msgspec.Struct, frozen=True):
|
|
161
|
+
number: int
|
|
162
|
+
title: str
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
REPOSITORY_OR_NONE = Expect(decoder(Repository)).on(HTTPStatus.NOT_FOUND, nothing)
|
|
166
|
+
ISSUE_PAGES = LinkHeader(items=lambda page: page) # each page is a JSON list of issues
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
class GitHub(AsyncBaseClient):
|
|
170
|
+
def __init__(self, token: str) -> None:
|
|
171
|
+
super().__init__(
|
|
172
|
+
base_url="https://api.github.com",
|
|
173
|
+
rate=RateBudget(Rate.per_second(10), max_in_flight=50),
|
|
174
|
+
auth=StaticHeaderAuth({"Authorization": f"Bearer {token}"}),
|
|
175
|
+
http=HttpOptions(headers={"Accept": "application/vnd.github+json"}),
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
async def repository(self, owner: str, name: str) -> Repository | None:
|
|
179
|
+
return await self.get(t"repos/{owner}/{name}", expect=REPOSITORY_OR_NONE)
|
|
180
|
+
|
|
181
|
+
def open_issues(self, owner: str, name: str):
|
|
182
|
+
return self.paginate(t"repos/{owner}/{name}/issues", expect=decoder(list[Issue]), pages=ISSUE_PAGES)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
async with GitHub(token) as github:
|
|
187
|
+
repository = await github.repository("python", "cpython")
|
|
188
|
+
async for issue in github.open_issues("python", "cpython"):
|
|
189
|
+
print(issue.number, issue.title)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Retries, pacing under GitHub's limits, pausing when its hourly limit is spent, following `Link` headers, and keeping
|
|
193
|
+
the token on `api.github.com` all come from the base class.
|
|
194
|
+
|
|
195
|
+
## Where to next
|
|
196
|
+
|
|
197
|
+
- [Compared with others](comparison.md): what headgate does that tenacity, stamina or a hand-rolled httpx client
|
|
198
|
+
does not, and when to pick those instead.
|
|
199
|
+
- [Configuration](configuration.md): every option, and where it lives.
|
|
200
|
+
- [Declared responses](responses.md) and [errors](errors.md): what an endpoint answers, and what it raises.
|
|
201
|
+
- [Testing a client](testing.md): fake networks, instant retries and failure schedules, with nothing private patched.
|