config

plantimager.webui.config

PlantDB Configuration Interface for Plant Imager Web UI.

This module provides components and callbacks for configuring the connection to the PlantDB API and managing datasets within the Plant Imager web interface.

Key Features

• PlantDB API connection configuration and testing
• Dataset listing and management
• Dynamic UI components for database status visualization
• Bootstrap-styled modals and alerts for user interaction

Environment variables

• ALLOW_PRIVATE_IP: if True, allow the use of private IPs for PlantDB REST API URL
• CERT_PATH: specify the path to the self-signed certificates used by the PlantDB server.
• VALIDATE_HOST: if True, check the PlantDB REST API URL against a blacklist

check_server_availability

check_server_availability(_, host, port, prefix, ssl, stored_host, stored_port, stored_prefix, stored_ssl)

Checks the availability of a server based on the provided host and port and updates the UI accordingly.

Parameters:

Name	Type	Description	Default
_	int	The n_clicks property of the load-plantdb-button element, which triggers the callback (not used).	required
host	str	The IP address or hostname of the server to test.	required
port	int	The port number of the server to test.	required
prefix	str	The URL prefix of the server to test.	required
ssl	bool	Flag indicating whether SSL (HTTPS) is enabled.	required
stored_host	str	The previously stored server host value, used if the connection test fails.	required
stored_port	int	The previously stored server port value, used if the connection test fails.	required
stored_prefix	str	The previously stored server prefix value, used if the connection test fails.	required
stored_ssl	bool	The previously stored server SSL flag, used if the connection test fails.	required

Returns:

Type	Description
bool	A flag indicating whether the server is available.
bool	A boolean indicating whether the load button should be disabled.
str	The updated server host value to store.
int	The updated server port value to store.
str	The updated server prefix value to store.
bool	The updated server SSL flag value to store.
bool	Whether the modal-close-interval should be disabled.
int	Reset n_intervals to 0 to restart the timer.

Source code in plantimager/webui/config.py

@callback(
    Output('connected', 'data'),
    Output('load-plantdb-button', 'disabled'),
    Output('plantdb-host', 'data'),
    Output('plantdb-port', 'data'),
    Output('plantdb-prefix', 'data'),
    Output('plantdb-ssl', 'data'),
    Output('modal-close-interval', 'disabled'),
    Output('modal-close-interval', 'n_intervals'),
    Input('connect-plantdb-button', 'n_clicks'),
    State('api-address', 'value'),
    State('api-port', 'value'),
    State('api-prefix', 'value'),
    State('api-ssl', 'value'),
    State('plantdb-host', 'data'),
    State('plantdb-port', 'data'),
    State('plantdb-prefix', 'data'),
    State('plantdb-ssl', 'data'),
)
def check_server_availability(
        _: int,
        host: str | None,
        port: int | str | None,
        prefix: str | None,
        ssl: bool | None,
        stored_host: str,
        stored_port: int,
        stored_prefix: str,
        stored_ssl: bool,
) -> tuple[bool, bool, str, int, str, bool, bool, int]:
    """Checks the availability of a server based on the provided host and port and updates the UI accordingly.

    Parameters
    ----------
    _ : int
        The n_clicks property of the load-plantdb-button element, which triggers the callback (not used).
    host : str
        The IP address or hostname of the server to test.
    port : int
        The port number of the server to test.
    prefix : str
        The URL prefix of the server to test.
    ssl : bool
        Flag indicating whether SSL (HTTPS) is enabled.
    stored_host : str
        The previously stored server host value, used if the connection test fails.
    stored_port : int
        The previously stored server port value, used if the connection test fails.
    stored_prefix : str
        The previously stored server prefix value, used if the connection test fails.
    stored_ssl : bool
        The previously stored server SSL flag, used if the connection test fails.

    Returns
    -------
    bool
        A flag indicating whether the server is available.
    bool
        A boolean indicating whether the load button should be disabled.
    str
        The updated server host value to store.
    int
        The updated server port value to store.
    str
        The updated server prefix value to store.
    bool
        The updated server SSL flag value to store.
    bool
        Whether the modal-close-interval should be disabled.
    int
        Reset n_intervals to 0 to restart the timer.
    """
    if host is None:
        host = stored_host
    if port is None:
        port = stored_port
    if prefix is None:
        prefix = stored_prefix
    if ssl is None:
        ssl = stored_ssl

    # Handle URLs that include a protocol prefix
    if host and isinstance(host, str):
        if host.startswith("http://"):
            host = host[7:]
            ssl = False
        elif host.startswith("https://"):
            host = host[8:]
            ssl = True

    if server_available(host, port, prefix, ssl):
        # Server is available: enable load button, enable interval timer
        return True, False, host, port, prefix, ssl, False, 0
    else:
        # Server is not available: disable load button, disable interval timer
        return False, True, host, port, prefix, ssl, True, 0

