Use of main guard and behavioural differences between 3.0.2 v 2.24.2

[LeoM1970]

First off, thank you for a wonderful, and rapidly evolving GUI framework.

The below minimal code works as expected in v2.24.2, but renders a blank page in v3.0.2... I can't claim to understand why.

from nicegui import ui


def gui_layout():
    ui.label("This is a test...")


if __name__ in {"__main__", "__mp_main__"}:
    gui_layout()
    ui.run()

I can get the code to work by removing the main guard...:

 from nicegui import ui


def gui_layout():
    ui.label("This is a test...")


gui_layout()
ui.run()

.. But I am a little finicky with some Python conventions and prefer to use the main guard. I managed to reintroduce it and get the code to work by moving the main function outside of it:

from nicegui import ui


def gui_layout():
    ui.label("This is a test...")


gui_layout()

if __name__ in {"__main__", "__mp_main__"}:
    ui.run()

Could you please shed some light on the new behaviour upon the upgrade? I read the migration guidance but perhaps some of your advice passed me by due to my inexperience.

Is there a way to keep the main function inside the main guard and render the page as expected in v3.0.2, or is this no longer possible?

Thank you in advance.

[falkoschindler]

Hi @LeoM1970,

Let me try to explain:

Before 3.0 NiceGUI created a so-called "auto-index client" as soon as the library got imported. Every UI element in your script that was created in global scope (not within a page function), was added to this client. Finally, ui.run started the server and requests to "/" received a rendering of the auto-index client.

Having a long-living shared client caused quite some problems, see #4472 (comment). Therefore we wanted to remove it and enforce page functions everywhere.

But the possibility to write a "Hello NiceGUI" app in just three lines of code was very compelling. More importantly, most online demos and code snippets everywhere on the internet don't use page functions. Requiring them would break too many apps and confuse users, so we were looking for an alternative.

Now in 3.0 we have a so-called "script mode". The code looks like before, but it works quite differently. When evaluating the script, NiceGUI notices UI elements outside of page functions. There is no client, so it decides to run in "script mode" and creates a temporary throw-away client to hold all UI elements. When it reaches ui.run, it re-evaluates the whole script wrapped in a page function. Most simple scripts will just work as if you had wrapped them in a page yourself. In some situations though, it can break. Then you can simply add an index page yourself.

So you can either write

from nicegui import ui

@ui.page('/')
def page():
    ui.label('This is a test...')

if __name__ in {'__main__', '__mp_main__'}:
    ui.run()

or use the new root parameter:

from nicegui import ui

def gui_layout():
    ui.label('This is a test...')

if __name__ in {'__main__', '__mp_main__'}:
    ui.run(root=gui_layout)

Both will create a proper index page without running in script mode.

[LeoM1970]

Thank you @falkoschindler for your detailed explanation!

More importantly, most online demos and code snippets everywhere on the internet don't use page functions.

Indeed! I was able to build a couple of dozen small NiceGUI apps without ever using @ui.page.

Keep up this great work.