Rio 0.10

It's been two months since the previous release, and 0.10 is a big one. The team has been busy, and we've got a lot to cover. Let's dive into the highlights of this release.

Major Highlights 🌟

Reworked Routing 🗺️

Rio now automatically detects your app's pages! Instead of specifying each page during app creation simply place your Python files in the "pages" directory and annotate components with @rio.page(...). Rio will scan the directory and add all annotated components to your app.

This change simplifies page management and follows our philosophy of making Rio user-friendly. If this does not work for you (for example,
because you want to add pages dynamically) the old system absolutely still works and isn't going anywhere.

A new kind of page has also been added: rio.Redirect allows to to add a page to your app that will immediately redirect to another page. This has always been possible with page guards, but the new system is more explicit and more convenient.

Page guards have also received a small update. Previously they were passed multiple parameters which cluttered up their signature. We've changed this to a single rio.GuardEvent object that contains all the information you need. This allows us to add more information in the future without breaking existing code.

To round it all out, any app with two or more pages will now have a default navigation added. This will help you get around during development and can easily be replaced by assigning your own navigation to the app's build callback. Learn more here.

Improved Parameter Naming 🏷️

We've seen some confusion around the naming of parameters in previous releases and have taken this opportunity to make several changes to clarify parameter names. The most prominent change are the width and height parameters.

Previously these would either accept a single number, or the literal "grow" to indicate that a component would like additional space. This has now been split into two values instead:

• min_width and min_height control the minimum size of a component. This allows you to force components to be larger than they would be based on their content.

• grow_x and grow_y correspond to the previous width="grow" and height="grow" respectively. As before, these will cause components to be prioritized when superfluous space is available.

To upgrade to the new system just apply a few simple replacements:

• width=123 -> min_width=123
• width="grow" -> grow_x=True
• height=123 -> min_height=123
• height="grow" -> grow_y=True

That's it! Even better, the old parameters will continue to work for now, and emit a warning in the terminal to remind you to update your code.

Other name changes include:

• rio.Text.wrap has been renamed to rio.Text.overflow. This avoids the confusing case of wrap="ellipsize".

• rio.Session.file_chooser is now rio.Session.pick_file

• rio.Page is now rio.ComponentPage. This is to avoid confusion with the lowercase @rio.page decorator.

• rio.Page.page_url is now called rio.ComponentPage.url_segment. This makes it clearer that only one segment should be specified, and not the entire URL.

• The plain style of rio.Button is now called plain-text. This separates it clearly from the new colored-text style.

Again, all old names will continue to work for the near future. We recommend slowly switching to the new names as you work on your app.

Dialogs 🗨️

Dialogs have finally arrived! These have been often requested and for good reason. They're a great way to ask users for input, confirm actions, or just display information in a way that doesn't require a new page.

The easiest way to do so is using the show_yes_no_dialog method available in the session. In just a few lines of code you can ask users a simple yes/no question and wait for them to respond

ice_cream_lover = await self.session.show_yes_no_dialog(
    title="This is a Dialog",
    text="Do you like ice cream?",
)

Of course, you can also provide completely custom content. This is a little more involved, so check out the documentation of rio.Session.show_custom_dialog for a full example.

We're also working on another convenience function that will allow you to create dialogs with arbitrary buttons, without having to create your own component. The API for this one is still unclear, so it will drop in a future release.

(If you're coming from a pre-release rather than the previous stable version, please note that dialogs have moved from rio.Component to rio.Session.)

Support for Base URLs 🌐

Rio now has experimental support for custom base URLs. This means you can host your Rio app in a subdirectory of your domain, such as mysite.com/myapp. This can be useful if you're hosting multiple apps on the same domain, or if you maybe want to create an admin-cockpit for your server that isn't the main application for users to see.

You can set the URL in the rio run command:

python -m rio run --base-url=https://mysite.com/myapp

Remember that this is experimental for now, so please let us know if you run into any issues.

Authentication Example 🔒

We've added a new example / template to Rio that demonstrates how to implement a login system. It shows how to securely store and verify passwords, and how to use sessions to keep users logged in.

This initial version stores all passwords locally using SQLite. Support for OAuth is in the works.

You can create a project based on this template in just one line:

rio new --template authentication

API Changes 🚨

• guards: Previously, multiple parameters were passed, cluttering their signature. This has been changed to a single rio.GuardEvent object that encapsulates all necessary information.
• Several parameter names have been updated but will be deprecated in a future release.

Other Improvements ✨

• FilePickerArea: Allows file uploads through drag-and-drop functionality or by selecting files via the file browser option.
• A Chinese translation of the README has been added by @youweicheng

Up Next: The Road to Stability 🚧

You'll have noticed the unusual amount of changes in this release. This is on purpose.

Rio has matured significantly since the initial release. Most of what you'd expect from an app framework has been implemented, and the time has come where we need to stop changing things each release and instead need to start worrying about stability.

This is why we've implemented everything on our backlog that would introduce API changes in this release. It will allow us to keep the API more consistent from now on, with much less changing between releases. Think of it as a sort of "soft stable" in preparation for 1.0, which we expect to reach later this year.

This of course doesn't mean that there won't be any more improvements. We are working on support for custom components, better internal state management and plenty other updates, but we are convinced that stability and reliability need to take center stage now.

This means that we'll be focusing on bug fixes, many, many more automated tests, and documentation improvements. Our website also has several changes lined up to optimize it for mobile, as well as make documentation more accessible.

Install 🛠️

Get it from pypi: pip install --upgrade rio-ui 🌊