create_dataset_cfg_icon

create_dataset_cfg_icon(is_connected=False, dataset_list=None)

Create a navigation link with the database status icon and dataset counter badge.

Creates a Bootstrap NavLink component that displays a database status icon and a badge showing the number of datasets. The icon changes appearance based on connection status.

Parameters:

Name	Type	Description	Default
is_connected	bool	Flag indicating whether the database connection is established, by default False	False
dataset_list	list	List of datasets to count, by default empty list	None

Returns:

Type	Description
NavLink	A navigation link component containing: - Database status icon - Badge showing dataset count The NavLink is styled and positioned according to the application's design.

Source code in plantimager/webui/config.py

def create_dataset_cfg_icon(is_connected: bool = False, dataset_list: list | None = None) -> dbc.NavLink:
    """Create a navigation link with the database status icon and dataset counter badge.

    Creates a Bootstrap NavLink component that displays a database status icon and
    a badge showing the number of datasets. The icon changes appearance based on
    connection status.

    Parameters
    ----------
    is_connected : bool, optional
        Flag indicating whether the database connection is established,
        by default False
    dataset_list : list, optional
        List of datasets to count, by default empty list

    Returns
    -------
    dash.bootstrap_components.NavLink
        A navigation link component containing:
        - Database status icon
        - Badge showing dataset count
        The NavLink is styled and positioned according to the application's design.
    """
    if dataset_list is None:
        dataset_list = []
    return dbc.NavLink(
        children=[
            dataset_cfg_status(is_connected),
            dbc.Badge(
                children=f"{len(dataset_list)}",
                id="dataset-count-badge",
                color="primary",
                className="position-absolute top-45 start-100 translate-middle",
                pill=True
            )
        ],
        id='plantdb-cfg-button',
        n_clicks=0,
        className="position-relative align-left",
        style={'color': "#f3f3f3"},
    )

dataset_cfg_status

dataset_cfg_status(is_connected)

Generate a database status icon based on the connection state.

Creates a Bootstrap icon element representing the database connection status. Returns a check icon when connected and a gear icon when disconnected.

Parameters:

Name	Type	Description	Default
is_connected	bool	Flag indicating whether the database connection is established.	required

Returns:

Type	Description
I	A Bootstrap icon component with the appropriate class based on connection status.

Source code in plantimager/webui/config.py

def dataset_cfg_status(is_connected: bool) -> html.I:
    """Generate a database status icon based on the connection state.

    Creates a Bootstrap icon element representing the database connection status.
    Returns a check icon when connected and a gear icon when disconnected.

    Parameters
    ----------
    is_connected : bool
        Flag indicating whether the database connection is established.

    Returns
    -------
    dash.html.I
        A Bootstrap icon component with the appropriate class based on connection status.
    """
    if is_connected:
        return html.I(className="bi bi-database-check fs-3")
    else:
        return html.I(className="bi bi-database-gear fs-3")

server_available

server_available(host, port, prefix, ssl)

Checks the availability of a server.

Parameters:

Name	Type	Description	Default
host	str	The IP address or hostname of the server to test.	required
port	int	The port number of the server to test.	required
prefix	str	The URL prefix of the server to test.	required
ssl	bool	Flag indicating whether SSL (HTTPS) is enabled.	required

Returns:

Type	Description
bool	A flag indicating whether the server is available.

Source code in plantimager/webui/config.py

