freeze - Chirp

Freeze — render routes to static HTML files.

Walks the app's route table after freeze, renders each freezable URL through the full ASGI middleware stack via TestClient, and writes the output to disk.

URLs in the frozen HTML are rewritten from absolute (/about) to relative (../about/) so the output works on any static host — S3, GitHub Pages, Cloudflare, or plainfile://— without a server to resolve clean URLs.

freeze

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

class FreezeResult

Summary of a freeze run.

class BlockEntry

One addressable section inside aSearchEntry.

Block-grained entries enable deep-linking search results to #anchor targets rather than only page URLs. bodyshould be…

class SearchEntry

Structured search data captured at render time.

Route handlers callsearch_contribute() during freeze to register structured metadata for the current page. This bypasses…

function search_contribute

No-op outside of freeze (the ContextVar defaults toNone).

function _url_to_file_path

Map a URL path to an output file path.

/docs/get-started/ → output_dir/docs/get-started/index.html / → output_dir/index.html

function _expand_params

Replace\{name} or {name:type}placeholders with values.

function _make_relative

Convert an absolute URL to a relative path toindex.html.

Both arguments are absolute paths (e.g./articles/foo). The result is relative from…

function _relativize_html

Rewrite absolute URL paths in html to relative paths.

Only rewrites paths that match known_urls(the set of frozen pages). External URLs, anchors, and…

function _page_depth

Return the directory depth of a URL path (for relative path computation).

function _extract_title

Extract the page title from or first <h1>.</p> </div> <span class="chirp-theme-reference-card__footer"> <span>Jump to symbol</span> <svg width="14" height="14" class="bengal-icon icon-caret-down" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="none"> <title>Caret Down function _extract_snippet

Extract a text snippet from the

element for search matching.

function _build_search_index

Build a search index from rendered (url, html) pairs.

