httpx-debug 0.1.0__tar.gz

httpx_debug-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest -q

httpx_debug-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

httpx_debug-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+uv.lock

httpx_debug-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mayur Rawte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

httpx_debug-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: httpx-debug
+Version: 0.1.0
+Summary: Failure-aware curl output for httpx: reproduce any (failing) request as a paste-able, secret-redacted curl command — printed or copied to your clipboard, even over SSH.
+Project-URL: Homepage, https://github.com/mayurrawte/httpx-debug
+Author: Mayur Rawte
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clipboard,curl,debug,debugging,devtools,httpx
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Description-Content-Type: text/markdown
+
+# httpx-debug
+
+**Reproduce any httpx request — especially the failing ones — as a paste-able curl command.**
+
+Stop print-debugging your HTTP calls:
+
+```python
+# before
+print(self._headers())
+print(params)
+print(self.base_url)
+print(path)
+
+# after
+import httpx_debug
+httpx_debug.attach(client)   # failing requests print a ready-to-paste curl command
+```
+
+When a request fails (4xx / 5xx / timeout / connection error), `httpx-debug` prints — and optionally copies to your clipboard — the exact `curl` command that reproduces it, with your secrets redacted:
+
+```
+# httpx-debug: 401 Unauthorized ← POST https://api.example.com/v1/users
+curl -X POST -H 'Authorization: <redacted>' -H 'Content-Type: application/json' -d '{"name": "mayur"}' https://api.example.com/v1/users
+```
+
+## Why not curlify?
+
+[curlify](https://pypi.org/project/curlify/) and friends convert a request object to curl — and that's it. `httpx-debug` is the debugging layer around that:
+
+- **Failure-aware** — attach once, hear about it only when something breaks. No call-site changes.
+- **Secret redaction by default** — `Authorization`, `Cookie`, `X-API-Key`, … become `<redacted>` so you can paste the command into an issue or Slack without leaking credentials.
+- **Clipboard, even over SSH** — uses `pbcopy`/`xclip`/`wl-copy`/`clip` locally and falls back to the OSC 52 terminal escape, which copies to your *local* clipboard from a remote shell.
+- **Async-first** — works identically with `httpx.Client` and `httpx.AsyncClient`.
+- **Sees exceptions too** — the drop-in `httpx_debug.Client` / `AsyncClient` also capture timeouts and connection errors, not just error status codes.
+
+Works anywhere httpx does — including under the **OpenAI and Anthropic SDKs**, which accept a custom `http_client`. Ever wondered what your LLM call actually sends over the wire?
+
+```python
+import httpx, httpx_debug, openai
+
+http_client = httpx.Client()
+httpx_debug.attach(http_client, on="all")
+client = openai.OpenAI(http_client=http_client)
+```
+
+## Install
+
+```bash
+pip install httpx-debug
+```
+
+Zero dependencies beyond httpx itself.
+
+## Usage
+
+### Convert a request to curl
+
+```python
+import httpx_debug
+
+curl = httpx_debug.to_curl(request)                 # secrets redacted
+curl = httpx_debug.to_curl(request, redact=False)   # raw
+```
+
+### Copy to clipboard
+
+```python
+httpx_debug.copy(request)   # returns True if a clipboard was reachable
+```
+
+### Attach to any client (yours or an SDK's)
+
+```python
+client = httpx.AsyncClient()
+httpx_debug.attach(client)              # print curl for 4xx/5xx responses
+httpx_debug.attach(client, on="all")    # ...or for every request
+httpx_debug.attach(client, copy=True)   # also copy to clipboard
+httpx_debug.detach(client)              # remove
+```
+
+`attach` uses httpx event hooks, so it can't observe transport exceptions (timeouts, DNS failures). For those, use the drop-in clients:
+
+### Drop-in clients (also capture timeouts & connection errors)
+
+```python
+client = httpx_debug.AsyncClient(base_url="https://api.example.com")
+# behaves exactly like httpx.AsyncClient, plus curl output on any failure
+```
+
+### Options
+
+| Option | Default | |
+|---|---|---|
+| `on` | `"error"` | `"error"` (status ≥ 400 + exceptions) or `"all"` |
+| `copy` | `False` | also copy the curl command to the clipboard |
+| `redact` | `True` | replace sensitive header values with `<redacted>` |
+| `copy_redact` | follows `redact` | redaction for the *clipboard* copy specifically |
+| `redact_headers` | built-in set | which headers count as sensitive (lowercase) |
+| `file` | `sys.stderr` | where to print |
+
+On the drop-in clients the same options are prefixed: `debug_on`, `debug_copy`, `debug_redact`, `debug_copy_redact`, `debug_redact_headers`, `debug_file`.
+
+### Print safe, copy replayable
+
+The printed command ends up in logs and screenshots — keep it redacted. The clipboard's job is *replaying* the request, which needs real credentials:
+
+```python
+httpx_debug.attach(client, copy=True, copy_redact=False)
+# terminal: Authorization: <redacted>     ← safe to paste in an issue
+# clipboard: Authorization: Bearer sk-…   ← actually runs
+```
+
+Raw copying is always opt-in — remember clipboard managers keep history.
+
+## Notes
+
+- Streamed request bodies are never consumed by httpx-debug; the curl output notes `# request body was streamed and is not shown`.
+- Non-UTF-8 bodies are omitted with a byte-count comment.
+- Debug tooling must never break your app: clipboard and hook failures are swallowed.
+
+## Roadmap
+
+- pytest plugin: show the curl of the last failed request under the traceback
+- response capture alongside the request
+- `requests` support
+- a Node.js sibling for server-side `fetch`
+
+## License
+
+MIT

httpx_debug-0.1.0/README.md

@@ -0,0 +1,130 @@
+# httpx-debug
+
+**Reproduce any httpx request — especially the failing ones — as a paste-able curl command.**
+
+Stop print-debugging your HTTP calls:
+
+```python
+# before
+print(self._headers())
+print(params)
+print(self.base_url)
+print(path)
+
+# after
+import httpx_debug
+httpx_debug.attach(client)   # failing requests print a ready-to-paste curl command
+```
+
+When a request fails (4xx / 5xx / timeout / connection error), `httpx-debug` prints — and optionally copies to your clipboard — the exact `curl` command that reproduces it, with your secrets redacted:
+
+```
+# httpx-debug: 401 Unauthorized ← POST https://api.example.com/v1/users
+curl -X POST -H 'Authorization: <redacted>' -H 'Content-Type: application/json' -d '{"name": "mayur"}' https://api.example.com/v1/users
+```
+
+## Why not curlify?
+
+[curlify](https://pypi.org/project/curlify/) and friends convert a request object to curl — and that's it. `httpx-debug` is the debugging layer around that:
+
+- **Failure-aware** — attach once, hear about it only when something breaks. No call-site changes.
+- **Secret redaction by default** — `Authorization`, `Cookie`, `X-API-Key`, … become `<redacted>` so you can paste the command into an issue or Slack without leaking credentials.
+- **Clipboard, even over SSH** — uses `pbcopy`/`xclip`/`wl-copy`/`clip` locally and falls back to the OSC 52 terminal escape, which copies to your *local* clipboard from a remote shell.
+- **Async-first** — works identically with `httpx.Client` and `httpx.AsyncClient`.
+- **Sees exceptions too** — the drop-in `httpx_debug.Client` / `AsyncClient` also capture timeouts and connection errors, not just error status codes.
+
+Works anywhere httpx does — including under the **OpenAI and Anthropic SDKs**, which accept a custom `http_client`. Ever wondered what your LLM call actually sends over the wire?
+
+```python
+import httpx, httpx_debug, openai
+
+http_client = httpx.Client()
+httpx_debug.attach(http_client, on="all")
+client = openai.OpenAI(http_client=http_client)
+```
+
+## Install
+
+```bash
+pip install httpx-debug
+```
+
+Zero dependencies beyond httpx itself.
+
+## Usage
+
+### Convert a request to curl
+
+```python
+import httpx_debug
+
+curl = httpx_debug.to_curl(request)                 # secrets redacted
+curl = httpx_debug.to_curl(request, redact=False)   # raw
+```
+
+### Copy to clipboard
+
+```python
+httpx_debug.copy(request)   # returns True if a clipboard was reachable
+```
+
+### Attach to any client (yours or an SDK's)
+
+```python
+client = httpx.AsyncClient()
+httpx_debug.attach(client)              # print curl for 4xx/5xx responses
+httpx_debug.attach(client, on="all")    # ...or for every request
+httpx_debug.attach(client, copy=True)   # also copy to clipboard
+httpx_debug.detach(client)              # remove
+```
+
+`attach` uses httpx event hooks, so it can't observe transport exceptions (timeouts, DNS failures). For those, use the drop-in clients:
+
+### Drop-in clients (also capture timeouts & connection errors)
+
+```python
+client = httpx_debug.AsyncClient(base_url="https://api.example.com")
+# behaves exactly like httpx.AsyncClient, plus curl output on any failure
+```
+
+### Options
+
+| Option | Default | |
+|---|---|---|
+| `on` | `"error"` | `"error"` (status ≥ 400 + exceptions) or `"all"` |
+| `copy` | `False` | also copy the curl command to the clipboard |
+| `redact` | `True` | replace sensitive header values with `<redacted>` |
+| `copy_redact` | follows `redact` | redaction for the *clipboard* copy specifically |
+| `redact_headers` | built-in set | which headers count as sensitive (lowercase) |
+| `file` | `sys.stderr` | where to print |
+
+On the drop-in clients the same options are prefixed: `debug_on`, `debug_copy`, `debug_redact`, `debug_copy_redact`, `debug_redact_headers`, `debug_file`.
+
+### Print safe, copy replayable
+
+The printed command ends up in logs and screenshots — keep it redacted. The clipboard's job is *replaying* the request, which needs real credentials:
+
+```python
+httpx_debug.attach(client, copy=True, copy_redact=False)
+# terminal: Authorization: <redacted>     ← safe to paste in an issue
+# clipboard: Authorization: Bearer sk-…   ← actually runs
+```
+
+Raw copying is always opt-in — remember clipboard managers keep history.
+
+## Notes
+
+- Streamed request bodies are never consumed by httpx-debug; the curl output notes `# request body was streamed and is not shown`.
+- Non-UTF-8 bodies are omitted with a byte-count comment.
+- Debug tooling must never break your app: clipboard and hook failures are swallowed.
+
+## Roadmap
+
+- pytest plugin: show the curl of the last failed request under the traceback
+- response capture alongside the request
+- `requests` support
+- a Node.js sibling for server-side `fetch`
+
+## License
+
+MIT

httpx_debug-0.1.0/docs/superpowers/specs/2026-07-16-httpx-debug-design.md

@@ -0,0 +1,99 @@
+# httpx-debug — design
+
+**Date:** 2026-07-16
+**Status:** approved (validated demand 2026-07-15/16; see README for positioning)
+
+## Problem
+
+Debugging httpx calls today means sprinkling `print(headers) / print(params) / print(url)`
+around call sites, then hand-assembling a curl command to reproduce the failure.
+Existing packages (curlify, curlify2, curlify3) only do request→curl *conversion* —
+no failure triggering, no secret redaction, no clipboard, no async-first design.
+httpx's official answer is DEBUG logging, which produces log noise, not a
+reproducible command. The OpenAI and Anthropic SDKs are built on httpx, making
+"what did my LLM call actually send" a growing instance of this pain.
+
+## Goal (v1)
+
+A tiny, dependency-light package (`httpx` only) that turns any httpx request —
+especially a *failing* one — into a paste-able, secret-redacted curl command,
+printed and/or copied to the clipboard (working even over SSH via OSC 52).
+
+## Non-goals (v1)
+
+- `requests` support (curlify covers it; may revisit)
+- pytest plugin (roadmap v2)
+- Other languages (roadmap; concept is portable)
+- Response-body capture/pretty-printing (roadmap)
+
+## Public API
+
+```python
+import httpx_debug
+
+httpx_debug.to_curl(request, redact=True)          # httpx.Request -> str
+httpx_debug.copy(request_or_str, redact=True)      # -> bool (clipboard success)
+httpx_debug.attach(client, on="error", copy=False, redact=True, file=None)
+httpx_debug.detach(client)
+httpx_debug.Client(...) / httpx_debug.AsyncClient(...)  # drop-in subclasses
+```
+
+- `to_curl`: single-line curl; skips `Content-Length`/`Host` (curl recomputes);
+  redacts sensitive header values by default (`Authorization`, `Cookie`,
+  `X-API-Key`, etc.) to `<redacted>`; shell-quotes via `shlex`.
+  Body: uses `request.content` when available; streamed bodies emit a
+  `# request body was streamed and is not shown` comment; non-UTF-8 bodies emit
+  `# binary request body (N bytes) not shown`.
+- `attach`: installs httpx event hooks on an existing `Client`/`AsyncClient`
+  (sync/async detected automatically). `on="error"` fires on status >= 400;
+  `on="all"` fires on every response. Prints to `file` (default stderr);
+  `copy=True` also copies to clipboard. Works on clients you don't construct
+  yourself (e.g. pass to OpenAI SDK via `http_client=`). Event hooks cannot see
+  transport exceptions — documented limitation.
+- `Client`/`AsyncClient`: subclasses overriding `send()`, so they additionally
+  capture `httpx.RequestError` (timeouts, connection errors), emit the curl,
+  and re-raise.
+- Clipboard: native tool first (`pbcopy`/`xclip`/`wl-copy`/`clip`), falling back
+  to the OSC 52 escape sequence written to `/dev/tty` so copy works over SSH.
+  Never raises; returns success bool.
+
+## Architecture
+
+```
+src/httpx_debug/
+  __init__.py      # public API surface
+  _curl.py         # to_curl + redaction
+  _clipboard.py    # copy_text: native tools + OSC 52 fallback
+  _hooks.py        # attach/detach, Client/AsyncClient subclasses, emit logic
+tests/             # pytest; httpx.MockTransport, no network
+```
+
+Each module independently testable; `_curl` is pure, `_clipboard` isolated
+behind `copy_text(text) -> bool`, `_hooks` composes the two.
+
+## Error handling
+
+Debug tooling must never break the app: hook and clipboard failures are
+swallowed (clipboard returns False; emit falls back to print). `to_curl` never
+raises on weird bodies — it degrades to explanatory comments.
+
+## Testing
+
+- `_curl`: method/-X rules, header inclusion+skips, redaction on/off + custom
+  set, query params, quoting, JSON body, binary body, streamed body.
+- `_hooks`: MockTransport 500 → emits; 200 + on="error" → silent; on="all" →
+  emits; async variants; Client subclass emits on ConnectError and re-raises;
+  detach removes hooks.
+- `_clipboard`: monkeypatched subprocess; OSC 52 fallback content.
+
+## Naming / packaging
+
+PyPI name `httpx-debug` (verified unregistered 2026-07-16), import
+`httpx_debug`. MIT. `hatchling` build, `requires-python >= 3.9`,
+runtime dep: `httpx>=0.23`. Publish with Classic Automation token (per npm/PyPI
+CI conventions Mayur uses).
+
+## Roadmap (post-v1)
+
+pytest plugin (curl of last failed request under traceback) · response capture ·
+`requests` support · Node sibling package.

httpx_debug-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "httpx-debug"
+version = "0.1.0"
+description = "Failure-aware curl output for httpx: reproduce any (failing) request as a paste-able, secret-redacted curl command — printed or copied to your clipboard, even over SSH."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Mayur Rawte" }]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.23"]
+keywords = ["httpx", "curl", "debug", "debugging", "clipboard", "devtools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Homepage = "https://github.com/mayurrawte/httpx-debug"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/httpx_debug"]

httpx_debug-0.1.0/src/httpx_debug/__init__.py

@@ -0,0 +1,14 @@
+from httpx_debug._clipboard import copy
+from httpx_debug._curl import DEFAULT_REDACT_HEADERS, REDACTED, to_curl
+from httpx_debug._hooks import AsyncClient, Client, attach, detach
+
+__all__ = [
+    "to_curl",
+    "copy",
+    "attach",
+    "detach",
+    "Client",
+    "AsyncClient",
+    "REDACTED",
+    "DEFAULT_REDACT_HEADERS",
+]

httpx_debug-0.1.0/src/httpx_debug/_clipboard.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import base64
+import shutil
+import subprocess
+import sys
+from typing import Union
+
+import httpx
+
+from httpx_debug._curl import to_curl
+
+_TOOLS = (
+    ["pbcopy"],
+    ["wl-copy"],
+    ["xclip", "-selection", "clipboard"],
+    ["xsel", "--clipboard", "--input"],
+    ["clip"],
+)
+
+
+def copy(request_or_text: Union[httpx.Request, str], *, redact: bool = True) -> bool:
+    """Copy a request (as a curl command) or plain text to the clipboard.
+
+    Returns True on success; never raises.
+    """
+    if isinstance(request_or_text, str):
+        text = request_or_text
+    else:
+        text = to_curl(request_or_text, redact=redact)
+    return copy_text(text)
+
+
+def copy_text(text: str) -> bool:
+    return _native_copy(text) or _osc52_copy(text)
+
+
+def _native_copy(text: str) -> bool:
+    for cmd in _TOOLS:
+        if not shutil.which(cmd[0]):
+            continue
+        try:
+            result = subprocess.run(
+                cmd,
+                input=text.encode("utf-8"),
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+            )
+        except Exception:
+            continue
+        if result.returncode == 0:
+            return True
+    return False
+
+
+def _osc52_copy(text: str) -> bool:
+    # OSC 52 asks the terminal emulator to set the clipboard, so it reaches
+    # the *local* clipboard even from an SSH session
+    payload = base64.b64encode(text.encode("utf-8"))
+    try:
+        tty = _open_tty()
+    except Exception:
+        return False
+    try:
+        tty.write(b"\x1b]52;c;" + payload + b"\x07")
+        tty.flush()
+        return True
+    except Exception:
+        return False
+    finally:
+        try:
+            tty.close()
+        except Exception:
+            pass
+
+
+def _open_tty():
+    if sys.platform == "win32":
+        raise OSError("OSC 52 fallback not supported on Windows")
+    return open("/dev/tty", "wb")

httpx_debug-0.1.0/src/httpx_debug/_curl.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import shlex
+from typing import Iterable, Optional, Tuple
+
+import httpx
+
+REDACTED = "<redacted>"
+
+DEFAULT_REDACT_HEADERS = frozenset(
+    {
+        "authorization",
+        "proxy-authorization",
+        "cookie",
+        "set-cookie",
+        "x-api-key",
+        "api-key",
+        "x-auth-token",
+        "x-amz-security-token",
+    }
+)
+
+# curl derives these itself; including them makes the command wrong when edited
+_SKIP_HEADERS = frozenset({"host", "content-length"})
+
+
+def to_curl(
+    request: httpx.Request,
+    *,
+    redact: bool = True,
+    redact_headers: Optional[Iterable[str]] = None,
+) -> str:
+    """Render an httpx.Request as a single-line, shell-safe curl command.
+
+    Sensitive header values are replaced with ``<redacted>`` unless
+    ``redact=False``. Streamed bodies are never consumed.
+    """
+    sensitive = (
+        frozenset(h.lower() for h in redact_headers)
+        if redact_headers is not None
+        else DEFAULT_REDACT_HEADERS
+    )
+    tokens = ["curl"]
+    if request.method != "GET":
+        tokens += ["-X", request.method]
+    for name, value in request.headers.multi_items():
+        lower = name.lower()
+        if lower in _SKIP_HEADERS:
+            continue
+        if redact and lower in sensitive:
+            value = REDACTED
+        tokens += ["-H", f"{_display_name(name)}: {value}"]
+    body, comment = _body(request)
+    if body is not None:
+        tokens += ["-d", body]
+    tokens.append(str(request.url))
+    command = shlex.join(tokens)
+    if comment:
+        command += "\n" + comment
+    return command
+
+
+def _display_name(name: str) -> str:
+    # httpx lowercases header names; Title-Case reads closer to what was sent
+    return "-".join(part.capitalize() for part in name.split("-")) if name.islower() else name
+
+
+def _body(request: httpx.Request) -> Tuple[Optional[str], Optional[str]]:
+    try:
+        raw = request.content
+    except httpx.RequestNotRead:
+        return None, "# request body was streamed and is not shown"
+    if not raw:
+        return None, None
+    try:
+        return raw.decode("utf-8"), None
+    except UnicodeDecodeError:
+        return None, f"# binary request body ({len(raw)} bytes) not shown"

httpx_debug-0.1.0/src/httpx_debug/_hooks.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import sys
+from typing import IO, Iterable, Optional
+
+import httpx
+
+from httpx_debug import _clipboard
+from httpx_debug._curl import to_curl
+
+_MARKER = "_httpx_debug_hook"
+
+
+class _Config:
+    def __init__(
+        self,
+        on: str = "error",
+        copy: bool = False,
+        redact: bool = True,
+        redact_headers: Optional[Iterable[str]] = None,
+        file: Optional[IO[str]] = None,
+        copy_redact: Optional[bool] = None,
+    ):
+        if on not in ("error", "all"):
+            raise ValueError(f'on must be "error" or "all", got {on!r}')
+        self.on = on
+        self.copy = copy
+        self.redact = redact
+        self.redact_headers = redact_headers
+        self.file = file
+        # clipboard redaction follows `redact` unless explicitly overridden;
+        # copy_redact=False keeps printed output safe while the clipboard
+        # gets a replayable command with real credentials
+        self.copy_redact = redact if copy_redact is None else copy_redact
+
+
+def _emit(request: httpx.Request, headline: str, config: _Config) -> None:
+    curl = to_curl(request, redact=config.redact, redact_headers=config.redact_headers)
+    out = config.file if config.file is not None else sys.stderr
+    print(f"# httpx-debug: {headline} ← {request.method} {request.url}", file=out)
+    print(curl, file=out)
+    if config.copy:
+        if config.copy_redact == config.redact:
+            clip = curl
+        else:
+            clip = to_curl(request, redact=config.copy_redact, redact_headers=config.redact_headers)
+        _clipboard.copy_text(clip)
+
+
+def _handle_response(response: httpx.Response, config: _Config) -> None:
+    if config.on == "error" and response.status_code < 400:
+        return
+    _emit(response.request, f"{response.status_code} {response.reason_phrase}", config)
+
+
+def attach(
+    client,
+    *,
+    on: str = "error",
+    copy: bool = False,
+    redact: bool = True,
+    redact_headers: Optional[Iterable[str]] = None,
+    file: Optional[IO[str]] = None,
+    copy_redact: Optional[bool] = None,
+):
+    """Install a response event hook that prints (and optionally copies) the
+    curl command for failing requests. Works on httpx.Client and AsyncClient,
+    including clients handed to third-party SDKs.
+
+    Event hooks cannot observe transport exceptions (timeouts, DNS failures);
+    use httpx_debug.Client / httpx_debug.AsyncClient for those.
+    """
+    config = _Config(
+        on=on,
+        copy=copy,
+        redact=redact,
+        redact_headers=redact_headers,
+        file=file,
+        copy_redact=copy_redact,
+    )
+
+    if isinstance(client, httpx.AsyncClient):
+
+        async def hook(response: httpx.Response) -> None:
+            _handle_response(response, config)
+
+    else:
+
+        def hook(response: httpx.Response) -> None:  # type: ignore[misc]
+            _handle_response(response, config)
+
+    setattr(hook, _MARKER, True)
+    hooks = {name: list(fns) for name, fns in client.event_hooks.items()}
+    hooks.setdefault("response", []).append(hook)
+    client.event_hooks = hooks
+    return client
+
+
+def detach(client) -> None:
+    """Remove hooks previously installed by attach()."""
+    client.event_hooks = {
+        name: [fn for fn in fns if not getattr(fn, _MARKER, False)]
+        for name, fns in client.event_hooks.items()
+    }
+
+
+def _pop_debug_kwargs(kwargs: dict) -> _Config:
+    return _Config(
+        on=kwargs.pop("debug_on", "error"),
+        copy=kwargs.pop("debug_copy", False),
+        redact=kwargs.pop("debug_redact", True),
+        redact_headers=kwargs.pop("debug_redact_headers", None),
+        file=kwargs.pop("debug_file", None),
+        copy_redact=kwargs.pop("debug_copy_redact", None),
+    )
+
+
+class Client(httpx.Client):
+    """Drop-in httpx.Client that also reports transport errors as curl."""
+
+    def __init__(self, *args, **kwargs):
+        self._debug = _pop_debug_kwargs(kwargs)
+        super().__init__(*args, **kwargs)
+
+    def send(self, request: httpx.Request, **kwargs) -> httpx.Response:
+        try:
+            response = super().send(request, **kwargs)
+        except httpx.RequestError as exc:
+            _emit(request, f"{type(exc).__name__}: {exc}", self._debug)
+            raise
+        _handle_response(response, self._debug)
+        return response
+
+
+class AsyncClient(httpx.AsyncClient):
+    """Drop-in httpx.AsyncClient that also reports transport errors as curl."""
+
+    def __init__(self, *args, **kwargs):
+        self._debug = _pop_debug_kwargs(kwargs)
+        super().__init__(*args, **kwargs)
+
+    async def send(self, request: httpx.Request, **kwargs) -> httpx.Response:
+        try:
+            response = await super().send(request, **kwargs)
+        except httpx.RequestError as exc:
+            _emit(request, f"{type(exc).__name__}: {exc}", self._debug)
+            raise
+        _handle_response(response, self._debug)
+        return response

httpx_debug-0.1.0/tests/test_clipboard.py

@@ -0,0 +1,83 @@
+import base64
+import shutil
+import subprocess
+
+import httpx
+
+import httpx_debug
+from httpx_debug import _clipboard
+from httpx_debug._clipboard import copy_text
+
+
+class FakeTTY:
+    def __init__(self):
+        self.data = b""
+
+    def write(self, b):
+        self.data += b
+
+    def flush(self):
+        pass
+
+    def close(self):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def test_copy_text_uses_native_tool(monkeypatch):
+    calls = {}
+    monkeypatch.setattr(shutil, "which", lambda name: f"/usr/bin/{name}")
+
+    def fake_run(cmd, **kwargs):
+        calls["cmd"] = cmd
+        calls["input"] = kwargs.get("input")
+        return subprocess.CompletedProcess(cmd, 0)
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    assert copy_text("hello") is True
+    assert calls["input"] == b"hello"
+
+
+def test_copy_text_falls_back_to_osc52_when_no_tool(monkeypatch):
+    monkeypatch.setattr(shutil, "which", lambda name: None)
+    tty = FakeTTY()
+    monkeypatch.setattr(_clipboard, "_open_tty", lambda: tty)
+    assert copy_text("hi") is True
+    assert tty.data.startswith(b"\x1b]52;c;")
+    assert base64.b64encode(b"hi") in tty.data
+
+
+def test_copy_text_never_raises(monkeypatch):
+    monkeypatch.setattr(shutil, "which", lambda name: None)
+
+    def boom():
+        raise OSError("no tty")
+
+    monkeypatch.setattr(_clipboard, "_open_tty", boom)
+    assert copy_text("hi") is False
+
+
+def test_public_copy_converts_request_and_redacts(monkeypatch):
+    captured = {}
+
+    def fake_copy_text(text):
+        captured["text"] = text
+        return True
+
+    monkeypatch.setattr(_clipboard, "copy_text", fake_copy_text)
+    req = httpx.Request("GET", "https://api.example.com/", headers={"Authorization": "Bearer sk-1"})
+    assert httpx_debug.copy(req) is True
+    assert "sk-1" not in captured["text"]
+    assert "<redacted>" in captured["text"]
+
+
+def test_public_copy_accepts_plain_string(monkeypatch):
+    captured = {}
+    monkeypatch.setattr(_clipboard, "copy_text", lambda t: bool(captured.setdefault("text", t)))
+    assert httpx_debug.copy("curl https://x.example") is True
+    assert captured["text"] == "curl https://x.example"

httpx_debug-0.1.0/tests/test_copy_redact.py

@@ -0,0 +1,50 @@
+import io
+
+import httpx
+
+import httpx_debug
+
+
+def sync_client(handler):
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def test_clipboard_redacted_by_default(monkeypatch):
+    copied = {}
+    monkeypatch.setattr("httpx_debug._clipboard.copy_text", lambda t: copied.setdefault("text", t) == t)
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(500))
+    httpx_debug.attach(client, file=buf, copy=True)
+    client.get("https://api.example.com/x", headers={"Authorization": "Bearer sk-1"})
+    assert "sk-1" not in copied["text"]
+    assert "<redacted>" in copied["text"]
+
+
+def test_copy_redact_false_copies_raw_but_prints_redacted(monkeypatch):
+    copied = {}
+    monkeypatch.setattr("httpx_debug._clipboard.copy_text", lambda t: copied.setdefault("text", t) == t)
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(500))
+    httpx_debug.attach(client, file=buf, copy=True, copy_redact=False)
+    client.get("https://api.example.com/x", headers={"Authorization": "Bearer sk-1"})
+    # clipboard gets the replayable command with the real credential
+    assert "Bearer sk-1" in copied["text"]
+    # terminal output stays safe to share
+    printed = buf.getvalue()
+    assert "sk-1" not in printed
+    assert "<redacted>" in printed
+
+
+def test_debug_client_supports_copy_redact(monkeypatch):
+    copied = {}
+    monkeypatch.setattr("httpx_debug._clipboard.copy_text", lambda t: copied.setdefault("text", t) == t)
+    buf = io.StringIO()
+    client = httpx_debug.Client(
+        transport=httpx.MockTransport(lambda req: httpx.Response(500)),
+        debug_file=buf,
+        debug_copy=True,
+        debug_copy_redact=False,
+    )
+    client.get("https://api.example.com/x", headers={"Authorization": "Bearer sk-1"})
+    assert "Bearer sk-1" in copied["text"]
+    assert "sk-1" not in buf.getvalue()