def server_available(host, port, prefix, ssl):
    """Checks the availability of a server.

    Parameters
    ----------
    host : str
        The IP address or hostname of the server to test.
    port : int
        The port number of the server to test.
    prefix : str
        The URL prefix of the server to test.
    ssl : bool
        Flag indicating whether SSL (HTTPS) is enabled.

    Returns
    -------
    bool
        A flag indicating whether the server is available.
    """
    allow_private_ip = os.getenv('ALLOW_PRIVATE_IP', 'false').lower() == 'true'
    cert_path = os.getenv('CERT_PATH', None)
    validate_host = os.getenv('VALIDATE_HOST', 'true').lower() == 'true'
    try:
        url = plantdb_url(host, port=port, prefix=prefix, ssl=ssl)
        availability = is_server_available(url, allow_private_ip=allow_private_ip,
                                           cert_path=cert_path, validate_host=validate_host)
    except:
        is_available = False
    else:
        is_available = availability.ok
    return is_available

show_api_address

show_api_address(modal_is_open, stored_host)

Callback updating the value of the 'api-address' field with stored data when opening the PlantDB configuration modal.

Parameters:

Name	Type	Description	Default
modal_is_open	bool	Indicates whether the configuration modal is currently open.	required
stored_host	str or None	The stored value of the PlantDB API host. Can be None if not previously set.	required

Returns:

Type	Description
str	The IP address to be used, either the stored host value or the PLANTDB_HOST constant.

Source code in plantimager/webui/config.py

@callback(
    Output('api-address', 'value'),
    Input('plantdb-cfg-modal', 'is_open'),
    State('plantdb-host', 'data')
)
def show_api_address(modal_is_open: bool, stored_host: str | None) -> str:
    """Callback updating the value of the 'api-address' field with stored data when opening the PlantDB configuration modal.

    Parameters
    ----------
    modal_is_open : bool
        Indicates whether the configuration modal is currently open.
    stored_host : str or None
        The stored value of the PlantDB API host. Can be ``None`` if not previously set.

    Returns
    -------
    str
        The IP address to be used, either the stored host value or the ``PLANTDB_HOST`` constant.
    """
    if modal_is_open:
        return stored_host if stored_host is not None else PLANTDB_HOST
    else:
        return stored_host

show_api_port

show_api_port(modal_is_open, stored_port)

Callback updating the value of the 'api-port' field with stored data when opening the PlantDB configuration modal.

Parameters:

Name	Type	Description	Default
modal_is_open	bool	Boolean indicating whether the configuration modal is open or closed.	required
stored_port	str or None	Stored port value retrieved from the state. Can be None if not specified.	required

Returns:

Type	Description
str	Value to be set for the "api-port" input field, either the stored port value or the PLANTDB_PORT constant.

Source code in plantimager/webui/config.py

@callback(
    Output('api-port', 'value'),
    Input('plantdb-cfg-modal', 'is_open'),
    State('plantdb-port', 'data')
)
def show_api_port(modal_is_open: bool, stored_port: int | None) -> int | str:
    """Callback updating the value of the 'api-port' field with stored data when opening the PlantDB configuration modal.

    Parameters
    ----------
    modal_is_open : bool
        Boolean indicating whether the configuration modal is open or closed.
    stored_port : str or None
        Stored port value retrieved from the state. Can be ``None`` if not specified.

    Returns
    -------
    str
        Value to be set for the "api-port" input field, either the stored port value or the ``PLANTDB_PORT`` constant.
    """
    if modal_is_open:
        return stored_port if stored_port is not None else PLANTDB_PORT
    else:
        return stored_port

show_api_prefix

show_api_prefix(modal_is_open, stored_prefix)

Callback updating the value of the 'api-prefix' field with stored data when opening the PlantDB configuration modal.

Parameters:

Name	Type	Description	Default
modal_is_open	bool	Boolean indicating whether the configuration modal is open or closed.	required
stored_prefix	str or None	Stored prefix value retrieved from the state. Can be None if not specified.	required

Returns:

Type	Description
str	Value to be set for the "api-prefix" input field.

Source code in plantimager/webui/config.py

