From 448c88ea41b41e8ce856c966a34d52baaadfbc1c Mon Sep 17 00:00:00 2001 From: appel_c Date: Tue, 14 Jan 2025 08:13:46 +0100 Subject: [PATCH] docs: add docs for client info message and live updates config --- bec_lib/bec_lib/redis_connector.py | 10 +++- .../plugin_setup_files/pre_startup.py | 7 --- .../developer/user_interfaces/bec_cli.md | 51 ++++++++++++++++++- 3 files changed, 57 insertions(+), 11 deletions(-) diff --git a/bec_lib/bec_lib/redis_connector.py b/bec_lib/bec_lib/redis_connector.py index 0f1f5e56..1d5873f9 100644 --- a/bec_lib/bec_lib/redis_connector.py +++ b/bec_lib/bec_lib/redis_connector.py @@ -246,7 +246,7 @@ class RedisConnector(ConnectorBase): def send_client_info( self, message: str, - rid: str = None, + show_asap: bool = False, source: Literal[ "bec_ipython_client", "scan_server", @@ -258,8 +258,8 @@ class RedisConnector(ConnectorBase): None, ] = None, severity: int = 0, - show_asap: bool = False, scope: str = None, + rid: str = None, metadata: dict = None, ): """ @@ -267,6 +267,12 @@ class RedisConnector(ConnectorBase): Args: msg (str): message + show_asap (bool, optional): show asap. Defaults to False. + source (Literal[str], optional): Any of the services: "bec_ipython_client", "scan_server", "device_server", "scan_bundler", "file_writer", "scihub", "dap". Defaults to None. + severity (int, optional): severity. Defaults to 0. + rid (str, optional): request ID. Defaults to None. + scope (str, optional): scope. Defaults to None. + metadata (dict, optional): metadata. Defaults to None. """ client_msg = ClientInfoMessage( message=message, diff --git a/bec_lib/util_scripts/plugin_setup_files/pre_startup.py b/bec_lib/util_scripts/plugin_setup_files/pre_startup.py index e22e554a..868c2c90 100644 --- a/bec_lib/util_scripts/plugin_setup_files/pre_startup.py +++ b/bec_lib/util_scripts/plugin_setup_files/pre_startup.py @@ -14,10 +14,3 @@ def extend_command_line_args(parser): # parser.add_argument("--session", help="Session name", type=str, default="cSAXS") return parser - - -# def get_config() -> ServiceConfig: -# """ -# Create and return the service configuration. -# """ -# return ServiceConfig(redis={"host": "localhost", "port": 6379}) diff --git a/docs/source/developer/user_interfaces/bec_cli.md b/docs/source/developer/user_interfaces/bec_cli.md index 97dc5648..2d0b0091 100644 --- a/docs/source/developer/user_interfaces/bec_cli.md +++ b/docs/source/developer/user_interfaces/bec_cli.md @@ -1,5 +1,52 @@ (developer.bec_cli)= # Command-line interface (CLI) -Coming soon... -In the meantime, have a look at the CLI documentation in the [user section](user.command_line_interface). \ No newline at end of file +BEC provides a command-line interface (CLI) as an interface for users to interact with the BEC server. The CLI is based on the [*IPython*](https://ipython.readthedocs.io/en/stable/) interactive shell, which provides a powerful and flexible environment for users to interact with the BEC server. To get an idea of the capabilities of the CLI, have a look at the [user section](user.command_line_interface). + +## Customizing the CLI +There are several ways to customize the CLI to suit your needs. BEC allows users to define pre- and post-startup scripts that are executed before and after the CLI is started. These extensions are implemented through [*BEC plugin*](developer.bec_plugins), more specifically within the *bec_ipython_client/startup* module. + +**Pre-startup script**: The pre-startup script can be used to extend the command line arguments for starting the CLI. For example, you can add a custom session name to the CLI that allows to identify the session in the post-startup script, i.e. + +```bash +bec --session my_session +``` +````{dropdown} View code: Pre-startup script +:icon: code-square +:animate: fade-in-slide-down + +```{literalinclude} ../../../../bec_lib/util_scripts/plugin_setup_files/pre_startup.py +:language: python +``` +```` + +**Post-startup script**: The post-startup script will be executed after the CLI is started. This script allows you to customize the CLI environment, e.g. by loading custom Python modules, setting reusable variables, or creating fully customized objects that represent experimental setups. + +````{dropdown} View code: Post-startup script +:icon: code-square +:animate: fade-in-slide-down + +```{literalinclude} ../../../../bec_lib/util_scripts/plugin_setup_files/post_startup.py +:language: python +``` +```` + +### Customizing CLI print behaviour +We also allow you to dynamically change the printed output of the CLI by adjusting the variables of the live updates config object. This includes the live table printout and the client-info messages. You can adjust the following variables in the *bec.live_updates_config* object: + +```python +bec.live_updates_config.print_live_table = False #True +bec.live_updates_config.print_client_info = False #True +``` + +**Client-Info messages**: The *RedisConnector* class provides a method to print client-info messages to the CLI. These messages can be send from any service or device, and will be printed in the CLI either immediately (show_asap=True) or at the end of a scan. Please keep in mind that all services have access to the *RedisConnector* class, and can send client-info messages to the CLI. + +``` python +from bec_lib.redis_connector import RedisConnector +bootstrap = "localhost:6379" +connector = RedisConnector(bootstrap) +connector.send_client_info(message="This is a client info message", show_asap=True) +``` + + +