Add request/response debug logging

[isaacCodes1]

Overview

This PR adds request/response debug logging to the Shade Python SDK so developers can troubleshoot integration issues with visibility into outgoing requests and incoming responses. It introduces ShadeClient with a debug flag, a global config.debug setting, and structured logging.DEBUG output under the shade logger with sensitive values masked.

Related Issue

Closes #13

Changes

🔍 Debug Logging System

• [ADD] src/shade/client.py

• Added ShadeClient with debug: bool = False and an HTTP request() method.

• Emits debug logs for outgoing requests (method, URL, headers, body) and incoming responses (status, headers, body) when debug mode is enabled.

• Supports both per-client debug=True and global config.debug = True.

• [ADD] src/shade/_debug.py

• Added helpers to mask Authorization header values (only last 4 characters visible).

• Added response body truncation at 2000 characters with a [truncated] suffix.

• Added structured request/response logging via Python's logging module at DEBUG level under the shade logger.

• [ADD] src/shade/config.py

• Added global SDK configuration with debug: bool = False.

• [MODIFY] src/shade/__init__.py

• Exported ShadeClient and config from the public API.

🧪 Tests

• [ADD] tests/test_debug_logging.py

• Added tests for authorization header masking.

• Added tests for response body truncation.

• Added tests verifying debug logs are emitted when debug=True.

• Added tests verifying no request/response content is logged when debug=False.

• Added tests verifying global config.debug enables logging.

• [MODIFY] tests/test_gateway.py

• Removed unused pytest import.

🔧 Dependencies

• [MODIFY] pyproject.toml

• Added httpx as an HTTP client dependency for ShadeClient.

• [MODIFY] poetry.lock

• Updated lockfile for the new httpx dependency.

Verification Results

poetry run pytest -v ✅ passed (10/10)
poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics ✅ passed

Acceptance Criteria	Status
With debug=True, each request logs method, URL, and masked headers	✅
Each response logs status code and truncated body	✅
Authorization header value is always masked in logs	✅
With debug=False (default), no request/response content is logged	✅
Logs use logging.DEBUG level under the shade logger	✅
Response bodies longer than 2000 characters are truncated with [truncated]	✅

Summary by CodeRabbit

• New Features
  • Added a ShadeClient for API requests with configurable base URL, context-manager support, and optional debug logging.
  • Introduced global SDK debug configuration (shade.config.debug) and exported it at the package level.
• Bug Fixes
  • Improved debug logging to safely mask authorization details and truncate large request/response bodies.
• Tests
  • Added coverage for redaction, truncation, and verifying debug logging behavior on/off.
• Chores
  • Added the httpx runtime dependency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ef8dd4de-718b-47f1-b018-f16224155095

📥 Commits

Reviewing files that changed from the base of the PR and between 7e048a4 and 0f7b282.

📒 Files selected for processing (2)

• src/shade/__init__.py
• src/shade/config.py

🚧 Files skipped from review as they are similar to previous changes (2)

• src/shade/init.py
• src/shade/config.py

---

📝 Walkthrough

Walkthrough

Adds httpx, exports ShadeClient and config, introduces debug logging helpers, implements ShadeClient request/response logging with masking and truncation, and adds tests for redaction, truncation, and debug behavior.

Changes

Request/response debug logging

Layer / File(s)	Summary
Public API and dependency wiring pyproject.toml, src/shade/config.py, src/shade/__init__.py	httpx is added, config.debug is defined, and ShadeClient plus config are exported from shade.
Debug logging helpers src/shade/_debug.py	Adds the shade logger setup, authorization masking, body truncation, body normalization, and request and response debug emitters.
Client request flow src/shade/client.py	Adds ShadeClient initialization, context-manager lifecycle, default authorization headers, and debug-aware request execution.
Debug logging tests tests/test_debug_logging.py, tests/test_gateway.py	Covers header redaction, body truncation, debug logging on and off, global debug overrides, truncated response bodies, and a small import cleanup.

Sequence Diagram(s)

sequenceDiagram
  participant ShadeClient
  participant shade._debug.log_request
  participant httpx.Client
  participant shade._debug.log_response
  participant logger

  ShadeClient->>shade._debug.log_request: log_request(method, url, masked headers, body)
  ShadeClient->>httpx.Client: request(method, url, headers, json, content)
  httpx.Client-->>ShadeClient: httpx.Response
  ShadeClient->>shade._debug.log_response: log_response(status_code, masked headers, body)
  shade._debug.log_request->>logger: logger.debug(message)
  shade._debug.log_response->>logger: logger.debug(message)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

I hopped through logs at dusk so sweet,
with masked-up bytes and carrot feet.
Long bodies shrank; the shade grew clear,
while tiny debug bells rang near.
Hop hop, the client now speaks neat. 🐰

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 3.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding request/response debug logging.
Description check	✅ Passed	It includes the summary, linked issue, dependencies, tests, and verification, though the template's type/checklist sections are omitted.
Linked Issues check	✅ Passed	The changes implement the requested debug mode, masking, truncation, global config, and DEBUG-level logging for issue #13.
Out of Scope Changes check	✅ Passed	The added dependency and test cleanup are directly related to the logging feature and do not appear out of scope.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/shade/client.py`:
- Line 50: The URL composition in Client should normalize the path before
joining it with base_url, because using a raw path can produce invalid URLs when
the path is missing a leading slash. Update the logic around the url assignment
in Client to ensure path is normalized consistently before concatenation, and
keep the fix localized to the URL-building code in this method.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: add01f4d-79ca-40d3-9a34-a54efac4e31e

📥 Commits

Reviewing files that changed from the base of the PR and between f6a4cff and 14164f4.

⛔ Files ignored due to path filters (1)

• poetry.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• pyproject.toml
• src/shade/__init__.py
• src/shade/_debug.py
• src/shade/client.py
• src/shade/config.py
• tests/test_debug_logging.py
• tests/test_gateway.py