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.
Files changed (262) hide show
  1. {headgate-0.3.0 → headgate-0.5.0}/.gitignore +3 -0
  2. {headgate-0.3.0 → headgate-0.5.0}/CHANGELOG.md +36 -1
  3. {headgate-0.3.0 → headgate-0.5.0}/PKG-INFO +26 -5
  4. {headgate-0.3.0 → headgate-0.5.0}/README.md +24 -3
  5. {headgate-0.3.0 → headgate-0.5.0}/docs/auth.md +1 -1
  6. headgate-0.5.0/docs/comparison.md +198 -0
  7. headgate-0.5.0/docs/index.md +201 -0
  8. {headgate-0.3.0 → headgate-0.5.0}/docs/pagination.md +46 -3
  9. {headgate-0.3.0 → headgate-0.5.0}/docs/security.md +23 -0
  10. headgate-0.5.0/docs/standards.md +107 -0
  11. headgate-0.5.0/docs/stylesheets/extra.css +246 -0
  12. {headgate-0.3.0 → headgate-0.5.0}/docs/testing.md +1 -1
  13. headgate-0.5.0/examples/github_client.py +86 -0
  14. {headgate-0.3.0 → headgate-0.5.0}/pyproject.toml +3 -2
  15. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/__init__.py +4 -1
  16. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_client.py +7 -2
  17. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/errors.py +15 -0
  18. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pagination/__init__.py +2 -1
  19. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pagination/_pager.py +23 -7
  20. headgate-0.5.0/src/headgate/pagination/_paginated.py +149 -0
  21. headgate-0.5.0/tests/examples/test_github_client.py +76 -0
  22. {headgate-0.3.0 → headgate-0.5.0}/tests/package/__snapshots__/test_api_surface.ambr +28 -12
  23. {headgate-0.3.0 → headgate-0.5.0}/tests/pagination/test_paginate.py +214 -1
  24. headgate-0.3.0/src/headgate/pagination/_paginated.py +0 -82
  25. {headgate-0.3.0 → headgate-0.5.0}/LICENSE +0 -0
  26. {headgate-0.3.0 → headgate-0.5.0}/docs/breaker.md +0 -0
  27. {headgate-0.3.0 → headgate-0.5.0}/docs/caching.md +0 -0
  28. {headgate-0.3.0 → headgate-0.5.0}/docs/configuration.md +0 -0
  29. {headgate-0.3.0 → headgate-0.5.0}/docs/deadlines.md +0 -0
  30. {headgate-0.3.0 → headgate-0.5.0}/docs/design.md +0 -0
  31. {headgate-0.3.0 → headgate-0.5.0}/docs/errors.md +0 -0
  32. {headgate-0.3.0 → headgate-0.5.0}/docs/mutation-testing.md +0 -0
  33. {headgate-0.3.0 → headgate-0.5.0}/docs/observability.md +0 -0
  34. {headgate-0.3.0 → headgate-0.5.0}/docs/rate-budgets.md +0 -0
  35. {headgate-0.3.0 → headgate-0.5.0}/docs/responses.md +0 -0
  36. {headgate-0.3.0 → headgate-0.5.0}/docs/retries.md +0 -0
  37. {headgate-0.3.0 → headgate-0.5.0}/docs/streaming.md +0 -0
  38. {headgate-0.3.0 → headgate-0.5.0}/examples/__init__.py +0 -0
  39. {headgate-0.3.0 → headgate-0.5.0}/examples/boundary.py +0 -0
  40. {headgate-0.3.0 → headgate-0.5.0}/examples/orders_client.py +0 -0
  41. {headgate-0.3.0 → headgate-0.5.0}/examples/quickstart.py +0 -0
  42. {headgate-0.3.0 → headgate-0.5.0}/examples/series_client.py +0 -0
  43. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_attempts.py +0 -0
  44. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_auth.py +0 -0
  45. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_body.py +0 -0
  46. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_codec.py +0 -0
  47. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/__init__.py +0 -0
  48. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_context.py +0 -0
  49. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_events.py +0 -0
  50. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_origin.py +0 -0
  51. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_retry_after.py +0 -0
  52. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_seams.py +0 -0
  53. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_switch.py +0 -0
  54. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_core/_time.py +0 -0
  55. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_curl.py +0 -0
  56. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_deprecation.py +0 -0
  57. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_failures.py +0 -0
  58. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_middleware.py +0 -0
  59. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_options.py +0 -0
  60. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_redirects.py +0 -0
  61. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_request_body.py +0 -0
  62. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_responses.py +0 -0
  63. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_stack.py +0 -0
  64. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_url.py +0 -0
  65. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_user_agent.py +0 -0
  66. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/_view.py +0 -0
  67. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/__init__.py +0 -0
  68. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_breaker.py +0 -0
  69. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_policy.py +0 -0
  70. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_registry.py +0 -0
  71. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/breaker/_scope.py +0 -0
  72. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/__init__.py +0 -0
  73. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_conditional.py +0 -0
  74. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_credentials.py +0 -0
  75. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_policy.py +0 -0
  76. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/cache/_transport.py +0 -0
  77. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/curl.py +0 -0
  78. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/events.py +0 -0
  79. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/health.py +0 -0
  80. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/msgspec.py +0 -0
  81. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/otel.py +0 -0
  82. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pagination/_link.py +0 -0
  83. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/policy.py +0 -0
  84. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/py.typed +0 -0
  85. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/pydantic.py +0 -0
  86. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/__init__.py +0 -0
  87. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_budget.py +0 -0
  88. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_budgets.py +0 -0
  89. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_feedback.py +0 -0
  90. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_fields.py +0 -0
  91. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_inflight.py +0 -0
  92. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_rate.py +0 -0
  93. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/ratelimit/_transport.py +0 -0
  94. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/__init__.py +0 -0
  95. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_budget.py +0 -0
  96. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_classify.py +0 -0
  97. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_policy.py +0 -0
  98. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_tracking.py +0 -0
  99. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/retry/_transport.py +0 -0
  100. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/__init__.py +0 -0
  101. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_addresses.py +0 -0
  102. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_credentials.py +0 -0
  103. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_downgrade.py +0 -0
  104. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/security/_transport.py +0 -0
  105. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/streaming/__init__.py +0 -0
  106. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/streaming/_stream.py +0 -0
  107. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/__init__.py +0 -0
  108. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_breakers.py +0 -0
  109. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_recording.py +0 -0
  110. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_time.py +0 -0
  111. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/_transport.py +0 -0
  112. {headgate-0.3.0 → headgate-0.5.0}/src/headgate/testing/faults.py +0 -0
  113. {headgate-0.3.0 → headgate-0.5.0}/tests/__init__.py +0 -0
  114. {headgate-0.3.0 → headgate-0.5.0}/tests/auth/__init__.py +0 -0
  115. {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_cached_token_auth.py +0 -0
  116. {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_credential_stampers.py +0 -0
  117. {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_flows_are_uniform.py +0 -0
  118. {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_header_and_query_auth.py +0 -0
  119. {headgate-0.3.0 → headgate-0.5.0}/tests/auth/test_mint_failures.py +0 -0
  120. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/__init__.py +0 -0
  121. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker.py +0 -0
  122. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_charging.py +0 -0
  123. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_integration.py +0 -0
  124. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_keying.py +0 -0
  125. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_breaker_state_machine.py +0 -0
  126. {headgate-0.3.0 → headgate-0.5.0}/tests/breaker/test_registry.py +0 -0
  127. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/__init__.py +0 -0
  128. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/_helpers.py +0 -0
  129. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_conditional.py +0 -0
  130. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_credentials.py +0 -0
  131. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_events.py +0 -0
  132. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_extension_passthrough.py +0 -0
  133. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_fallback.py +0 -0
  134. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_filters.py +0 -0
  135. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_held_bodies.py +0 -0
  136. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_integration.py +0 -0
  137. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_shared_downloads.py +0 -0
  138. {headgate-0.3.0 → headgate-0.5.0}/tests/cache/test_store_on_accept.py +0 -0
  139. {headgate-0.3.0 → headgate-0.5.0}/tests/client/__init__.py +0 -0
  140. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_call_options.py +0 -0
  141. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_client.py +0 -0
  142. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_deadline.py +0 -0
  143. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_error_details.py +0 -0
  144. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_error_messages.py +0 -0
  145. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_events.py +0 -0
  146. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_failure_policy.py +0 -0
  147. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_invalid_url.py +0 -0
  148. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_middleware.py +0 -0
  149. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_options.py +0 -0
  150. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_policy.py +0 -0
  151. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_redirect_identity.py +0 -0
  152. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_response_size_cap.py +0 -0
  153. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_retry_opt_out.py +0 -0
  154. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_timeouts_fit_deadline.py +0 -0
  155. {headgate-0.3.0 → headgate-0.5.0}/tests/client/test_verbs.py +0 -0
  156. {headgate-0.3.0 → headgate-0.5.0}/tests/conftest.py +0 -0
  157. {headgate-0.3.0 → headgate-0.5.0}/tests/core/__init__.py +0 -0
  158. {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_context.py +0 -0
  159. {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_events.py +0 -0
  160. {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_origin.py +0 -0
  161. {headgate-0.3.0 → headgate-0.5.0}/tests/core/test_retry_after.py +0 -0
  162. {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/__init__.py +0 -0
  163. {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_errors.py +0 -0
  164. {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_event_stream.py +0 -0
  165. {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_msgspec.py +0 -0
  166. {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_pydantic.py +0 -0
  167. {headgate-0.3.0 → headgate-0.5.0}/tests/decoding/test_responses.py +0 -0
  168. {headgate-0.3.0 → headgate-0.5.0}/tests/errors/__init__.py +0 -0
  169. {headgate-0.3.0 → headgate-0.5.0}/tests/errors/__snapshots__/test_error_messages_snapshot.ambr +0 -0
  170. {headgate-0.3.0 → headgate-0.5.0}/tests/errors/test_error_messages_snapshot.py +0 -0
  171. {headgate-0.3.0 → headgate-0.5.0}/tests/examples/__init__.py +0 -0
  172. {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_docs.py +0 -0
  173. {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_orders_client.py +0 -0
  174. {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_quickstart.py +0 -0
  175. {headgate-0.3.0 → headgate-0.5.0}/tests/examples/test_series_client.py +0 -0
  176. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/__init__.py +0 -0
  177. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/_support.py +0 -0
  178. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_breaker_gate.py +0 -0
  179. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_cache_and_auths.py +0 -0
  180. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_deadline.py +0 -0
  181. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_destinations.py +0 -0
  182. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_events.py +0 -0
  183. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_hedging.py +0 -0
  184. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_pagination_credentials.py +0 -0
  185. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_replayable_body.py +0 -0
  186. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_retry_and_rate.py +0 -0
  187. {headgate-0.3.0 → headgate-0.5.0}/tests/integration/test_views.py +0 -0
  188. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/__init__.py +0 -0
  189. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/__snapshots__/test_snapshots.ambr +0 -0
  190. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/_support.py +0 -0
  191. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_accept.py +0 -0
  192. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_deprecation.py +0 -0
  193. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_otel.py +0 -0
  194. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_otel_isolation.py +0 -0
  195. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_snapshots.py +0 -0
  196. {headgate-0.3.0 → headgate-0.5.0}/tests/observe/test_with_options.py +0 -0
  197. {headgate-0.3.0 → headgate-0.5.0}/tests/package/__init__.py +0 -0
  198. {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_api_surface.py +0 -0
  199. {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_boundaries.py +0 -0
  200. {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_contracts.py +0 -0
  201. {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_import_isolation.py +0 -0
  202. {headgate-0.3.0 → headgate-0.5.0}/tests/package/test_metadata.py +0 -0
  203. {headgate-0.3.0 → headgate-0.5.0}/tests/pagination/__init__.py +0 -0
  204. {headgate-0.3.0 → headgate-0.5.0}/tests/pagination/test_link_header.py +0 -0
  205. {headgate-0.3.0 → headgate-0.5.0}/tests/performance/__init__.py +0 -0
  206. {headgate-0.3.0 → headgate-0.5.0}/tests/performance/test_memory.py +0 -0
  207. {headgate-0.3.0 → headgate-0.5.0}/tests/properties/__init__.py +0 -0
  208. {headgate-0.3.0 → headgate-0.5.0}/tests/properties/test_policy_properties.py +0 -0
  209. {headgate-0.3.0 → headgate-0.5.0}/tests/properties/test_url_properties.py +0 -0
  210. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/__init__.py +0 -0
  211. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_budget.py +0 -0
  212. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_client_feedback.py +0 -0
  213. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_feedback.py +0 -0
  214. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_in_flight.py +0 -0
  215. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_rate.py +0 -0
  216. {headgate-0.3.0 → headgate-0.5.0}/tests/ratelimit/test_rate_limit_transport.py +0 -0
  217. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/__init__.py +0 -0
  218. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_budget_and_classify.py +0 -0
  219. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_client_retries.py +0 -0
  220. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_faults.py +0 -0
  221. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_parking_and_hedging.py +0 -0
  222. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_policy.py +0 -0
  223. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_properties.py +0 -0
  224. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_tracking.py +0 -0
  225. {headgate-0.3.0 → headgate-0.5.0}/tests/retry/test_transport.py +0 -0
  226. {headgate-0.3.0 → headgate-0.5.0}/tests/security/__init__.py +0 -0
  227. {headgate-0.3.0 → headgate-0.5.0}/tests/security/_servers.py +0 -0
  228. {headgate-0.3.0 → headgate-0.5.0}/tests/security/_web.py +0 -0
  229. {headgate-0.3.0 → headgate-0.5.0}/tests/security/certs/ca.pem +0 -0
  230. {headgate-0.3.0 → headgate-0.5.0}/tests/security/certs/server.pem +0 -0
  231. {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_addresses.py +0 -0
  232. {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_credential_origins.py +0 -0
  233. {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_origin_properties.py +0 -0
  234. {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_pinned_transport.py +0 -0
  235. {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_redirect_hardening.py +0 -0
  236. {headgate-0.3.0 → headgate-0.5.0}/tests/security/test_ssrf_guard.py +0 -0
  237. {headgate-0.3.0 → headgate-0.5.0}/tests/streaming/__init__.py +0 -0
  238. {headgate-0.3.0 → headgate-0.5.0}/tests/streaming/test_request_bodies.py +0 -0
  239. {headgate-0.3.0 → headgate-0.5.0}/tests/streaming/test_stream.py +0 -0
  240. {headgate-0.3.0 → headgate-0.5.0}/tests/support/__init__.py +0 -0
  241. {headgate-0.3.0 → headgate-0.5.0}/tests/support/breakers.py +0 -0
  242. {headgate-0.3.0 → headgate-0.5.0}/tests/support/budgets.py +0 -0
  243. {headgate-0.3.0 → headgate-0.5.0}/tests/support/clients.py +0 -0
  244. {headgate-0.3.0 → headgate-0.5.0}/tests/support/events.py +0 -0
  245. {headgate-0.3.0 → headgate-0.5.0}/tests/support/responses.py +0 -0
  246. {headgate-0.3.0 → headgate-0.5.0}/tests/support/tokens.py +0 -0
  247. {headgate-0.3.0 → headgate-0.5.0}/tests/support/wire.py +0 -0
  248. {headgate-0.3.0 → headgate-0.5.0}/tests/testing/__init__.py +0 -0
  249. {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_breakers.py +0 -0
  250. {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_cassettes.py +0 -0
  251. {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_fake_transport.py +0 -0
  252. {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_recording.py +0 -0
  253. {headgate-0.3.0 → headgate-0.5.0}/tests/testing/test_time.py +0 -0
  254. {headgate-0.3.0 → headgate-0.5.0}/tests/transport/__init__.py +0 -0
  255. {headgate-0.3.0 → headgate-0.5.0}/tests/transport/test_curl.py +0 -0
  256. {headgate-0.3.0 → headgate-0.5.0}/tests/transport/test_health.py +0 -0
  257. {headgate-0.3.0 → headgate-0.5.0}/tests/urls/__init__.py +0 -0
  258. {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_empty_segment.py +0 -0
  259. {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_path_escaping.py +0 -0
  260. {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_route_template.py +0 -0
  261. {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_sanitize_url.py +0 -0
  262. {headgate-0.3.0 → headgate-0.5.0}/tests/urls/test_secret_query_params.py +0 -0
@@ -12,3 +12,6 @@ htmlcov/
12
12
  .benchmarks/
13
13
  mutants/
14
14
  .hypothesis/
15
+
16
+ # The docs site, built by `zensical build`
17
+ site/
@@ -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.3.0...HEAD
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.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.com/kelsayed17/headgate/tree/main/docs
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
+ [![PyPI](https://img.shields.io/pypi/v/headgate)](https://pypi.org/project/headgate/)
47
+ [![Python](https://img.shields.io/pypi/pyversions/headgate)](https://pypi.org/project/headgate/)
48
+ [![CI](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml)
49
+ [![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)](CONTRIBUTING.md)
50
+ [![Docs](https://img.shields.io/badge/docs-kelsayed17.github.io%2Fheadgate-blue)](https://kelsayed17.github.io/headgate/)
51
+ [![Licence: MIT](https://img.shields.io/pypi/l/headgate)](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 (endpoint paths are t-strings) and `httpx2`, pydantic's fork of httpx. Upstream `httpx` is not
58
- supported: passing one of its objects raises a `TypeError` naming the mistake.
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
+ [![PyPI](https://img.shields.io/pypi/v/headgate)](https://pypi.org/project/headgate/)
8
+ [![Python](https://img.shields.io/pypi/pyversions/headgate)](https://pypi.org/project/headgate/)
9
+ [![CI](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kelsayed17/headgate/actions/workflows/ci.yml)
10
+ [![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)](CONTRIBUTING.md)
11
+ [![Docs](https://img.shields.io/badge/docs-kelsayed17.github.io%2Fheadgate-blue)](https://kelsayed17.github.io/headgate/)
12
+ [![Licence: MIT](https://img.shields.io/pypi/l/headgate)](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 (endpoint paths are t-strings) and `httpx2`, pydantic's fork of httpx. Upstream `httpx` is not
19
- supported: passing one of its objects raises a `TypeError` naming the mistake.
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`](../examples/orders_client.py) has a complete one. What the flow can count on:
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
+ ![headgate logo](assets/logo.png)
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">&rarr;</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.