Links¶

A Link model whose href may be a callable resolved against the request at serialization time — so links are built with no request in hand.

Deferred hrefs¶

Link.href accepts either a concrete URL or a UrlResolver: a callable taking the request context and returning a URL. A resolver href is invoked during JSON serialization, which is what lets you build the link far from any request:

from gazebo.link import Link
from gazebo.rels import Rel

# Built in business logic with no request in hand: the href is a callable, and is
# resolved against the active request when the model is serialized to JSON.
link = Link(href=lambda ctx: ctx.url_for('plant', id=1), rel=Rel.ITEM)

The Link model¶

Beyond href, a Link carries the usual OGC/Atom members — rel, type, title, method, headers, body — and allows extras (extra='allow') for anything a profile defines. None fields are dropped on JSON serialization, so an unset title simply doesn't appear. See the reference for the full field list.

Factories¶

You rarely spell out a rel and a resolver by hand. Three classmethods cover the common links, each deferred so it resolves against the live request:

from gazebo.link import Link
from gazebo.rels import Rel

links = [
    Link.self_link(),  # the current request URL
    Link.root_link(),  # url_for('landing')
    Link.to_route('plant', rel=Rel.ITEM, path={'id': 1}),  # url_for('plant', id=1)
]

For a route with path parameters, pass them as the path mapping (Link.to_route('plant', rel=Rel.ITEM, path={'id': 1})). Those values are bound into the deferred resolver and handed to ctx.url_for at serialization time — they are not stored as fields on the link, so they never appear in the emitted JSON.

Resolving without a request¶

A link only serializes to a real URL when a context is available. Under the FastAPI glue that's automatic for every response. For a manual dump, pass the context (see request context); with no context available, a callable href raises a clear error instead of emitting a broken link.

Reference¶

See gazebo.link.