Add Protocols example

Author: adewale

CHANGELOG.md

@@ -25,6 +25,7 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0
 - `iterators` and `generator-expressions` examples to make the Iteration arc explicit.
 - Syntax coverage examples for loop control, loop `else`, assertions, deletion, scope rebinding, positional-only parameters, assignment expressions, `yield from`, exception chaining/groups, advanced match patterns, inheritance, metaclasses, async iteration/context managers, import aliases, and specialized operators/literals.
 - Optional `see_also` example graph links with validation tests.
+- `Protocol` example covering structural typing and its boundary with inheritance.
 
 ### Changed
 

README.md

@@ -6,7 +6,7 @@ Production: <https://www.pythonbyexample.dev> (`workers.dev` remains enabled as
 
 ## Features
 
-- 69 curated Python 3.13 examples in learning order
+- 70 curated Python 3.13 examples in learning order
 - Literate source/output cells for each example walkthrough
 - Editable complete examples powered by CodeMirror
 - Read-only syntax highlighting powered by Shiki

src/asset_manifest.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.06e133dcde6a.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '6dd0b780fadd'
+HTML_CACHE_VERSION = '002f150145c0'

src/example_sources/manifest.toml

@@ -63,6 +63,7 @@ order = [
   "modules",
   "import-aliases",
   "type-hints",
+  "protocols",
   "enums",
   "regular-expressions",
   "number-parsing",

src/example_sources/protocols.md

@@ -0,0 +1,100 @@
++++
+slug = "protocols"
+title = "Protocols"
+section = "Types"
+summary = "Protocol describes required behavior for structural typing."
+doc_path = "/library/typing.html#typing.Protocol"
+see_also = [
+  "type-hints",
+  "classes",
+  "inheritance-and-super",
+]
++++
+
+`Protocol` describes the methods or attributes an object must provide. It exists for structural typing: if an object has the right shape, type checkers can treat it as compatible.
+
+This is different from inheritance. Inheritance says a class is explicitly derived from a parent; a protocol says callers only need a particular behavior.
+
+At runtime, ordinary method lookup still applies. Protocols are mainly for static analysis, documentation, and API boundaries.
+
+:::program
+```python
+from typing import Protocol
+
+class Greeter(Protocol):
+    def greet(self) -> str:
+        ...
+
+class Person:
+    def __init__(self, name):
+        self.name = name
+
+    def greet(self):
+        return f"hello {self.name}"
+
+
+def welcome(greeter: Greeter):
+    print(greeter.greet())
+
+welcome(Person("Ada"))
+print(Greeter.__name__)
+```
+:::
+
+:::cell
+A protocol names required behavior. The ellipsis marks the method body as intentionally unspecified, similar to an interface declaration.
+
+```python
+from typing import Protocol
+
+class Greeter(Protocol):
+    def greet(self) -> str:
+        ...
+
+print(Greeter.__name__)
+```
+
+```output
+Greeter
+```
+:::
+
+:::cell
+A class can satisfy the protocol without inheriting from it. `Person` has a compatible `greet()` method, so it has the right shape for static type checkers.
+
+```python
+class Person:
+    def __init__(self, name):
+        self.name = name
+
+    def greet(self):
+        return f"hello {self.name}"
+
+print(Person("Ada").greet())
+```
+
+```output
+hello Ada
+```
+:::
+
+:::cell
+Use the protocol as an annotation at the API boundary. The function only cares that the object can greet; it does not care about the concrete class.
+
+```python
+def welcome(greeter: Greeter):
+    print(greeter.greet())
+
+welcome(Person("Ada"))
+```
+
+```output
+hello Ada
+```
+:::
+
+:::note
+- Protocols are for structural typing: compatibility by shape rather than explicit inheritance.
+- Type checkers understand protocols; normal runtime method calls still do the work.
+- Prefer inheritance when shared implementation matters, and protocols when only required behavior matters.
+:::

src/example_sources_data.py

@@ -2526,6 +2526,63 @@
              'code': 'def label(score: int) -> str:\n    return f"score={score}"\n\nprint(label("high"))',
              'output': 'score=high',
              'line': 44}]},
+ {'slug': 'protocols',
+  'title': 'Protocols',
+  'section': 'Types',
+  'summary': 'Protocol describes required behavior for structural typing.',
+  'doc_url': 'https://docs.python.org/3.13/library/typing.html#typing.Protocol',
+  'code': 'from typing import Protocol\n'
+          '\n'
+          'class Greeter(Protocol):\n'
+          '    def greet(self) -> str:\n'
+          '        ...\n'
+          '\n'
+          'class Person:\n'
+          '    def __init__(self, name):\n'
+          '        self.name = name\n'
+          '\n'
+          '    def greet(self):\n'
+          '        return f"hello {self.name}"\n'
+          '\n'
+          '\n'
+          'def welcome(greeter: Greeter):\n'
+          '    print(greeter.greet())\n'
+          '\n'
+          'welcome(Person("Ada"))\n'
+          'print(Greeter.__name__)\n',
+  'expected_output': 'hello Ada\nGreeter\n',
+  'notes': ['Protocols are for structural typing: compatibility by shape rather than explicit inheritance.',
+            'Type checkers understand protocols; normal runtime method calls still do the work.',
+            'Prefer inheritance when shared implementation matters, and protocols when only required behavior '
+            'matters.'],
+  'cells': [{'prose': ['A protocol names required behavior. The ellipsis marks the method body as intentionally '
+                       'unspecified, similar to an interface declaration.'],
+             'code': 'from typing import Protocol\n'
+                     '\n'
+                     'class Greeter(Protocol):\n'
+                     '    def greet(self) -> str:\n'
+                     '        ...\n'
+                     '\n'
+                     'print(Greeter.__name__)',
+             'output': 'Greeter',
+             'line': 22},
+            {'prose': ['A class can satisfy the protocol without inheriting from it. `Person` has a compatible '
+                       '`greet()` method, so it has the right shape for static type checkers.'],
+             'code': 'class Person:\n'
+                     '    def __init__(self, name):\n'
+                     '        self.name = name\n'
+                     '\n'
+                     '    def greet(self):\n'
+                     '        return f"hello {self.name}"\n'
+                     '\n'
+                     'print(Person("Ada").greet())',
+             'output': 'hello Ada',
+             'line': 40},
+            {'prose': ['Use the protocol as an annotation at the API boundary. The function only cares that the object '
+                       'can greet; it does not care about the concrete class.'],
+             'code': 'def welcome(greeter: Greeter):\n    print(greeter.greet())\n\nwelcome(Person("Ada"))',
+             'output': 'hello Ada',
+             'line': 59}]},
  {'slug': 'enums',
   'title': 'Enums',
   'section': 'Types',

tests/fixtures/golden_examples.py

@@ -112,6 +112,7 @@ def test_language_surface_has_good_initial_coverage(self):
             "inheritance-and-super",
             "metaclasses",
             "type-hints",
+            "protocols",
             "enums",
             "json",
             "assertions",
@@ -177,6 +178,7 @@ def test_syntax_surface_has_explicit_examples(self):
             "pattern = r\"\\d+\"",
             "data = b\"py\"",
             "number = 2 + 3j",
+            "class Greeter(Protocol):",
             "print(Scale(2) @ Scale(3))",
             "print(...)",
         ]