Skip to content

taipy.gui.Gui

Entry point for the Graphical User Interface generation.

Attributes:

Name Type Description
on_action Callable

The function that is called when a control triggers an action, as the result of an interaction with the end-user.
It defaults to the on_action() global function defined in the Python application. If there is no such function, actions will not trigger anything.
The signature of the on_action callback function must be:

  • state: the State instance of the caller.
  • id (optional): a string representing the identifier of the caller.
  • payload (optional): an optional payload from the caller.
on_change Callable

The function that is called when a control modifies variables it is bound to, as the result of an interaction with the end-user.
It defaults to the on_change() global function defined in the Python application. If there is no such function, user interactions will not trigger anything.
The signature of the on_change callback function must be:

  • state: the State instance of the caller.
  • var_name (str): The name of the variable that triggered this callback.
  • var_value (any): The new value for this variable.
on_init Callable

The function that is called on the first connection of a new client.
It defaults to the on_init() global function defined in the Python application. If there is no such function, the first connection will not trigger anything.

The signature of the on_init callback function must be:

  • state: the State instance of the caller.
on_navigate Callable

The function that is called when a page is requested.
It defaults to the on_navigate() global function defined in the Python application. If there is no such function, page requests will not trigger anything.
The signature of the on_navigate callback function must be:

  • state: the State instance of the caller.
  • page_name: the name of the page the user is navigating to.
  • params (Optional): the query parameters provided in the URL.

The on_navigate callback function must return the name of the page the user should be directed to.

on_exception Callable

The function that is called an exception occurs on user code.
It defaults to the on_exception() global function defined in the Python application. If there is no such function, exceptions will not trigger anything.
The signature of the on_exception callback function must be:

  • state: the State instance of the caller.
  • function_name: the name of the function that raised the exception.
  • exception: the exception object that was raised.
on_status Callable

The function that is called when the status page is shown.
It defaults to the on_status() global function defined in the Python application. If there is no such function, status page content shows only the status of the server.
The signature of the on_status callback function must be:

  • state: the State instance of the caller.

It must return raw and valid HTML content as a string.

on_user_content Callable

The function that is called when a specific URL (generated by get_user_content_url()) is requested.
This callback function must return the raw HTML content of the page to be displayed on the browser.

This attribute defaults to the on_user_content() global function defined in the Python application. If there is no such function, those specific URLs will not trigger anything.
The signature of the on_user_content callback function must be:

The returned HTML content can therefore use both the variables stored in the state and the parameters provided in the call to get_user_content_url().

state State

Only defined when running in an IPython notebook context.
The unique instance of State that you can use to change bound variables directly, potentially impacting the user interface in real-time.

Note

This class belongs to and is documented in the taipy.gui package but it is accessible from the top taipy package to simplify its access, allowing to use:

from taipy import Gui

__init__(page=None, pages=None, css_file=None, path_mapping=None, env_filename=None, libraries=None, flask=None)

Initialize a new Gui instance.

Parameters:

Name Type Description Default
page Optional[Union[str, Page]]

An optional Page instance that is used when there is a single page in this interface, referenced as the root page (located at /).
If page is a raw string and if it holds a path to a readable file then a Markdown page is built from the content of that file.
If page is a string that does not indicate a path to readable file then a Markdown page is built from that string.
Note that if pages is provided, those pages are added as well.

None
pages Optional[dict]

Used if you want to initialize this instance with a set of pages.
The method add_pages(pages) is called if pages is not None. You can find details on the possible values of this argument in the documentation for this method.

None
css_file Optional[str]

A pathname to a CSS file that gets used as a style sheet in all the pages.
The default value is a file that has the same base name as the Python file defining the main function, sitting next to this Python file, with the .css extension.

None
path_mapping Optional[dict]

A dictionary that associates a URL prefix to a path in the server file system.
If the assets of your application are located in /home/me/app_assets and you want to access them using only 'assets' in your application, you can set path_mapping={"assets": "/home/me/app_assets"}. If your application then requests the file "/assets/images/logo.png", the server searches for the file "/home/me/app_assets/images/logo.png".
If empty or not defined, access through the browser to all resources under the directory of the main Python file is allowed.

None
env_filename Optional[str]

An optional file from which to load application configuration variables (see the Configuration section of the User Manual for details.)
The default value is "taipy.gui.env"

None
libraries Optional[List[ElementLibrary]]

An optional list of extension library instances that pages can reference.
Using this argument is equivalent to calling add_library() for each list's elements.

None
flask Optional[Flask]

An optional instance of a Flask application object.
If this argument is set, this Gui instance will use the value of this argument as the underlying server. If omitted or set to None, this Gui will create its own Flask application instance and use it to serve the pages.

None

__pre_render_pages()

Pre-render all pages to have a proper initialization of all variables

add_library(library) staticmethod

Add a custom visual element library.

This application will be able to use custom visual elements defined in this library.

Parameters:

Name Type Description Default
library ElementLibrary

The custom visual element library to add to this application.

required

Multiple libraries with the same name can be added. This allows to split multiple custom visual elements in several ElementLibrary instances, but still refer to these elements with the same prefix in the page definitions.

add_page(name, page, style='')

Add a page to the Graphical User Interface.

Parameters:

Name Type Description Default
name str

The name of the page.

required
page Union[str, Page]

The content of the page.
It can be an instance of Markdown or Html.
If page is a string, then:

  • If page is set to the pathname of a readable file, the page content is read as Markdown input text.
  • If it is not, the page content is read from this string as Markdown text.
required
style Optional[str]

Additional CSS style to apply to this page.

  • if there is style associated with a page, it is used at a global level
  • if there is no style associated with the page, the style is cleared at a global level
  • if the page is embedded in a block control, the style is ignored
