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: state: the State instance of the caller. path: the path provided to the get_user_content_url() to build the URL. parameters: An optional dictionary as defined in the get_user_content_url() call. 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.