Each entry hasu (relative file path), t(title), and optionallyd(text snippet for…

function _build_rich_search_index

Build a structured search manifest from render-time contributions.

Pages that contributed structured data viasearch_contribute() get full metadata (category, tags, TOC, description). Pages…

function _extract_internal_hrefs

Return the set of internal URLs referenced by<a href>in html.

Fragments (#section) and query strings (?x=1) are…

function _build_xref_graph

Build the cross-reference graph from rendered pages.

Manifest format::

{
    "version": 1,
    "pages": {
        "/docs/intro/": {
            "references": ["/docs/a/", "/docs/b/"],
            "referenced_by": ["/docs/c/"]
        }
    }
}
…

function _inject_static_search

Inject the client-side search script into a frozen HTML page.

Only injects if the page contains a.chirp-docs-searchinput. Uses a<script src>for…

function _enumerate_urls

Classify routes and expand parameterized ones.

Returns (urls, skipped_reasons, warnings).

function _live_blocks_for_url

Return(route_path, spec)for live blocks matching url.

An empty list means this URL has no live-block rewrites to apply.

function _live_placeholder_html

Render the htmx placeholder that replaces a live block in frozen HTML.

function _apply_live_blocks

Rewrite declared live blocks in html as htmx placeholders.

Matches urlto a registered route, then for each live block declared on that route…

async function freeze

Freeze the app to static HTML files.

Renders every freezable GET route through the full ASGI stack and writes the output to output_dir.

FreezeResult

class

Summary of a freeze run.

BlockEntry

class

One addressable section inside aSearchEntry.

Block-grained entries enable deep-linking search results to #anchor targets rather than only page URLs. bodyshould be plain text (tags stripped) for direct match scoring.

SearchEntry

class

Structured search data captured at render time.

Route handlers callsearch_contribute() during freeze to register structured metadata for the current page. This bypasses HTML scraping entirely — category, tags, TOC, and description survive from the template context to the search index.

search_contribute

function

def search_contribute(entry: SearchEntry) -> None

No-op outside of freeze (the ContextVar defaults toNone).

Parameters

Name	Type	Default	Description
`entry`	`SearchEntry`	—

_url_to_file_path

function

def _url_to_file_path(url: str, output_dir: Path) -> Path

Map a URL path to an output file path.

/docs/get-started/ → output_dir/docs/get-started/index.html / → output_dir/index.html

Parameters

Name	Type	Default	Description
`url`	`str`	—
`output_dir`	`Path`	—

_expand_params

function

def _expand_params(route_path: str, params: dict[str, str]) -> str

Replace\{name} or {name:type}placeholders with values.

Parameters

Name	Type	Default	Description
`route_path`	`str`	—
`params`	`dict[str, str]`	—

_make_relative

function

def _make_relative(from_url: str, to_url: str) -> str

Convert an absolute URL to a relative path toindex.html.

Both arguments are absolute paths (e.g./articles/foo). The result is relative from the directory containing from_url/index.html and points to to_url/index.html so thatfile://browsing works (no server-side index resolution needed).

Examples::

_make_relative("/articles/foo", "/about")
    # "../../about/index.html"
_make_relative("/articles/foo", "/")
    # "../../index.html"
_make_relative("/", "/about")
    # "about/index.html"

Parameters

Name	Type	Default	Description
`from_url`	`str`	—
`to_url`	`str`	—

_relativize_html

function

def _relativize_html(html: str, page_url: str, known_urls: frozenset[str]) -> str

Rewrite absolute URL paths in html to relative paths.

Only rewrites paths that match known_urls (the set of frozen pages). External URLs, anchors, and unknown paths are left untouched.

Parameters

Name	Type	Default
`html`	`str`	—
`page_url`	`str`	—
`known_urls`	`frozenset[str]`	—

_page_depth

function

def _page_depth(url: str) -> int

Return the directory depth of a URL path (for relative path computation).

Parameters

Name	Type	Default	Description
`url`	`str`	—

_extract_title

function

def _extract_title(html: str) -> str

Extract the page title from or first <h1>.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">html</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">str</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_extract_snippet</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_extract_snippet" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _extract_snippet(html: str, max_len: int = 200) -> str</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Extract a text snippet from the <article> element for search matching.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">html</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">max_len</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">int</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <code class="chirpui-params-table__code chirpui-params-table__code--muted">200</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">str</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_build_search_index</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_build_search_index" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _build_search_index(rendered: list[tuple[str, str]]) -> list[dict[str, str]]</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Build a search index from rendered (url, html) pairs.</p> <p>Each entry has<code>u</code> (relative file path), <code>t</code>(title), and optionally<code>d</code>(text snippet for full-text matching).</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">rendered</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[tuple[str, str]]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">list[dict[str, str]]</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_build_rich_search_index</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_build_rich_search_index" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _build_rich_search_index(contributions: list[SearchEntry], rendered: list[tuple[str, str]]) -> dict[str, Any]</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Build a structured search manifest from render-time contributions.</p> <p>Pages that contributed structured data via<code>search_contribute</code>() get full metadata (category, tags, TOC, description). Pages without contributions fall back to HTML scraping for title + snippet.</p> <p>The manifest format (v2)::</p> <pre><code>{ "version": 2, "facets": {"category": [...], "tags": [...]}, "entries": [{"u", "t", "d", "c", "tags", "toc", "body", "blocks"}, ...] } </code></pre> <p>Each block entry has<code>{"id", "h", "b", "a", "d"}</code>for block id, heading, plain-text body, anchor (href fragment), and heading depth.</p> <p>Version 2 is a superset of v1: readers that ignore<code>blocks</code>behave identically to v1 readers.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">contributions</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[SearchEntry]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">rendered</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[tuple[str, str]]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">dict[str, Any]</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_extract_internal_hrefs</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_extract_internal_hrefs" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _extract_internal_hrefs(html: str, known_urls: frozenset[str]) -> list[str]</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Return the set of internal URLs referenced by<code><a href></code>in <em>html</em>.</p> <p>Fragments (<code>#section</code>) and query strings (<code>?x=1</code>) are stripped before matching against <em>known_urls</em>. External links (<code>https:</code>, <code>mailto:</code>) are not captured because the regex anchors on <code>href="/</code>.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">html</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">known_urls</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">frozenset[str]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">list[str]</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_build_xref_graph</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_build_xref_graph" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _build_xref_graph(rendered: list[tuple[str, str]], known_urls: frozenset[str]) -> dict[str, Any]</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Build the cross-reference graph from rendered pages.</p> <p>Manifest format::</p> <pre><code>{ "version": 1, "pages": { "/docs/intro/": { "references": ["/docs/a/", "/docs/b/"], "referenced_by": ["/docs/c/"] } } } </code></pre> <p>Lists are sorted alphabetically so the output is deterministic. Self- references are excluded.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">rendered</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[tuple[str, str]]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">known_urls</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">frozenset[str]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">dict[str, Any]</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_inject_static_search</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_inject_static_search" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _inject_static_search(html: str, depth: int, index_path: str) -> str</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Inject the client-side search script into a frozen HTML page.</p> <p>Only injects if the page contains a<code>.chirp-docs-search</code>input. Uses a<code><script src></code> for the index (works on <code>file://</code>) and an inline script for the search logic.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">html</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">depth</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">int</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">index_path</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">str</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_enumerate_urls</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_enumerate_urls" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _enumerate_urls(app: App) -> tuple[list[str], list[str], list[str]]</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Classify routes and expand parameterized ones.</p> <p>Returns (urls, skipped_reasons, warnings).</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">app</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">App</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">tuple[list[str], list[str], list[str]]</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_live_blocks_for_url</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_live_blocks_for_url" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _live_blocks_for_url(app: App, url: str) -> list[tuple[str, LiveBlockSpec]]</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Return<code>(route_path, spec)</code>for live blocks matching <em>url</em>.</p> <p>An empty list means this URL has no live-block rewrites to apply.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">app</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">App</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">url</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">list[tuple[str, LiveBlockSpec]]</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_live_placeholder_html</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_live_placeholder_html" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _live_placeholder_html(url: str, spec: LiveBlockSpec) -> str</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Render the htmx placeholder that replaces a live block in frozen HTML.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">url</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">spec</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">LiveBlockSpec</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">str</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">_apply_live_blocks</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="_apply_live_blocks" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>def _apply_live_blocks(html: str, url: str, app: App, captures: list[tuple[str, dict[str, Any]]], errors: list[str]) -> str</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Rewrite declared live blocks in <em>html</em> as htmx placeholders.</p> <p>Matches <em>url</em> to a registered route, then for each live block declared on that route renders it in isolation with the captured template context and replaces the exact string match in <em>html</em>. No-op when nothing matches.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">html</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">url</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">str</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">app</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">App</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">captures</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[tuple[str, dict[str, Any]]]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">errors</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[str]</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">str</code> </p> </div> </aside> </div> </div> </details> <details class="chirpui-accordion__item chirp-theme-reference-member" name="reference-members" > <summary class="chirpui-accordion__trigger"> <span class="chirpui-accordion__trigger-text">freeze</span> <div class="chirpui-accordion__trigger-actions"> <span class="chirpui-badge chirpui-badge--muted"> <span class="chirpui-badge__text">function</span> </span> <span class="chirpui-badge chirpui-badge--info"> <span class="chirpui-badge__text">async</span> </span> </div> </summary> <div class="chirpui-accordion__content"> <div id="freeze" class="chirp-theme-reference-member__body"> <div class="chirpui-code-block-wrapper chirp-theme-reference-member__signature" x-data="chirpuiCopy()"> <pre class="chirpui-code-block"><code>async def freeze(app: App, output_dir: Path, *, exclude: list[str] | None = None) -> FreezeResult</code></pre> <button type="button" class="chirpui-code-block__copy" data-copy-timeout="2000" @click="copy()" aria-label="Copy code"> <span x-show="!copied" aria-hidden="true">⧉</span> <span x-show="copied" x-cloak aria-hidden="true">✓</span> </button> </div> <div class="chirpui-rendered-content chirpui-rendered-content--compact chirp-theme-reference-member__description"> <p>Freeze the app to static HTML files.</p> <p>Renders every freezable GET route through the full ASGI stack and writes the output to <em>output_dir</em>.</p> </div> <div class="chirpui-params-table chirp-theme-reference-member__params"> <p class="chirpui-params-table__title">Parameters</p> <div class="chirpui-params-table__wrap" tabindex="0" aria-label="Parameters"> <table class="chirpui-params-table__table"> <thead class="chirpui-params-table__head"> <tr> <th class="chirpui-params-table__th chirpui-params-table__th--name">Name</th> <th class="chirpui-params-table__th chirpui-params-table__th--type">Type</th> <th class="chirpui-params-table__th chirpui-params-table__th--default">Default</th> <th class="chirpui-params-table__th chirpui-params-table__th--description">Description</th> </tr> </thead> <tbody class="chirpui-params-table__body"> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">app</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">App</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">output_dir</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">Path</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <span class="chirpui-params-table__empty">—</span> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> <tr class="chirpui-params-table__row"> <td class="chirpui-params-table__td chirpui-params-table__td--name"> <code class="chirpui-params-table__code">exclude</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--type"> <code class="chirpui-params-table__code">list[str] | None</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--default"> <code class="chirpui-params-table__code chirpui-params-table__code--muted">None</code> </td> <td class="chirpui-params-table__td chirpui-params-table__td--description"> </td> </tr> </tbody> </table> </div> </div> <aside class="chirpui-callout chirpui-callout--neutral chirp-theme-reference-returns"> <div class="chirpui-callout__header"> <div class="chirpui-callout__title">Returns</div> <div class="chirpui-callout__header-actions"></div> </div> <div class="chirpui-callout__body"> <p class="chirp-theme-reference-returns__type"> <code class="chirpui-code">FreezeResult</code> </p> </div> </aside> </div> </div> </details> </div> <p class="chirp-theme-reference-source"> <a href="https://github.com/lbliii/chirp/blob/main//home/runner/work/chirp/chirp/site/../src/chirp/freeze.py#L1" class="chirp-theme-reference-source__link" target="_blank" rel="noopener"> <svg width="14" height="14" class="bengal-icon icon-code" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="none"> <title>Code View source · /home/runner/work/chirp/chirp/site/../src/chirp/freeze.py:1