Feedback Wanted: Rio Extension API

[mad-moo]

We've long wanted to add an extension API to Rio. The plan is to allow everyone
to extend Rio while keeping the core small(ish). We have thought about this for
some time and have a first outline of what we think the API should look like.
Please take a look and let us know what you think.

The basic idea is to create a rio.Extension class that can be subclassed to
expand Rio's functionality. Then, when a rio.App is created, a list of
extensions can be passed in to add the functionality to the app. Something like
this:

app = rio.App(
    name='My App',
    extensions=[
        # Example: An extension that adds an admin interface to the app, which
        # displays a summary of connected users, server statistics
        AdminPageExtension(),
        # Another example: An extension that adds OAuth2 support to the app,
        # making it easy to add Single Sign-On to the app
        OAuthExtension(
            client_id='abc123',
            client_secret='def456',
        ),
    ],
)

Extension API

The API is simple: Create a Python class that inherits from rio.Extension.
This class can then register handlers that are triggered whenever something
happens in an app:

• on_app_start is called when the app starts up
• on_app_close is the counterpart to on_app_start and is called when the app
  is shutting down
• on_session_start is called when a new user connects to the app
• on_session_close is called when a user disconnects from the app
• on_as_fastapi is not only in desperate need for a better name, but is also
  called when as_fastapi is called on an app. This allows extensions to add
  custom routes or middlewares to the FastAPI app that Rio uses internally
• on_page_change triggers when a user navigates to a new page in the app

More events can be added in the future of course, these are just what we've
thought up so far.

A simple extension would look something like this:

class CookieWarningExtension(rio.Extension):
    @rio.extension_event.on_session_start
    async def show_cookie_warning(self, session: rio.Session) -> None:
        await session.display_custom_dialog(
            CookieWarningComponent,
        )

A real extension would of course also bring configuration options and make sure
not to warn the same user multiple times, but you get the idea.

Use Cases

• Add an admin interface to the app
• Add OAuth2 support to the app
• Add local authentication to the app
• Display a cookie warning to users in the EU
• Add Telemetry

Feedback

What do you think? Is this API flexible enough? Are there any events missing? Do
you have a better idea alltogether? Let us know!

[azidancorp]

I'm all for supporting new features that will allow ease of adding and incorporating common utilities!

I'm a bit unsure of how an extension layout will be - can it be multiple files, have external dependencies or data sources? And consequently, will this data have to be in its own place, or how easily can it be integrated into the rest of the app/data.

Take authentication for example - I can see how the initial db setup/login works, but how would it look in practice when parts of the main app would need to interact with extended functionality? For example, page guards, or a core persistence class - would it need to be moved to on_page_change instead? Or even multiple extensions interacting with each other - say an admin panel extension that needs to update roles in the user db, which is linked to an auth extension.

How much of this can instead be achieved by having a component library instead - for example the cookie warning. Auth/admin however sounds more like it will need a lot more glue - just wondering if it would be better to just have an example app library for these more complex things.

[mad-moo]

The API is just this one class. How the project creating that class is ultimately laid out is none of Rio's business - you can put it all in one file, multiple files, whatever. You've got all of Python at your disposal.

You're right that these extensions would bring some components (like the cookie warning), but that's not really their purpose - the logic behind them is. For example, you may only want to show the cookie warning in countries that need it. And only show it once, then remember the user's choice somewhere.

I'm also currently thinking about how to exactly design the authentication example. I might create another discussion for that once I've got a decent idea

[iwr-redmond]

How the project creating that class is ultimately laid out is none of Rio's business.

To misquote Martin Nally, the most important design principle for promoting adoption is to maximize developer success.

A robust extension API should have standards and guardrails to encourage high-quality coding and support easy compatibility with future core versions. While I agree that the specific file structure isn't necessarily very relevant, per se, I think there should be some standards that Rio core measures extensions against before loading them. This could include, for example:

1. A mandatory namespace (rio.extension.your_package_here)
2. A mandatory package layout, e.g. __init__.py, __extension__.py, utils.py, and an extension frontend directory mirroring the main package's structure as standard
3. At least one user-facing component (Rio is a UI framework after all)
4. Mandatory support for all six event decorators (on_mount, etc.) with instructions for passing this test when a particular decorator is irrelevant for the extension

It might also be useful to consider requiring a Rio-specific section inside each extension's pyproject.toml, similar to the ComfyUI's [tool.comfy], to support an extension registry at some later time.

[iwr-redmond]

I would like to see support for integrating Typescript libraries with the Python framework, allowing for extensions that are built around TS projects while remaining Python-only for end users.

[mad-moo]

That would require us to bundle a typescript compiler, thus bloating Rio. Supporting JS supports both JS and TS, it just needs to be compiled first

[iwr-redmond]

You could include a dev option, similar to the window one, that includes nodejs-wheel as a dependency along with hatchling, and then a CLI utility that creates an extension template with starter configurations copied from the main project. Ordinary users would be unaffected, while extension developers would have easy access to best practices.

Edit (trigger-happy today): nodejs-bin -> nodejs-wheel

[mad-moo]

I like that idea!

[felipetesc]

I don't know if that's feasible, perhaps even crazy, but what about integrating with Brython for DOM objects and browser events. Accordingly their website the performance is similar to cpython : https://brython.info/speed_results.html

[mad-moo]

That's planned, though for the more distant future. We'd like to allow moving over some events to the client side by running Python in the browser. This would allow reacting to events without the round-trip delay.

Performance isn't really relevant here, because the big savings are from avoiding network latency. I'd also expect most event handlers to just set a couple properties and return.

[mad-moo]

I've implemented this. It's going through testing now 👌

[felipetesc]

Hi. Another topic which could improve Rio is the addition of more sophisticated ways to create animations. I've read at https://rio.dev/docs/api/rectangle that Rectangles are used for that. However if Rio can include a new Component such as Animation where we could use things like treejs, animejs, snapjs, it would be really interesting. The Animation class could use SVG animations to change their scalar attributes, so we could pass Icons.

[mad-moo]

Yeah, animations are very limited right now. If you know of a nice API to fits into Rio we're all ears.

I don't want to use JS libraries for this. That'd go totally against what Rio is trying to do - create a pythonic interface that needs to JS knowledge.

[felipetesc]

Another thing I'm really missing is the fixed attribute to position divs. I know I can use Stack, but it lacks the independence fixed value gives with html.

[mad-moo]

Can you give an example of what you're looking for?

[mad-moo]

Let's keep this conversation focused on extensions please. If you're looking for additional features create a new discussion or issue!