djblets.pagestate.state¶

Page state representations.

class PageStateData[source]¶

Bases: TypedDict

Data to inject into a page

This represents content for the page (as HTML-safe or unsafe text) and an ETag to include with the page response. Both are optional.

New in version 6.0.

content: NotRequired[SafeString | str]¶

The content to include in the page.

This can be HTML-safe or unsafe text.

etag: NotRequired[str | None]¶

The ETag data to include for the HTTP response.

__annotations__ = {'content': ForwardRef('NotRequired[SafeString | str]', module='djblets.pagestate.state'), 'etag': ForwardRef('NotRequired[str | None]', module='djblets.pagestate.state')}¶

__closed__ = None¶

__extra_items__ = typing_extensions.NoExtraItems¶

__mutable_keys__ = frozenset({'content', 'etag'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (typing_extensions.TypedDict,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'content', 'etag'})¶

__total__ = True¶

class PageState[source]¶

Bases: object

Additional state used for the dynamic construction of a page.

This is used to dynamically inject content into a page. Pages can make use of {% page_hook_point %} template tags to specify places where content can be injected.

Content can be injected in two ways:

1. Manually through calls to :py:meth:inject`.

2. Dynamically by calling registered injectors, which take a page hook point name and provide the data to inject.

Both content for the page and ETags for the response can be injected.

If the same named page hook point is used in multiple places, or across multiple template renders within a request/response cycle, each point will contain the injected content.

Callers can also store and retrieve arbitrary data using the extra_data attribute. This will not affect page rendering or ETags.

New in version 6.0.

classmethod for_request(request: HttpRequest, *, only_if_exists: Literal[True]) → Self | None[source]¶

classmethod for_request(request: HttpRequest, *, only_if_exists: Literal[False] = False) → Self

Return a PageState for a given HTTP request.

The same instance will be returned every time this is called for the same HTTP request.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• only_if_exists (bool, optional) –

  If set, this will return None if data doesn’t already exist.

  By default, an instance will always be returned.

Returns:

The page state instance for the request.

Return type:

PageState

__init__() → None[source]¶

Initialize the page state.

extra_data: dict[str, Any]¶

A dictionary callers can use for arbitrary storage of data.

__annotations__ = {'_data': 'dict[str, list[PageStateData]]', '_etag_sha': '_Hash | None', 'extra_data': 'dict[str, Any]'}¶

inject(point_name: str, data: PageStateData) → None[source]¶

Manually inject data into the page.

This may contain content for the page hook point, and it may contain ETag data to include in the final ETag.

Parameters:

• point_name (str) – The page hook point name to inject data into.

• data (PageStateData) – The data to inject into the page hook point.

Raises:

ValueError – The page state data was missing a required key or contained an incorrect type.

clear_injections(point_name: str | None = None) → None[source]¶

Clear injections for one or all page hook points.

If a point name isn’t provided, manual injections will be cleared from all points.

Parameters:

point_name (str, optional) – The optional page hook point name to clear injections from.

get_etag() → str[source]¶

Return the current ETag for the page.

If called while the page is still being rendered, future calls may have a different result.

Returns:

The current ETag for the data on the page.

Return type:

str

iter_content(*, point_name: str, request: HttpRequest, context: Context) → Iterator[SafeString | str][source]¶

Iterate through rendered content for a page hook point.

This will first iterate through all dynamic injectors and then through all manual injections in order.

Any missing ETags will be generated based on the page content, ensuring that changes in content will cause caches to invalidate.

Any errors coming from an injector will be logged and the injector skipped.

Parameters:

• point_name (str) – The page hook point name to iterate through.

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The context for the template.

Yields:

str or django.utils.safestring.SafeString – Each HTML-safe or unsafe content injected into the page hook point.

iter_page_state_data(*, point_name: str, request: HttpRequest, context: Context) → Iterator[PageStateData][source]¶

Iterate through all page state data for a page hook point.

This will first iterate through all dynamic injectors and then through all manual injections in order.

Any errors coming from an injector will be logged and the injector skipped.

Parameters:

• point_name (str) – The page hook point name to iterate through.

• request (django.http.HttpRequest) – The HTTP request from the client.

• context (django.template.Context) – The context for the template.

Yields:

str or django.utils.safestring.SafeString – Each HTML-safe or unsafe content injected into the template hook point.