protocol-design

Guide Python typing.Protocol usage for structural subtyping and interface design.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/101mare/skill-library --skill protocol-design-101mare
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: protocol-design
Source: https://github.com/101mare/skill-library/tree/main/skills/patterns/protocol-design
Command: npx skills add https://github.com/101mare/skill-library --skill protocol-design-101mare

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps developers properly define and utilize Python's typing.Protocol for robust interface design and structural subtyping, avoiding common pitfalls and promoting testable code.

Core Features & Use Cases

  • Interface Definition: Define contracts between modules using structural subtyping (duck typing) without requiring inheritance.
  • Protocol vs ABC: Clearly understand when to use Protocol versus Abstract Base Classes (ABC).
  • Runtime Checking: Learn the nuances and limitations of @runtime_checkable.
  • Mocking: Effectively use Mock(spec=Protocol) for type-safe testing.
  • Use Case: When designing a system where different components need to interact through a common set of methods (e.g., various notification services), Protocol ensures they adhere to the contract without forcing a shared inheritance hierarchy.

Quick Start

Use the protocol-design skill to understand how to define a Python typing.Protocol for a data repository interface.

Frequently Asked Questions about protocol-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I use Python typing.Protocol for structural subtyping and interface design?

Python typing.Protocol enables structural subtyping for interface design by allowing you to define contracts between modules using duck typing without requiring shared inheritance hierarchies.

What is the difference between Python Protocol and Abstract Base Classes (ABCs)?

Python Protocol uses structural subtyping to define interfaces without forcing inheritance, whereas Abstract Base Classes (ABCs) require explicit inheritance to enforce interface contracts across components.

Does @runtime_checkable work for validating Python Protocol implementations?

@runtime_checkable allows runtime instance checks for Python Protocol implementations, but it only verifies method presence and not their type signatures, presenting notable limitations for robust validation.

Can I use Mock with Python Protocol for type-safe testing?

Yes, you can use Mock(spec=Protocol) in Python to ensure type-safe testing, allowing your test suites to accurately mock structural subtyping interfaces without explicit inheritance.

How do I compose multiple Python Protocols into a single interface?

You can compose multiple Python Protocols by combining them, creating a single unified interface that enforces the combined structural subtyping contracts across your application components.

When should I not use Python typing.Protocol for interface definition?

You should avoid Python typing.Protocol when you need strict nominal subtyping or runtime method signature validation, as Protocol primarily supports structural duck typing without deep signature enforcement.