@callback(
    Output('api-prefix', 'value'),
    Input('plantdb-cfg-modal', 'is_open'),
    State('plantdb-prefix', 'data')
)
def show_api_prefix(modal_is_open: bool, stored_prefix: str | None) -> int | str:
    """Callback updating the value of the 'api-prefix' field with stored data when opening the PlantDB configuration modal.

    Parameters
    ----------
    modal_is_open : bool
        Boolean indicating whether the configuration modal is open or closed.
    stored_prefix : str or None
        Stored prefix value retrieved from the state. Can be ``None`` if not specified.

    Returns
    -------
    str
        Value to be set for the "api-prefix" input field.
    """
    if modal_is_open:
        return stored_prefix if stored_prefix is not None else ""
    else:
        return stored_prefix

show_api_ssl

show_api_ssl(modal_is_open, stored_ssl)

Callback updating the value of the 'api-ssl' checkbox with stored data when opening the PlantDB configuration modal.

Parameters:

Name	Type	Description	Default
modal_is_open	bool	Boolean indicating whether the configuration modal is open or closed.	required
stored_ssl	bool or None	Stored SSL flag retrieved from the state. Can be None if not specified.	required

Returns:

Type	Description
bool	Value to be set for the "api-ssl" checkbox.

Source code in plantimager/webui/config.py

@callback(
    Output('api-ssl', 'value'),
    Input('plantdb-cfg-modal', 'is_open'),
    State('plantdb-ssl', 'data')
)
def show_api_ssl(modal_is_open: bool, stored_ssl: bool | None) -> bool:
    """Callback updating the value of the 'api-ssl' checkbox with stored data when opening the PlantDB configuration modal.

    Parameters
    ----------
    modal_is_open : bool
        Boolean indicating whether the configuration modal is open or closed.
    stored_ssl : bool or None
        Stored SSL flag retrieved from the state. Can be ``None`` if not specified.

    Returns
    -------
    bool
        Value to be set for the "api-ssl" checkbox.
    """
    if modal_is_open:
        return stored_ssl if stored_ssl is not None else False
    else:
        return stored_ssl

show_plantdb_status

show_plantdb_status(status, host, port, prefix, ssl)

Display the connection status of the PlantDB server in a Bootstrap alert component.

This callback function generates a styled alert component that shows whether the PlantDB server is available or not. The alert includes an icon and descriptive text with the server's host and port information when applicable.

Parameters:

Name	Type	Description	Default
status	bool or None	Connection status of the PlantDB server: - None: status unknown - True: server is available - False: server is unavailable	required
host	str	Hostname or IP address of the PlantDB server	required
port	int	Port number of the PlantDB server	required
prefix	str	URL prefix of the PlantDB server	required
ssl	bool	Flag indicating whether SSL (HTTPS) is enabled	required

Returns:

Type	Description
Alert	A Bootstrap alert component with the appropriate styling and message based on the connection status: - Info (blue): when status is unknown - Success (green): when server is available - Danger (red): when server is unavailable

Source code in plantimager/webui/config.py

@callback(
    Output('plantdb-status-form', 'children'),
    Input('connected', 'data'),
    State('plantdb-host', 'data'),
    State('plantdb-port', 'data'),
    State('plantdb-prefix', 'data'),
    State('plantdb-ssl', 'data'),
)
def show_plantdb_status(status: bool | None, host: str, port: int, prefix: str, ssl: bool) -> dbc.Alert:
    """Display the connection status of the PlantDB server in a Bootstrap alert component.

    This callback function generates a styled alert component that shows whether the
    PlantDB server is available or not. The alert includes an icon and descriptive text
    with the server's host and port information when applicable.

    Parameters
    ----------
    status : bool or None
        Connection status of the PlantDB server:
        - ``None``: status unknown
        - ``True``: server is available
        - ``False``: server is unavailable
    host : str
        Hostname or IP address of the PlantDB server
    port : int
        Port number of the PlantDB server
    prefix : str
        URL prefix of the PlantDB server
    ssl : bool
        Flag indicating whether SSL (HTTPS) is enabled

    Returns
    -------
    dash_bootstrap_components.Alert
        A Bootstrap alert component with the appropriate styling and message based on
        the connection status:
        - Info (blue): when status is unknown
        - Success (green): when server is available
        - Danger (red): when server is unavailable
    """
    if status is None:
        status_form = dbc.Alert(children=[
            html.I(className="bi bi-info-circle-fill me-2"),
            "Unknown server availability."
        ], color="info")
    elif status:
        status_form = dbc.Alert(children=[
            html.I(className="bi bi-check-circle-fill me-2"),
            f"Server {plantdb_url(host, port=port, prefix=prefix, ssl=ssl)} available.",
        ], color="success")
    else:
        status_form = dbc.Alert(children=[
            html.I(className="bi bi-x-octagon-fill me-2"),
            f"Server {plantdb_url(host, port=port, prefix=prefix, ssl=ssl)} unavailable!",
        ], color="danger")
    return status_form