httpx_debug-0.1.0/tests/test_curl.py

@@ -0,0 +1,108 @@
+import httpx
+import pytest
+
+from httpx_debug import to_curl
+
+
+def test_simple_get_has_no_explicit_method():
+    req = httpx.Request("GET", "https://api.example.com/users")
+    curl = to_curl(req)
+    assert curl.startswith("curl ")
+    assert " -X " not in curl
+    assert curl.rstrip().endswith("https://api.example.com/users")
+
+
+def test_non_get_method_is_explicit():
+    req = httpx.Request("DELETE", "https://api.example.com/users/1")
+    assert " -X DELETE " in to_curl(req)
+
+
+def test_query_params_preserved_in_url():
+    req = httpx.Request("GET", "https://api.example.com/users", params={"page": "2", "q": "a b"})
+    curl = to_curl(req)
+    assert "page=2" in curl
+    assert "q=a+b" in curl or "q=a%20b" in curl
+
+
+def test_headers_included():
+    req = httpx.Request("GET", "https://api.example.com/", headers={"X-Custom": "yes"})
+    assert "X-Custom: yes" in to_curl(req)
+
+
+def test_host_and_content_length_skipped():
+    req = httpx.Request("POST", "https://api.example.com/", json={"a": 1})
+    curl = to_curl(req)
+    assert "content-length" not in curl.lower()
+    assert "host:" not in curl.lower()
+
+
+def test_authorization_redacted_by_default():
+    req = httpx.Request("GET", "https://api.example.com/", headers={"Authorization": "Bearer sk-secret"})
+    curl = to_curl(req)
+    assert "sk-secret" not in curl
+    assert "Authorization: <redacted>" in curl
+
+
+def test_redaction_covers_common_secret_headers():
+    req = httpx.Request(
+        "GET",
+        "https://api.example.com/",
+        headers={"X-API-Key": "k123", "Cookie": "session=abc"},
+    )
+    curl = to_curl(req)
+    assert "k123" not in curl
+    assert "session=abc" not in curl
+
+
+def test_redact_false_keeps_secrets():
+    req = httpx.Request("GET", "https://api.example.com/", headers={"Authorization": "Bearer sk-secret"})
+    assert "Bearer sk-secret" in to_curl(req, redact=False)
+
+
+def test_custom_redact_headers():
+    req = httpx.Request("GET", "https://api.example.com/", headers={"X-Tenant": "acme"})
+    curl = to_curl(req, redact_headers={"x-tenant"})
+    assert "acme" not in curl
+    assert "X-Tenant: <redacted>" in curl
+
+
+def test_json_body_included_as_data():
+    req = httpx.Request("POST", "https://api.example.com/users", json={"name": "mayur"})
+    curl = to_curl(req)
+    assert '-d \'{"name": "mayur"}\'' in curl or '-d \'{"name":"mayur"}\'' in curl
+
+
+def test_body_with_single_quotes_is_shell_safe():
+    req = httpx.Request("POST", "https://api.example.com/", content=b"it's fine")
+    curl = to_curl(req)
+    # shlex-style quoting: the result must be a single shell token containing the text
+    assert "it" in curl and "fine" in curl
+    import shlex
+
+    # the command must round-trip through a shell tokenizer without error
+    tokens = shlex.split(curl)
+    assert "it's fine" in tokens
+
+
+def test_binary_body_omitted_with_comment():
+    req = httpx.Request("POST", "https://api.example.com/", content=b"\xff\xfe\x00\x01")
+    curl = to_curl(req)
+    assert "-d" not in curl
+    assert "# binary request body (4 bytes) not shown" in curl
+
+
+def test_streamed_body_noted_not_consumed():
+    def gen():
+        yield b"chunk"
+
+    req = httpx.Request("POST", "https://api.example.com/", content=gen())
+    curl = to_curl(req)
+    assert "streamed" in curl
+    assert "-d" not in curl
+
+
+def test_output_is_single_command_line_plus_optional_comment():
+    req = httpx.Request("GET", "https://api.example.com/")
+    curl = to_curl(req)
+    command_lines = [l for l in curl.splitlines() if not l.startswith("#")]
+    assert len(command_lines) == 1

httpx_debug-0.1.0/tests/test_hooks.py

@@ -0,0 +1,127 @@
+import io
+
+import httpx
+import pytest
+
+import httpx_debug
+
+
+def sync_client(handler):
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def test_attach_prints_redacted_curl_on_error_response():
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(500))
+    httpx_debug.attach(client, file=buf)
+    client.get("https://api.example.com/x", headers={"Authorization": "Bearer sk-1"})
+    out = buf.getvalue()
+    assert "httpx-debug: 500" in out
+    assert "curl" in out
+    assert "<redacted>" in out
+    assert "sk-1" not in out
+
+
+def test_attach_silent_on_success_by_default():
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(200))
+    httpx_debug.attach(client, file=buf)
+    client.get("https://api.example.com/x")
+    assert buf.getvalue() == ""
+
+
+def test_attach_on_all_prints_for_success():
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(200))
+    httpx_debug.attach(client, on="all", file=buf)
+    client.get("https://api.example.com/x")
+    assert "curl" in buf.getvalue()
+
+
+def test_attach_preserves_existing_hooks():
+    seen = []
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(500))
+    client.event_hooks = {"response": [lambda r: seen.append(r.status_code)]}
+    httpx_debug.attach(client, file=buf)
+    client.get("https://api.example.com/x")
+    assert seen == [500]
+    assert "curl" in buf.getvalue()
+
+
+def test_detach_removes_only_our_hook():
+    seen = []
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(500))
+    client.event_hooks = {"response": [lambda r: seen.append(r.status_code)]}
+    httpx_debug.attach(client, file=buf)
+    httpx_debug.detach(client)
+    client.get("https://api.example.com/x")
+    assert buf.getvalue() == ""
+    assert seen == [500]
+
+
+def test_attach_copy_flag_copies_curl(monkeypatch):
+    copied = {}
+    monkeypatch.setattr("httpx_debug._clipboard.copy_text", lambda t: copied.setdefault("text", t) == t)
+    buf = io.StringIO()
+    client = sync_client(lambda req: httpx.Response(500))
+    httpx_debug.attach(client, file=buf, copy=True)
+    client.get("https://api.example.com/x")
+    assert copied["text"].startswith("curl")
+
+
+async def test_attach_async_client():
+    buf = io.StringIO()
+    client = httpx.AsyncClient(transport=httpx.MockTransport(lambda req: httpx.Response(503)))
+    httpx_debug.attach(client, file=buf)
+    async with client:
+        await client.get("https://api.example.com/x")
+    assert "httpx-debug: 503" in buf.getvalue()
+
+
+def test_debug_client_emits_on_error_status():
+    buf = io.StringIO()
+    client = httpx_debug.Client(
+        transport=httpx.MockTransport(lambda req: httpx.Response(404)), debug_file=buf
+    )
+    client.get("https://api.example.com/missing")
+    assert "httpx-debug: 404" in buf.getvalue()
+
+
+def test_debug_client_emits_curl_on_connect_error_and_reraises():
+    buf = io.StringIO()
+
+    def handler(req):
+        raise httpx.ConnectError("connection refused")
+
+    client = httpx_debug.Client(transport=httpx.MockTransport(handler), debug_file=buf)
+    with pytest.raises(httpx.ConnectError):
+        client.get("https://api.example.com/x")
+    out = buf.getvalue()
+    assert "ConnectError" in out
+    assert "curl" in out
+
+
+def test_debug_client_silent_on_success():
+    buf = io.StringIO()
+    client = httpx_debug.Client(
+        transport=httpx.MockTransport(lambda req: httpx.Response(200)), debug_file=buf
+    )
+    client.get("https://api.example.com/x")
+    assert buf.getvalue() == ""
+
+
+async def test_debug_async_client_emits_on_timeout_and_reraises():
+    buf = io.StringIO()
+
+    def handler(req):
+        raise httpx.ReadTimeout("timed out")
+
+    client = httpx_debug.AsyncClient(transport=httpx.MockTransport(handler), debug_file=buf)
+    async with client:
+        with pytest.raises(httpx.ReadTimeout):
+            await client.get("https://api.example.com/slow")
+    out = buf.getvalue()
+    assert "ReadTimeout" in out
+    assert "curl" in out