Improve client, update & fix tests

[skupriienko]

Links:

Jira

Actions:

• Core SDK & Client:

  • Explicit __all__ declaration in mailgun.client to cleanly isolate the public API namespace.
  • A __repr__ method to the Client class to improve developer experience (DX) during console debugging.
  • Overrode __dir__ in Client and AsyncClient to expose dynamic endpoint routes directly to IDE autocompletion engines (VS Code, PyCharm).
  • Security guardrail (CWE-319) in Config that logs a warning if a cleartext http:// API URL is configured.
  • Implemented Smart Logging (telemetry) in Client and AsyncClient to help users debug API requests, generated URLs, and server errors (404, 400, 429).
  • Added build_path_from_keys utility in mailgun.handlers.utils to centralize and dry up URL path generation across handlers.
  • Refactored the Config routing engine to use a deterministic, data-driven approach (EXACT_ROUTES and PREFIX_ROUTES).
  • Improved dynamic API version resolution to gracefully switch between v1, v2, v3, v4, and v5 without hardcoded logic.
  • Added advanced path interpolation in handle_default to automatically inject inline URL parameters (e.g., /v2/x509/{domain}/status).
  • Enabled native dynamic routing support for Mailgun Optimize, Validations Service, and Email Preview APIs out-of-the-box, without requiring new custom handlers.
  • Fixed API versioning collisions in DOMAIN_ENDPOINTS (e.g., ensuring tracking resolves to v3 instead of v1) and corrected the credentials route prefix.
  • Secured internal configuration registries by wrapping them in MappingProxyType to prevent accidental mutations of the client state.
  • Broadened type hints for files (Any | None) and timeout (int | float | tuple) to fully support requests/httpx capabilities without triggering false positives in strict IDEs.
  • Refactored api_call exception blocks to use the else clause for successful returns, adhering to strict Ruff (TRY300) standards.
  • Fixed a silent data loss bug in create() where custom headers passed by the user were ignored instead of being merged.
  • Fixed a kwargs collision bug in update() by using .pop("headers") instead of .get() to prevent passing duplicate keyword arguments.
  • Preserved original tracebacks (PEP 3134) by properly chaining TimeoutError and ApiError using from e.
  • Mitigated a log-flooding vulnerability (OWASP CWE-532) by safely truncating massive HTML error responses to 500 characters.
  • Replaced a fragile try/except TypeError status code check with robust getattr and isinstance validation to prevent masking unrelated exceptions.

• Integration Tests:

  • Fixed flaky integration tests failing with 429 Too Many Requests and state-sharing collisions.
  • Created an intelligent live meta-testing suite (test_routing_meta_live.py) to strictly verify SDK endpoint aliases and URL construction against live Mailgun Nginx servers.
  • Extended smoke_test.py to prove cross-version dynamic routing (e.g., seamlessly switching to v4 for address validation).

• Unit Tests:

  • Migrated the fragmented linting and formatting pipeline (Flake8, Black, Pylint, Pyupgrade, etc.) to a unified, high-performance ruff setup in .pre-commit-config.yaml.
  • Cleaned up obsolete unit tests that conflicted with the new forgiving dynamic "Catch-All" routing architecture.

• Documentation & Repository Management:

  • Enabled pip dependency caching in GitHub Actions to drastically speed up CI workflows.
  • Added Python 3.14 support to the GitHub Actions test matrix.
  • Added a new "Logging & Debugging" section to README.md.
  • Updated README.md with new documentation and code examples for the Validations & Optimize APIs.
  • Updated CHANGELOG.md to reflect the dynamic routing expansion and path interpolation.

Verification & Testing:

To verify these changes locally, ensure your environment variables (APIKEY and DOMAIN, and others) are set, then run the following commands:

1. Run the Unit Test Suite (Fast):
Validates the core routing logic, data structures, and mock handlers.

pytest tests/unit/ -v

2. Run the Live Routing Meta-Test (No state mutation):
Proves the SDK correctly constructs URLs for all ~30 supported endpoints by hitting live Mailgun servers (expects 200, 400, 401, or 403 responses; tests fail if the Python SDK crashes or generates a 404 bad route).

pytest tests/integration/test_routing_meta_live.py -v -s

3. Run the Full Integration Suite (State mutation):
Executes end-to-end flows against your Sandbox domain (creates/deletes real resources).

pytest tests/integration/tests.py -v

4. Execute the Interactive Smoke Test:
Runs the executable documentation script demonstrating cross-version routing and payload serialization.

python mailgun/examples/smoke_test.py