Skip to content

xtr_web_profiler

A development toolbar on every page, and a profile of every request.

In the development environment, each HTML page an application serves gets a toolbar at its foot: the status, the time it took, the memory, the log, the events, the route, the background requests the page made since. Each item opens the request's full profile — request and response, a timeline of where the time went, every log record, every listener, the exception with its frames — and every profile stays searchable for two days.

The profiles are collected by the http kernel's profiler; this package draws them. A library adds a panel by registering a data collector with a template.

PROFILER_PAGE_HEADER module-attribute

PROFILER_PAGE_HEADER: Final = 'X-Profiler-Page'

Marks a response as one of the profiler's own pages, which no policy restricts.

ProfilerController

ProfilerController(profiler: Profiler | None, manager: TemplateManager, project_dir: Path)

Answers every page of the profiler.

Each page leaves its own request unprofiled, so looking at profiles never makes more of them. With the profiler off — the application turned it off under the http kernel's configuration — every page answers 404, as an application without the profiler would.

Show what profiler stored, through manager's templates.

Parameters:

  • profiler (Profiler | None) –

    What stores the profiles; None when profiling is off.

  • manager (TemplateManager) –

    What renders the pages and the panels.

  • project_dir (Path) –

    The project's root: the source view shows no file outside it.

toolbar async

toolbar(request: Request, response: Response, token: str) -> Response

Return the toolbar of the profile token: every collector's toolbar block.

stylesheet async

stylesheet(response: Response) -> Response

Return the toolbar's stylesheet, which a page may cache for ten minutes.

home async

home(request: Request, response: Response) -> Response

Send the browser to the latest profiles.

search async

search(request: Request, response: Response) -> Response

Send the browser to the profile a token names, or to the profiles the filters find.

search_results async

search_results(request: Request, response: Response, token: str) -> Response

Return the stored profiles the filters find, newest first.

panel async

panel(request: Request, response: Response, token: str) -> Response

Return the profile token with its menu and one panel; latest is the newest.

open_file async

open_file(request: Request, response: Response) -> Response

Return a source file of the project, the asked-for line marked.

InvalidArgumentError

Bases: WebProfilerError, ValueError

A configuration value the web profiler would misread.

Also a :class:ValueError.

TemplateNotFoundError

TemplateNotFoundError(collector: str, template: str)

Bases: WebProfilerError, LookupError

A data collector names a panel template that does not exist.

The template is named on the collector's tag as "@<import package>/<path under its templates folder>". Also a :class:LookupError.

Attributes:

  • collector (str) –

    The collector whose panel could not be shown.

  • template (str) –

    The template its tag names.

Record the collector and the template it names.

WebProfilerError

Bases: Exception

Base class for every error raised by this library.

Every subclass carries what went wrong as typed attributes and composes its own message from them.

CollectorView dataclass

CollectorView(name: str, data: Mapping[str, object])

What a panel template knows as collector.

Attributes:

  • name (str) –

    The collector's name.

  • data (Mapping[str, object]) –

    What it kept of the request, as the profile stored it — collector.data.method, collector.data["status_code"].

TemplateManager

TemplateManager(environment: Environment, templates: DataCollectorTemplates)

Pairs a profile's collectors with their panel templates, and renders a template's blocks.

A panel template defines up to four blocks — toolbar (the toolbar item), menu (the profile page's menu entry), panel (the panel itself) and head (anything the panel needs in the page head) — and each is rendered on its own, so the toolbar and the profile page draw from one template per collector.

Render with environment the panels templates names.

get_names

get_names(profile: Profile, profiler: Profiler) -> list[tuple[str, str]]

Return the (collector, template) pairs of profile's panels, in panel order.

A panel is shown when its collector is registered and kept data in this profile.

Raises:

render_block

render_block(template: str, block: str, context: Mapping[str, object]) -> Markup

Return block of template rendered with context; empty when it has none.

render

render(template: str, context: Mapping[str, object]) -> str

Return the whole of template rendered with context.

WebDebugToolbarMiddleware

WebDebugToolbarMiddleware(app: ASGIApp, *, config: WebProfilerConfig, manager: TemplateManager, csp: ContentSecurityPolicyHandler)

Names each profile on its response, and draws the toolbar into the HTML pages.

Every response naming a profile in X-Debug-Token also gets X-Debug-Token-Link, the address of its profile — what a client that renders no HTML follows. A background request (X-Requested-With: XMLHttpRequest, or a fetch the browser marks as not loading a document) never gets the toolbar; with ajax_replace its response asks the page to reload the toolbar with its own profile.

The toolbar is drawn into a response only when all of these hold: the toolbar is on, the response names a profile, it is no redirect, its content type is HTML, it is no attachment, its body is not encoded, and the request was not a background one. It goes in before the closing </body> — found even when the tag is split across two chunks of a streamed body — and the Content-Length is dropped, the body having grown. A page with no </body> goes out unchanged.

With intercept_redirects, a redirect answering a page is replaced by a page saying where it leads, toolbar included, so the request that redirected can be read before following it.

The profiler's own pages run under no content security policy; any other page drawn into has the toolbar's nonces added to its policy.

A compressed body cannot be drawn into, and a browser always accepts one. So a request that may get the toolbar — one accepting HTML, or anything, that is not a background request — reaches the application without its Accept-Encoding: the application's own compression leaves that page as it is, and the answers to background requests and to clients asking for something else stay compressed. This runs only where the profiler does, in development.

Wrap app.

Parameters:

  • app (ASGIApp) –

    The application whose pages get the toolbar.

  • config (WebProfilerConfig) –

    Whether the toolbar is on, and how it behaves.

  • manager (TemplateManager) –

    What renders the toolbar's loader and the redirect page.

  • csp (ContentSecurityPolicyHandler) –

    What lets the toolbar run under a page's policy.

config property

config: WebProfilerConfig

How the toolbar behaves.

csp property

csp: ContentSecurityPolicyHandler

What lets the toolbar run under a page's policy.

snippet

snippet(scope: Scope, token: str, nonces: dict[str, str]) -> bytes | None

Return the toolbar's loader for the profile token, or None when unrouted.

redirect_page

redirect_page(location: str, status: int, snippet: bytes) -> bytes

Return the page standing in for a redirect to location.