toggle_plantdb_cfg_modal

toggle_plantdb_cfg_modal(cfg_clicks, n_intervals, is_open)

Toggle the visibility state of the PlantDB configuration modal.

This callback function controls the opening and closing of the PlantDB configuration modal dialog. It is triggered by: 1. clicking the configuration button (opens modal) 2. the interval timer (closes modal after successful connection)

Parameters:

Name	Type	Description	Default
cfg_clicks	int	Number of times the plantdb-cfg-button has been clicked.	required
n_intervals	int	Number of intervals elapsed (for auto-close after successful connection).	required
is_open	bool	Current visibility state of the modal.	required

Returns:

Type	Description
bool	The new visibility state of the modal.

Source code in plantimager/webui/config.py

@callback(Output('plantdb-cfg-modal', 'is_open'),
          Input('plantdb-cfg-button', 'n_clicks'),
          Input('modal-close-interval', 'n_intervals'),
          State('plantdb-cfg-modal', 'is_open'),
          prevent_initial_call=True)
def toggle_plantdb_cfg_modal(
        cfg_clicks: int,
        n_intervals: int,
        is_open: bool
) -> bool:
    """Toggle the visibility state of the PlantDB configuration modal.

    This callback function controls the opening and closing of the PlantDB configuration
    modal dialog. It is triggered by:
    1. clicking the configuration button (opens modal)
    2. the interval timer (closes modal after successful connection)

    Parameters
    ----------
    cfg_clicks : int
        Number of times the plantdb-cfg-button has been clicked.
    n_intervals : int
        Number of intervals elapsed (for auto-close after successful connection).
    is_open : bool
        Current visibility state of the modal.

    Returns
    -------
    bool
        The new visibility state of the modal.
    """
    triggered_id = ctx.triggered_id

    # The configuration button was clicked - toggle modal
    if triggered_id == 'plantdb-cfg-button':
        return not is_open

    # The interval timer fired - close the modal (only fires after successful connection)
    elif triggered_id == 'modal-close-interval':
        return False

    return no_update

update_dataset_badge

update_dataset_badge(dataset_list)

Update the dataset count badge with the current number of datasets.

This callback function updates a badge element in the UI to display the total number of datasets currently available in the system. It converts the length of the dataset list to a string for display.

Parameters:

Name	Type	Description	Default
dataset_list	list	A list containing the dataset names stored in the dcc.Store component.	required

Returns:

Type	Description
str	String representation of the number of datasets in the list.

Source code in plantimager/webui/config.py

@callback(
    Output('dataset-count-badge', 'children'),
    Input('dataset-list', 'data')  # Assuming you have a dataset list stored in dcc.Store
)
def update_dataset_badge(dataset_list: list) -> str:
    """Update the dataset count badge with the current number of datasets.

    This callback function updates a badge element in the UI to display the total
    number of datasets currently available in the system. It converts the length
    of the dataset list to a string for display.

    Parameters
    ----------
    dataset_list : list
        A list containing the dataset names stored in the dcc.Store component.

    Returns
    -------
    str
        String representation of the number of datasets in the list.
    """
    return str(len(dataset_list))

update_dataset_list

update_dataset_list(n_clicks, connected, host, port, prefix, ssl, access_token)

Callback updating the dataset list and displaying the load status when a user clicks the load button.

Parameters:

