server.speculation_rules

Page actions AI-ready formats and sharing
Open LLM text
Share with AI
Ask Claude Ask ChatGPT Ask Gemini Ask Copilot
module

Speculation Rules injection — automatic prefetch/prerender hints from route definitions.

Three modes controlled byAppConfig.speculation_rules:

  • False / "off"— inject nothing (default).
  • True / "conservative"— prefetch linked pages on hover/pointerdown.…

Speculation Rules injection — automatic prefetch/prerender hints from route definitions.

Three modes controlled byAppConfig.speculation_rules:

  • False / "off"— inject nothing (default).
  • True / "conservative"— prefetch linked pages on hover/pointerdown. Safe for all apps.
  • "moderate"— prefetch all static GET routes eagerly, prerender on hover.
  • "eager"— prerender static GET routes eagerly. Use only when routes are side-effect-free and fast.

Injected into full-page HTML responses viaHTMLInjectmiddleware, before</head>.

Chirp generates rules from the router at freeze time:

  • Static GET routes (no path parameters) become"source": "list" candidates.
  • Parametric routes are expressed ashref_matchespatterns.
  • SSE endpoints (referenced=True) and non-GET routes are excluded.

server.speculation_rules

Name Type Default Description
type —
qualified_name —
element_type —
description —
source_file —
line_number —
is_autodoc —
autodoc_element —
_autodoc_template —
_autodoc_url_path —
_autodoc_page_type —
title —
doc_content_hash —

Symbols on this page

function normalize_speculation_rules

Canonicalize thespeculation_rulesconfig value.

Returns one of"off", "conservative", "moderate", or "eager".

Jump to symbol function _route_to_href_pattern

Convert a Chirp route path to a Speculation Ruleshref_matchespattern.

/users/{id:int} becomes /users/*.

Jump to symbol function build_speculation_rules_json

Generate Speculation Rules JSON from the router.

Returns empty string for"off"mode or when no eligible routes exist.

Jump to symbol function build_speculation_rules_snippet

Build the full<script type="speculationrules">snippet.

Returns empty string when mode is"off"or no rules are generated.

A<script type="speculationrules">element is governed…

Jump to symbol
normalize_speculation_rules
function 
def normalize_speculation_rules(value: bool | str) -> SpeculationRulesMode

Canonicalize thespeculation_rulesconfig value.

Returns one of"off", "conservative", "moderate", or "eager".

Parameters

Name Type Default Description
value bool | str —
_route_to_href_pattern
function 
def _route_to_href_pattern(path: str) -> str

Convert a Chirp route path to a Speculation Ruleshref_matchespattern.

/users/{id:int} becomes /users/*.

Parameters

Name Type Default Description
path str —
build_speculation_rules_json
function 
def build_speculation_rules_json(router: object, mode: SpeculationRulesMode) -> str

Generate Speculation Rules JSON from the router.

Returns empty string for"off"mode or when no eligible routes exist.

Parameters

Name Type Default Description
router object —
mode SpeculationRulesMode —
build_speculation_rules_snippet
function 
def build_speculation_rules_snippet(router: object, mode: SpeculationRulesMode, *, nonce: str = '') -> str

Build the full<script type="speculationrules">snippet.

Returns empty string when mode is"off"or no rules are generated.

A<script type="speculationrules">element is governed by the CSP script-src directive, so when nonce is non-empty the <script> carries anonce="..."attribute and survives a nonce-based CSP that no longer ships'unsafe-inline'.

Parameters

Name Type Default Description
router object —
mode SpeculationRulesMode —
nonce str ''

View source · /home/runner/work/chirp/chirp/site/../src/chirp/server/speculation_rules.py:1