httpx-debug 0.1.0__py3-none-any.whl

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/_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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+httpx_debug/__init__.py,sha256=jodJv2IpcOYTgOr0OCxnpWmTQ-gBlsVnbWn498LqWkg,328
+httpx_debug/_clipboard.py,sha256=h9gQ3zu5mrMqmg0gRFovithx5YEfzlUKBqTqTOntJ2M,1951
+httpx_debug/_curl.py,sha256=FvmD7Eam2SAhGV-iome03izJCopftzxy9XFqv0Onyfo,2228
+httpx_debug/_hooks.py,sha256=Flgi5OfjJUf08Fe7EWGTpM_SZs9T927zla4WsATEek4,4925
+httpx_debug-0.1.0.dist-info/METADATA,sha256=K2X4RIF9YbzNzIjEqBB1vw9dkrCUCZkboVprD3QOUzM,5483
+httpx_debug-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+httpx_debug-0.1.0.dist-info/licenses/LICENSE,sha256=RFWd3lWPIDAthIAm9tYEbLpsSJVKWFCjXPhrblnH4Bk,1068
+httpx_debug-0.1.0.dist-info/RECORD,,

httpx_debug-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

httpx_debug-0.1.0.dist-info/licenses/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.