Name	Type	Description	Default
n_clicks	int	The n_clicks property of the load-plantdb-button element, which triggers the callback (not used).	required
connected	bool	The connection status of the PlantDB API server.	required
host	str	The hostname or IP address of the PlantDB API server.	required
port	int	The port number of the PlantDB API server.	required
prefix	str	The prefix of the PlantDB API server.	required
ssl	bool	Flag indicating whether SSL (HTTPS) is enabled.	required

Returns:

Type	Description
Alert	An alert component indicating success or failure of dataset retrieval.
list of str	A list of dataset names retrieved from the server.

Source code in plantimager/webui/config.py

@callback(
    Output('load-status-form', 'children'),
    Output('dataset-list', 'data'),
    Input('load-plantdb-button', 'n_clicks'),
    Input('connected', 'data'),
    State('plantdb-host', 'data'),
    State('plantdb-port', 'data'),
    State('plantdb-prefix', 'data'),
    State('plantdb-ssl', 'data'),
    State('access-token', 'data'),
    prevent_initial_call=True,
)
def update_dataset_list(
        n_clicks: int,
        connected: bool | None,
        host: str,
        port: int | str,
        prefix: str,
        ssl: bool,
        access_token: str,
) -> tuple[dbc.Alert, list[str]]:
    """Callback updating the dataset list and displaying the load status when a user clicks the load button.

    Parameters
    ----------
    n_clicks : int
        The n_clicks property of the load-plantdb-button element, which triggers the callback (not used).
    connected : bool
        The connection status of the PlantDB API server.
    host : str
       The hostname or IP address of the PlantDB API server.
    port : int
        The port number of the PlantDB API server.
    prefix : str
        The prefix of the PlantDB API server.
    ssl : bool
        Flag indicating whether SSL (HTTPS) is enabled.

    Returns
    -------
    dash_bootstrap_components.Alert
        An alert component indicating success or failure of dataset retrieval.
    list of str
        A list of dataset names retrieved from the server.
    """
    error = ""
    if not connected:
        error = "PlantDB API server not connected."
        return _unconnected_status(error=error), []

    try:
        dataset_list = sorted(request_scan_names_list(host, port=port, prefix=prefix, ssl=ssl,
                                                      session_token=access_token))
    except RequestException as e:
        dataset_list = []
        error = e

    if dataset_list:
        status = _connected_status(dataset_list)
    else:
        status = _unconnected_status(error=error)

    return status, dataset_list

update_plantdb_cfg_button

update_plantdb_cfg_button(status, dataset_list)

Update the PlantDB configuration button's appearance based on connection status.

This callback function updates the visual representation of the PlantDB configuration button in the navigation bar depending on the connection status and dataset list state. It uses the create_dataset_cfg_icon function to generate the appropriate icon.

Parameters:

Name	Type	Description	Default
status	bool or None	The connection status to the PlantDB API. None indicates no connection attempt has been made. True indicates a successful connection. False indicates a failed connection.	required
dataset_list	list or None	List of available datasets from the PlantDB. None if no datasets are loaded or connection is not established.	required

Returns:

Type	Description
NavLink	A Dash HTML component representing the configuration button icon with the appropriate styling based on the connection status.

Source code in plantimager/webui/config.py

@callback(
    Output('plantdb-cfg-button', 'children'),
    Input('connected', 'data'),
    State('dataset-list', 'data'),
)
def update_plantdb_cfg_button(status: bool | None, dataset_list: list | None) -> NavLink:
    """Update the PlantDB configuration button's appearance based on connection status.

    This callback function updates the visual representation of the PlantDB configuration
    button in the navigation bar depending on the connection status and dataset list state.
    It uses the create_dataset_cfg_icon function to generate the appropriate icon.

    Parameters
    ----------
    status : bool or None
        The connection status to the PlantDB API.
        ``None`` indicates no connection attempt has been made.
        ``True`` indicates a successful connection.
        ``False`` indicates a failed connection.
    dataset_list : list or None
        List of available datasets from the PlantDB.
        ``None`` if no datasets are loaded or connection is not established.

    Returns
    -------
    dash_bootstrap_components.NavLink
        A Dash HTML component representing the configuration button icon
        with the appropriate styling based on the connection status.
    """
    return create_dataset_cfg_icon(status, dataset_list)