Usage

The module unpoly.up exposes the main Unpoly class which is used to communicate with Unpoly via HTTP headers. All the information of the Unpoly server protocol is exposed and easily accessable.

An example usage could look like this (request.up is enabled via the Django Integration):

def create_user(request):
    # Set a nice <title> for unpoly
    request.up.set_title("Create user | MyDomain.com")
    if request.method == "POST":
        form = UserForm(request.POST)
    else:
        form = UserForm()
    # Do not save the form if unpoly is just trying
    # to validate a form field
    if form.is_valid() and not request.up.validate:
        instance = form.save()
        # Tell unpoly that the user was created successfully
        request.up.emit("user:created", {"id": instance.pk})
        # and also close the layer
        request.up.layer.accept()
    return render(request, "template.html", {"form": form})

class unpoly.up.Unpoly(adapter: BaseAdapter)

The main entrypoint for communication with Unpoly

__bool__() → bool

Returns true if the request is triggered via Unpoly.

This basically checks if the X-Up-Version header is set.

property cache: Cache: Access to the Cache functionality

property context: dict[str, object]: Returns the current context. Initially this is X-Up-Context but the server can modify the returned dictionary to update the values on the client.

emit(type: str, options: dict[str, object]) → None: Emit events to the frontend (X-Up-Events).

property fail_context: dict[str, object]: Returns the current failure context (X-Up-Fail-Context).

property fail_layer: Layer: Access the current Layer configuration for failures.

property fail_mode: str: Returns the request’s failure mode (X-Up-Fail-Mode).

property fail_target: str: Gives access to the request’s failure target (X-Up-Fail-Target). If the server set a new target it will return that instead.

finalize_response(response: object) → None

Finalize the response by settings required headers & cookies.

It should be noted that the response is passed as is to current adapter, which knows how to set headers on the response etc.

property layer: Layer: Access the current Layer configuration.

property mode: str: Returns the request’s mode (X-Up-Mode).

property needs_cookie: bool: Checks whether the response should set the _up_method cookie.

property origin_layer: Layer: Returns a Layer representing the origin mode The layer’s main purpose is to expose the is_root and is_overlay properties.

property origin_mode: str: Returns the request’s origin mode (X-Up-Origin-Mode).

set_title(value: str) → None: Sets the title so Unpoly can update the <title> tag (X-Up-Title).

property target: str: Gives access to the request’s target (X-Up-Target). If the server set a new target it will return that instead.

property validate: list[str]: Returns the fields Unpoly is trying to validate (X-Up-Validate).

property version: str: Unpoly version (X-Up-Version).

property version_info: list[int | str]: Unpoly version (X-Up-Version) parsed into a tuple.

class unpoly.up.Cache(unpoly: Unpoly)

evict(pattern: str = '*') → None: Tell the client to evict all caches matching the pattern (X-Up-Evict-Cache).

expire(pattern: str = '*') → None: Tell the client to remove all caches matching the pattern (X-Up-Expire-Cache).

keep() → None: Tell the client to keep the cache.

class unpoly.up.Layer(unpoly: Unpoly, mode: str, context: dict[str, object])

accept(value: object = None) → None

Accept the current layer (X-Up-Accept-Layer).

An optional value can be provided to be passed back to the client.

context: Current layer context (X-Up[-Fail]-Context).

dismiss(value: object = None) → None

Accept the current layer (X-Up-Dismiss-Layer).

An optional value can be provided to be passed back to the client.

emit(type: str, options: dict[str, object] | None = None) → None

Emit events to the frontend (X-Up-Events).

Similar to Unpoly.emit() but emits on the current layer.

property is_overlay: bool: Returns whether this is an overlay layer.

property is_root: bool: Returns whether this is the root layer.

mode: Current layer mode (X-Up[-Fail]-Mode).

open(**options: object) → None: Open a new layer (X-Up-Open-Layer) with the passed options.