docs: hold the docs' test prose to the same typography rule

- The plain-ASCII check in tests/docs_src/test_shape.py now covers the
  test modules in tests/docs_src/ as well as the pages and examples, and
  their docstrings and comments are rewritten to satisfy it. The check's
  own table of banned characters is spelled as escapes so the file
  passes the check it implements.
- The invalid-`mode=` hint in Client.__post_init__ was the one
  user-facing string in src/mcp with a typographic dash, and
  docs/client/protocol-versions.md quotes that error verbatim. It now
  uses a semicolon; the two tests that pin the message are updated.
- testing.md's note on pytest and inline-snapshot no longer speaks in
  the first person, and two test docstrings now state the invariant they
  pin.

Author: maxisbey

docs/tutorial/testing.md

@@ -27,12 +27,11 @@ To run the test below you'll need two extra (development) dependencies:
     ```
 
 !!! info
-    I think [`pytest`](https://docs.pytest.org/en/stable/) is a pretty standard testing framework,
-    so I won't go into details here.
+    These docs assume you already know [`pytest`](https://docs.pytest.org/en/stable/).
 
-    [`inline-snapshot`](https://15r10nk.github.io/inline-snapshot/latest/) is a library that lets you
-    take snapshots of the output of your tests, which makes it much easier to write tests for your
-    server. You don't need to use it, but we are spreading the word for best practices.
+    [`inline-snapshot`](https://15r10nk.github.io/inline-snapshot/latest/) is optional: it records
+    the output of a test as the `snapshot(...)` literal you see below, which makes a test that
+    asserts on a whole result object much faster to write. A plain `assert` works too.
 
 Now the test:
 

src/mcp/client/client.py

@@ -207,7 +207,7 @@ async def main():
     def __post_init__(self) -> None:
         if self.mode not in ("legacy", "auto") and self.mode not in MODERN_PROTOCOL_VERSIONS:
             hint = (
-                f" ({self.mode!r} is a handshake-era version — use mode='legacy')"
+                f" ({self.mode!r} is a handshake-era version; use mode='legacy')"
                 if self.mode in HANDSHAKE_PROTOCOL_VERSIONS
                 else ""
             )

tests/client/test_client.py

@@ -477,7 +477,7 @@ def test_client_rejects_handshake_era_mode_at_construction() -> None:
     `__post_init__` with a hint to use `mode='legacy'` — the version-pin path is
     modern-only."""
     server = MCPServer("test")
-    with pytest.raises(ValueError, match=r"handshake-era version — use mode='legacy'"):
+    with pytest.raises(ValueError, match=r"handshake-era version; use mode='legacy'"):
         Client(server, mode="2025-06-18")
     with pytest.raises(ValueError, match=r"mode must be 'legacy', 'auto', or one of"):
         Client(server, mode="not-a-version")

tests/docs_src/test_asgi.py

@@ -1,4 +1,4 @@
-"""`docs/run/asgi.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/run/asgi.md`: every claim the page makes, proved against the real SDK."""
 
 import inspect
 
@@ -151,7 +151,7 @@ async def test_custom_route_lands_next_to_the_mcp_endpoint() -> None:
 
 
 async def test_the_health_check_answers_outside_the_protocol() -> None:
-    """tutorial006: `GET /health` is ordinary HTTP — no session manager, no MCP."""
+    """tutorial006: `GET /health` is ordinary HTTP, with no session manager and no MCP."""
     transport = httpx.ASGITransport(app=tutorial006.app)
     async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1") as http:
         response = await http.get("/health")

tests/docs_src/test_authorization.py

@@ -1,4 +1,4 @@
-"""`docs/advanced/authorization.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/advanced/authorization.md`: every claim the page makes, proved against the real SDK."""
 
 import httpx
 import pytest

tests/docs_src/test_client.py

@@ -1,4 +1,4 @@
-"""`docs/client/index.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/client/index.md`: every claim the page makes, proved against the real SDK."""
 
 import pytest
 from inline_snapshot import snapshot
@@ -35,7 +35,7 @@ async def test_connected_properties_are_populated_inside_the_block() -> None:
 
 
 async def test_a_client_is_not_reusable_after_the_block_ends() -> None:
-    """tutorial001: `async with` is the whole lifecycle — construct a new Client per connection."""
+    """tutorial001: `async with` is the whole lifecycle. Construct a new Client per connection."""
     client = Client(tutorial001.mcp)
     async with client:
         assert client.server_info.name == "Bookshop"

tests/docs_src/test_client_callbacks.py

@@ -1,4 +1,4 @@
-"""`docs/client/callbacks.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/client/callbacks.md`: every claim the page makes, proved against the real SDK."""
 
 import pytest
 from inline_snapshot import snapshot
@@ -34,7 +34,7 @@ async def test_the_callback_answers_the_servers_question() -> None:
 
 
 async def test_the_callback_receives_the_servers_question_as_form_params() -> None:
-    """tutorial002: the callback gets `ElicitRequestFormParams` — the message and the requested schema."""
+    """tutorial002: the callback gets `ElicitRequestFormParams` (the message and the requested schema)."""
     received: list[ElicitRequestParams] = []
 
     async def recording(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:

tests/docs_src/test_client_transports.py

@@ -1,4 +1,4 @@
-"""`docs/client/transports.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/client/transports.md`: every claim the page makes, proved against the real SDK."""
 
 import inspect
 
@@ -20,7 +20,7 @@ async def test_the_in_memory_program_on_the_page_runs(capsys: pytest.CaptureFixt
 
 
 async def test_in_memory_client_talks_to_the_server_object() -> None:
-    """tutorial001: passing the server object connects in-process — no subprocess, no port."""
+    """tutorial001: passing the server object connects in-process. No subprocess, no port."""
     async with Client(tutorial001.mcp) as client:
         assert client.server_info.name == "Bookshop"
         assert client.protocol_version == "2026-07-28"

tests/docs_src/test_completions.py

@@ -1,4 +1,4 @@
-"""`docs/tutorial/completions.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/tutorial/completions.md`: every claim the page makes, proved against the real SDK."""
 
 import pytest
 from inline_snapshot import snapshot
@@ -40,7 +40,7 @@ async def test_completing_without_a_handler_is_method_not_found() -> None:
 
 
 async def test_registering_the_handler_advertises_the_capability() -> None:
-    """tutorial002: `@mcp.completion()` is the whole declaration — the capability is derived from it."""
+    """tutorial002: `@mcp.completion()` is the whole declaration; the capability is derived from it."""
     async with Client(tutorial002.mcp) as client:
         assert client.server_capabilities.completions == CompletionsCapability()
 
@@ -91,7 +91,7 @@ async def test_the_typed_prefix_still_filters_a_dependent_parameter() -> None:
 
 
 def test_context_arguments_is_optional() -> None:
-    """tutorial003: `context.arguments` is `dict[str, str] | None` — the handler's `None` guard is required."""
+    """tutorial003: `context.arguments` is `dict[str, str] | None`; the handler's `None` guard is required."""
     assert CompletionContext.model_fields["arguments"].annotation == (dict[str, str] | None)
     assert CompletionContext().arguments is None
 

tests/docs_src/test_context.py

@@ -1,4 +1,4 @@
-"""`docs/tutorial/context.md` — every claim the page makes, proved against the real SDK."""
+"""`docs/tutorial/context.md`: every claim the page makes, proved against the real SDK."""
 
 import re