Refactor client

[skupriienko]

Links:

Jira

Actions:

• Core SDK & Client:

  • Refactor Client to utilize requests.Session for connection pooling, drastically improving performance for sequential requests.
  • Refactor Config into a @dataclass for cleaner configuration state management.
  • Decompose Endpoint._build_url and Client.api_call to resolve cyclomatic complexity (C901), extracting _check_dx_guardrails, _build_csv_url, and telemetry extraction into pure @staticmethods.
  • Define explicit public module interfaces using __all__ in __init__.py to prevent namespace pollution.
  • Centralize HTTP status logging within api_call using standard Python logging, and deprecating legacy custom logging handlers.
  • Implement Graceful Degradation for legacy kwargs (ensure_ascii, data_encoding) and utility functions (parse_response), wrapping them in standard DeprecationWarnings instead of breaking the API.
  • Upgrade the timeout parameter to accept tuple[float, float] and float, increasing the default to 60s to better handle heavy API operations.
  • Optimize Memory & Routing Performance: Implement __slots__ across Client, Config, and Endpoint, and introduce an instance-level _endpoint_cache, resulting in a ~50x speedup for endpoint resolution.
  • Optimize Allocations: Replace dynamic header generation with types.MappingProxyType (_JSON_HEADERS, _TEXT_HEADERS) and move urllib3.util.retry.Retry to a ClassVar.
  • Optimize Cold Boot: Replace slow Regex (re.match) with native string manipulation (.split()) in mailjet_rest/utils/version.py to improve SDK import time.
  • IDE Autocompletion: Override __dir__ in the core Client to expose high-traffic dynamic endpoints directly to IDE IntelliSense.

• Security & Developer Experience (DX):

  • Mitigate Path Traversal (CWE-22) by strictly applying urllib.parse.quote to dynamically injected id and action_id path parameters.
  • Mitigate Cleartext Transmission (CWE-319) by validating the https scheme and requiring a valid hostname during Config initialization.
  • Prevent HTTP Header/CRLF Injection (CWE-113) by explicitly scanning headers and Bearer tokens for newline characters using fast native string matching.
  • Mitigate Infinite Blocking (CWE-400): Deprecate passing timeout=None, emitting a warning that explicit timeouts will be enforced in v2.0.
  • Mitigate Open Redirects (CWE-601): Hard-disable automatic redirects (allow_redirects=False) for all API calls.
  • Implement PEP 578 Audit Hooks: Emit sys.audit events for outbound network egress and explicit warnings if TLS verification is disabled.
  • Add DX Guardrails to emit logger.warning events when detecting ambiguous routing (e.g., using singular /template in Content API v1 or routing Send API outside of v3/v3.1).
  • Implement Graceful Degradation for legacy HTTP exceptions (AuthorizationError, ActionDeniedError, etc.), restoring them to preserve 100% backward compatibility for existing try/except blocks.
  • Integrate Smart Telemetry to automatically extract Mailjet Trace IDs (CustomID, Campaign, TemplateID) from payloads and inject them into debug logs.

• Unit & Integration Tests:

  • Delete the monolithic test.py and segregate tests into tests/unit/ (offline mocked tests) and tests/integration/ (live network tests).
  • Migrate legacy unittest classes to modern pytest fixtures, refactoring assertions into the AAA (Arrange, Act, Assert) pattern.
  • Implement comprehensive offline mock tests for internal routing, CSV endpoints, and DX guardrail branches.
  • Implement full Template lifecycle integration tests for both Email API (v3) and Content API (v1), ensuring clean teardown via try/finally.
  • Verify real multipart upload behavior for Content API images.
  • Add comprehensive unit tests for legacy deprecations (test_legacy_deprecations.py) and context manager lifecycle.
  • Add Performance Test Suite: Introduce tests/test_perf.py (via pytest-benchmark) for micro-benchmarking routing overhead, and tests/test_boot.py (via cProfile) for tracking cold-boot initialization costs.

• CI/CD, Linting & Repository Management:

  • Consolidate tooling by migrating completely to Ruff as the single source of truth for formatting and linting, purging legacy tools (Black, Flake8, Pylint, Pydocstyle) from pyproject.toml and environments.
  • Update GitHub Actions to utilize pip caching, verify compiled .whl artifacts using twine check, and expand the testing matrix to include Python 3.14.
  • Update .github/dependabot.yml to group minor/patch updates and scan GitHub Actions.
  • Add explicit test-unit and test-integration targets to the Makefile.
  • Align environment-dev.yaml strictly with pyproject.toml and add typing-extensions for robust cross-version type hinting (<3.11).
  • Introduce Universal Management Script: Add manage.sh to centralize and simplify running formatters, linters, benchmark comparisons, and security audits (osv-scanner, pip-audit).

• Documentation & Samples:

  • Update SECURITY.md to reflect exclusive support for the active branch and forbid reporting CVEs via public issues.
  • Update README.md with new Logging & Debugging guides, updated Python compatibility (3.10-3.14), and modern Content API multipart upload examples.
  • Refresh all files in samples/ to safely fetch credentials using os.environ.get().
  • Update CHANGELOG.md with detailed sections for Security, Performance, Additions, Deprecations, and Fixes.
  • Consolidate legacy smoke tests into an executable samples/smoke_readme_runner.py to dynamically test all README examples.
  • Create PERFORMANCE.md: Document the architectural optimizations (__slots__, Caching, MappingProxyType) and baseline metrics (routing speed down to ~152ns).