Skip to content

chore: harden Protocol contract checks#138

Open
QuantumGhost wants to merge 7 commits into
langgenius:mainfrom
QuantumGhost:type/static-assertion
Open

chore: harden Protocol contract checks#138
QuantumGhost wants to merge 7 commits into
langgenius:mainfrom
QuantumGhost:type/static-assertion

Conversation

@QuantumGhost
Copy link
Copy Markdown
Contributor

@QuantumGhost QuantumGhost commented May 13, 2026

AI disclosure: This PR was primarily drafted with Codex using GPT-5.5.
I have reviewed and edited the final diff, and I am responsible for the content.

Important

  1. Make sure you have read our contribution guidelines
  2. Search existing issues and pull requests to confirm this change is not a duplicate
  3. Open or identify the issue this pull request resolves or advances
  4. Use a Conventional Commits title for this pull request, and mark breaking changes with !
  5. Remember that the pull request title will become the squash merge commit message
  6. If CLA Assistant prompts you, sign CLA.md in the pull request conversation

Related Issue

Closes #136

Summary

This PR hardens protocol contracts by:

  1. Preventing nominal subclasses from inadvertently becoming instantiable unless they explicitly override the protocol methods.
  2. Statically checking all in-source protocol implementations.

Changes included:

  • Marks protocol methods as abstract.
  • Adds colocated *_type_contract.py static assertions for in-repository protocol implementations.
  • Adds regression tests for abstract protocol methods.
  • Excludes *_type_contract.py files from published distributions.
  • Documents the development-only role of static type contract files.

Validation performed:

  • make check
  • uv run pytest
  • uv build --out-dir /tmp/graphon-dist.FoJno3
  • Inspected the generated wheel and sdist to confirm no *_type_contract.py files are included.

Checklist

  • This pull request links the issue it resolves or advances
  • This pull request title follows Conventional Commits, and any breaking change is marked with !
  • If CLA Assistant prompted me, I signed CLA.md in the pull request conversation

Exclude static type contract modules from published distributions and document their development-only role.

Add tests that ensure Protocol methods remain abstract enough to reject indirect nominal implementations without overrides.

Assisted-by: Codex:GPT-5.4
Replace the hand-maintained Protocol list with AST-based discovery over graphon modules so new Protocol definitions are automatically covered.

Assisted-by: Codex:GPT-5.4
@QuantumGhost
Copy link
Copy Markdown
Contributor Author

Updated the protocol regression tests to follow the AST-based discovery approach from the previous PR reference.

Changes:

  • Replaced the hand-maintained Protocol list with automatic discovery under src/graphon.
  • Kept coverage for direct subclasses without overrides.
  • Added coverage for indirect subclasses without overrides and indirect partial overrides.

Validation:

  • make check
  • uv run pytest

Remove type contract files where the implementation already subclasses the Protocol directly, and document that type contracts are intended for structural implementations.

Assisted-by: Codex:GPT-5.4
@QuantumGhost
Copy link
Copy Markdown
Contributor Author

Adjusted the static type contract scope based on review feedback.

Changes:

  • Removed files for implementations that already directly subclass their target Protocol, such as .
  • Kept structural contracts where the implementation does not nominally inherit the target Protocol.
  • For mixed files, retained only the structural assertions.
  • Updated CONTRIBUTING.md to document that type contract files are for structural protocol implementations.

Validation:

  • make check
  • uv run pytest

@QuantumGhost
Copy link
Copy Markdown
Contributor Author

Adjusted the static type contract scope based on review feedback.

Changes:

  • Removed *_type_contract.py files for implementations that already directly subclass their target Protocol, such as HttpxHttpClient(HttpClientProtocol).
  • Kept structural contracts where the implementation does not nominally inherit the target Protocol.
  • For mixed files, retained only the structural assertions.
  • Updated CONTRIBUTING.md to document that type contract files are for structural protocol implementations.

Validation:

  • make check
  • uv run pytest

@QuantumGhost QuantumGhost marked this pull request as ready for review May 13, 2026 16:28
@dosubot dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label May 13, 2026
Keep the Protocol contract test focused on member abstractness, document the non-empty member guard, and remove direct/indirect instantiation checks.

Assisted-by: Codex:GPT-5.4
@QuantumGhost
Copy link
Copy Markdown
Contributor Author

Updated the protocol abstract contract test per review feedback.

Changes:

  • Added an inline comment explaining why the non-empty member assertion exists.
  • Removed the direct and indirect instantiation checks.
  • Kept the test focused on verifying Protocol members are declared abstract.

Validation:

  • make check
  • uv run pytest

@QuantumGhost QuantumGhost enabled auto-merge (squash) May 13, 2026 16:33
@QuantumGhost QuantumGhost disabled auto-merge May 13, 2026 16:35
@QuantumGhost QuantumGhost enabled auto-merge (squash) May 13, 2026 16:36
@WH-2099 WH-2099 self-assigned this May 15, 2026
@WH-2099 WH-2099 self-requested a review May 15, 2026 08:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Harden Protocol contracts with abstract methods and regression checks

2 participants