''

Note that page names cannot start with the slash ('/') character and that each page must have a unique name.

add_pages(pages=None)

Add several pages to the Graphical User Interface.

Parameters:

Name Type Description Default
pages Union[dict[str, Union[str, Page]], str]

The pages to add.
If pages is a dictionary, a page is added to this Gui instance for each of the entries in pages:

  • The entry key is used as the page name.
  • The entry value is used as the page content:
    • The value can can be an instance of Markdown or Html, then it is used as the page definition.
    • If entry value is a string, then:
      • If it is set to the pathname of a readable file, the page content is read as Markdown input text.
      • If it is not, the page content is read from this string as Markdown text.
None

Reading pages from a directory

If pages is a string that holds the path to a readable directory, then this directory is traversed, recursively, to find files that Taipy can build pages from.

For every new directory that is traversed, a new hierarchical level for pages is created.

For every file that is found:

  • If the filename extension is .md, it is read as Markdown content and a new page is created with the base name of this filename.
  • If the filename extension is .html, it is read as HTML content and a new page is created with the base name of this filename.

For example, say you have the following directory structure:

reports
├── home.html
├── budget/
│   ├── expenses/
│   │   ├── marketing.md
│   │   └── production.md
│   └── revenue/
│       ├── EMAE.md
│       ├── USA.md
│       └── ASIA.md
└── cashflow/
    ├── weekly.md
    ├── monthly.md
    └── yearly.md

Calling gui.add_pages('reports') is equivalent to calling:

gui.add_pages({
                "reports/home", Html("reports/home.html"),
                "reports/budget/expenses/marketing", Markdown("reports/budget/expenses/marketing.md"),
                "reports/budget/expenses/production", Markdown("reports/budget/expenses/production.md"),
                "reports/budget/revenue/EMAE", Markdown("reports/budget/revenue/EMAE.md"),
                "reports/budget/revenue/USA", Markdown("reports/budget/revenue/USA.md"),
                "reports/budget/revenue/ASIA", Markdown("reports/budget/revenue/ASIA.md"),
                "reports/cashflow/weekly", Markdown("reports/cashflow/weekly.md"),
                "reports/cashflow/monthly", Markdown("reports/cashflow/monthly.md"),
                "reports/cashflow/yearly", Markdown("reports/cashflow/yearly.md")
})

add_partial(page)

Create a new Partial.

The User Manual section on Partials gives details on when and how to use this class.

Parameters:

Name Type Description Default
page Union[str, Page]

The page to create a new Partial from.
It can be an instance of Markdown or Html.
If page is a string, then:

  • If page is set to the pathname of a readable file, the content of the new Partial is read as Markdown input text.
  • If it is not, the content of the new Partial is read from this string as Markdown text.
required

Returns:

Type Description
Partial

The new Partial object defined by page.

add_shared_variable(*names) staticmethod

Add shared variables.

The variables will be synchronized between all clients when updated. Note that only variables from the main module will be registered.

This is a synonym for add_shared_variables().

Parameters:

Name Type Description Default
names str

The names of the variables that become shared, as a list argument.

()

add_shared_variables(*names) staticmethod

Add shared variables.

The variables will be synchronized between all clients when updated. Note that only variables from the main module will be registered.

This is a synonym for add_shared_variable().

Parameters:

Name Type Description Default
names str

The names of the variables that become shared, as a list argument.

()

get_flask_app()

Get the internal Flask application.

This method must be called after run() was invoked.

Returns:

Type Description
Flask

The Flask instance used.

register_content_provider(content_type, content_provider) staticmethod

Add a custom content provider.

The application can use custom content for the part block when its content property is set to an object with type type.

Parameters:

Name Type Description Default
content_type type

The type of the content that triggers the content provider.

required
content_provider Callable[..., str]

The function that converts content of type type into an HTML string.

required

reload()

Reload the web server.

This function reloads the underlying web server only in the situation where it was run in a separated thread: the run_in_thread parameter to the run method was set to True, or you are running in an IPython notebook context.

run(run_server=True, run_in_thread=False, async_mode='gevent', **kwargs)

Start the server that delivers pages to web clients.

Once you enter run(), users can run web browsers and point to the web server URL that Gui serves. The default is to listen to the localhost address (127.0.0.1) on the port number 5000. However, the configuration of this Gui object may impact that (see the Configuration section of the User Manual for details).

Parameters:

Name Type Description Default
run_server bool

Whether or not to run a web server locally. If set to False, a web server is not created and started.

True
run_in_thread bool

Whether or not to run a web server in a separated thread. If set to True, the web server runs is a separated thread.
Note that if you are running in an IPython notebook context, the web server always runs in a separate thread.

False
async_mode str

The asynchronous model to use for the Flask-SocketIO. Valid values are:

  • "gevent": Use a gevent server.
  • "threading": Use the Flask Development Server. This allows the application to use the Flask reloader (the use_reloader option) and Debug mode (the debug option).
  • "eventlet": Use an eventlet event-driven WSGI server.

The default value is "gevent"
Note that only the "threading" value provides support for the development reloader functionality (use_reloader option). Any other value makes the use_reloader configuration parameter ignored.
Also note that setting the debug argument to True forces async_mode to "threading".

'gevent'
**kwargs dict[str, any]

Additional keyword arguments that configure how this Gui is run. Please refer to the Configuration section of the User Manual for more information.

{}

Returns:

Type Description
Optional[Flask]

The Flask instance if run_server is False else None.

stop()

Stop the web server.

This function stops the underlying web server only in the situation where it was run in a separated thread: the run_in_thread parameter to the run() method was set to True, or you are running in an IPython notebook context.