Skip to content

feat(typing): add strict .pyi stubs, stateful Hypothesis rules, and mutation gates - #177

Draft
skupriienko wants to merge 1 commit into
wave-4-builders-semverfrom
wave-5-typing-stateful-tests
Draft

skupriienko wants to merge 1 commit into
wave-4-builders-semverfrom
wave-5-typing-stateful-tests

Conversation

@skupriienko

@skupriienko skupriienko commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Stack (v1.9.2 Hardening Rollout)

Wave PR Base <- Head Scope
Wave 1 #173 master <- wave-1-tooling-hygiene CRIT-03, CRIT-04, CRIT-05, HIGH-06
Wave 2 #174 wave-1-tooling-hygiene <- wave-2-transport-redaction CRIT-01, CRIT-02, HIGH-01 (lock), HIGH-02, HIGH-03, HIGH-04 (path), OPT-09
Wave 3 #175 wave-2-transport-redaction <- wave-3-boot-slots-pooling OPT-01..OPT-07, OPT-10, OPT-11, HIGH-01 (warn_unclosed)
Wave 4 #176 wave-3-boot-slots-pooling <- wave-4-builders-semver HIGH-04 (bool/stream), HIGH-05, HIGH-07, OPT-08
-> Wave 5 (This PR) #177 wave-4-builders-semver <- wave-5-typing-stateful-tests MOD-02, MOD-04

Merge in order: #173 -> #174 -> #175 -> #176 -> #177.

Note

Stacked PR workflow note: ClusterFuzzLite PR fuzzing runs immediately on all PRs. Workflows scoped to branches: [master] (CI, PR Validation, Continuous Security Verification, CodeQL) trigger automatically as parent PRs merge into master and GitHub retargets this PR's base branch to master.


Summary

Wave 5 of 5 for v1.9.2 (stacked on #176 / wave-4-builders-semver). Ships deterministic PEP 561 .pyi type stubs (client.pyi, endpoint.pyi) verified by a zero-subprocess AST stub checker (scripts/check_stubs.py --check), wires stub and wheel checks into CI (commit_checks.yaml, publish.yml, MANIFEST.in), expands stateful Hypothesis RuleBasedStateMachine builder tests, and configures mutmut with targeted unit tests reaching 81.57% killed mutants (1270/1557).


Actions

  • PEP 561 Type Stubs & Zero-Subprocess AST Checker (mailjet_rest/client.pyi, mailjet_rest/endpoint.pyi, scripts/check_stubs.py, MANIFEST.in, pyproject.toml, MOD-02):
    • Generated explicit typed route attributes on Client for all 111 ROUTES_REGISTRY endpoints alongside typed Endpoint methods (get, create, update, delete, stream, get_many, id).
    • Added deterministic AST-based scripts/check_stubs.py --check verification (no subprocess calls) and included .pyi stubs in source/wheel distributions.
  • CI & Wheel Packaging Stub Gates (.github/workflows/commit_checks.yaml, .github/workflows/publish.yml, manage.sh, MOD-02):
    • Wired python scripts/check_stubs.py --check into commit_checks.yaml and manage.sh, and verified .pyi + py.typed files inside built wheels in publish.yml.
  • Stateful Hypothesis & Mutation Testing (tests/property/test_builder_state.py, tests/unit/test_stubs.py, tests/unit/test_wave5_mutation_coverage.py, tests/unit/test_wave2_security.py, MOD-04):
    • Expanded Hypothesis RuleBasedStateMachine rules covering MessageBuilder and SendPayloadBuilder invariants.
    • Added stub synchronization unit tests (tests/unit/test_stubs.py) and mutation-killing unit coverage (tests/unit/test_wave5_mutation_coverage.py) reaching 81.57% (1270/1557 killed, 285 survived, 2 timeout, 0 no tests across builders.py, endpoint.py, utils/transport_security.py, and utils/version.py).

Verification & Testing

  • pytest -n auto -W error --cov=mailjet_rest --cov-fail-under=80 tests/unit tests/property tests/regression: 276 passed, 94.94% coverage.
  • mutmut run / mutmut results --all true: 1270/1557 killed (81.57%) (builders 78.75%, endpoint 83.72%, transport_security 86.43%, version 85.71%).
  • Static, security & packaging gates: ruff check ., ruff format --check ., python scripts/check_stubs.py --check, mypy --strict mailjet_rest (13 files, 0 issues), pyright mailjet_rest (0 errors), slotscheck -m mailjet_rest (13 modules, 30 classes OK), bandit -c pyproject.toml -r mailjet_rest (0 issues), zizmor .github/workflows/ (0 findings), pip-audit --skip-editable (0 vulnerabilities), python tests/test_boot.py (0.544s cProfile / 0.8364s wall), pytest -q tests/test_perf.py (6 passed), python -m build --no-isolation + twine check dist/* (PASSED with .pyi + py.typed verified in wheel).
  • Live Mailjet API network tests (pytest -m network, samples/smoke_readme_runner.py) were skipped locally due to absent MJ_APIKEY_PUBLIC / MJ_APIKEY_PRIVATE credentials.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant