Installation

pip install brickly-core

Quick start

You describe which widget is shown at which path, and brickly-core builds the routing for the frontend out of it. Everything you need is imported from the package:

from dataclasses import dataclass
from typing import Literal

from brickly_core import *


# 1. Widgets: what the frontend renders.
@dataclass(kw_only=True)
class TextWidget(Widget):
    type: Literal["text"] = "text"
    text: str


# 2. Events: functions that build the content of a screen.
@event("layout")
async def layout(**_):
    return FragmentWidget(TextWidget(text="My shop"), OutletWidget())

@event("home")
async def home(**_):
    return TextWidget(text="Welcome!")

@event("item")
async def item(item_id: int, **_):
    return TextWidget(text=f"Item #{item_id}")

@event("item.meta")
async def item_meta(item_id: int, **_):
    return {"title": f"Item #{item_id}"}


# 3. Screens bound to paths.
router = Router(paths=[
    RouterPath(template="/", screen=Screen(shell_widget=layout, widget=home)),
    RouterPath(template="item/{item_id:int}", screen=Screen(
        widget=item,
        meta=item_meta,
        fallback_widget=TextWidget(text="Item is unavailable"),
    )),
])

# 4. The routing of the app, ready to be served to the frontend.
settings = RouterSettings(routers=[router])

Opening /item/42 shows My shop (the layout of /) with Item #42 inside it.

Events

@event marks a function that the routing may call to build a screen: its widget, its layout, its meta data, or a middleware step. Only decorated functions can be used in Screen and Middleware.

@event("item")
async def item(item_id: int, **_):
    return TextWidget(text=f"Item #{item_id}")

• Give every event a unique name ("item", "shop.cart", …). Using the same name twice is an error at import time.

• Path parameters arrive as keyword arguments with their names from the template: item/{item_id:int} gives item_id. End the signature with **_ to accept everything else.

• Both async def and plain def work.

• Events can be static or class methods. Put @event above @staticmethod / @classmethod:

  class Pages:
      @event("pages.about")
      @staticmethod
      async def about(**_):
          return TextWidget(text="About")
  
      @event("pages.contacts")
      @classmethod
      async def contacts(cls, **_):
          return TextWidget(text="Contacts")
  
  RouterPath(template="about", screen=Screen(widget=Pages.about))

  Regular methods taking self can’t be events.

Screens

A Screen describes what is shown at a path. All settings are optional:

Layouts nest along the path. With a layout on / and another on /dashboard, opening /dashboard/stats renders the / layout, inside it the /dashboard layout, and inside that the stats page:

router = Router(paths=[
    RouterPath(template="/", screen=Screen(shell_widget=main_layout)),
    RouterPath(template="dashboard", screen=Screen(shell_widget=dashboard_layout)),
    RouterPath(template="dashboard/stats", screen=Screen(widget=stats)),
])

Paths

RouterPath(template=..., screen=...) binds a screen to a path.

• Segments are separated by /; leading and trailing slashes don’t matter, and "/" is the root of the router.

• A parameter is written {name:type}: item/{item_id:int}, shop/{slug:str}. Its value is passed to the events of that screen and of the screens below it.

Routers

A Router groups paths under a common prefix. Split a big app into several routers, e.g. one per module, and pass them all to RouterSettings:

shop = Router(prefix="/shop", paths=[
    RouterPath(template="/", screen=Screen(widget=shop_page)),
    RouterPath(template="item/{item_id:int}", screen=Screen(widget=item)),
])
blog = Router(prefix="/blog", paths=[
    RouterPath(template="/", screen=Screen(widget=blog_page)),
])

settings = RouterSettings(routers=[shop, blog])     # /shop, /shop/item/42, /blog

Paths can also be added later with router.add(RouterPath(...)). Build RouterSettings once every router is complete.

# users module
admin_users = Router(prefix="/admin", middleware=Middleware(events=[require_admin]), paths=[
    RouterPath(template="users", screen=Screen(widget=users)),
])

# billing module: no middleware of its own
admin_billing = Router(prefix="/admin", paths=[
    RouterPath(template="billing", screen=Screen(widget=billing)),
])

settings = RouterSettings(routers=[admin_users, admin_billing])

custom = Router(paths=[
    RouterPath(template="/", screen=Screen(widget=my_home), override=True),
])

settings = RouterSettings(routers=[router, custom])   # "/" now shows my_home

Middleware

Middleware are events that run before a screen is shown: load the current user, check access, redirect. Each one returns what should happen next:

@event("auth.load_user")
async def load_user(ctx, **_):
    user = await get_current_user()
    if user is None:
        return Redirect(to="/login")
    return Allow(context={"user": user})

@event("auth.require_admin")
async def require_admin(ctx, **_):
    if not ctx.data["user"].is_admin:          # data passed on by load_user
        return Deny(status=403)

Attach middleware to the whole app or to a router:

admin = Router(prefix="/admin", middleware=Middleware(events=[require_admin]), paths=[...])

settings = RouterSettings(
    routers=[router, admin],
    middleware=Middleware(events=[load_user]),      # runs before every screen
)

• RouterSettings(middleware=...) runs before every screen of the app, first.

• Router(middleware=...) runs before every screen under the router’s prefix, including pages of other routers with the same prefix (see above), and nested prefixes such as /admin/reports.

• Middleware runs from the outside in: app first, then /admin, then /admin/reports. A middleware listed more than once runs only once.

• Redirect and Deny stop the chain: the middleware after them don’t run.