bec-widgets 0.99.1__py3-none-any.whl → 0.99.9__py3-none-any.whl

docs/conf.py

@@ -1,82 +0,0 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-import os
-import pathlib
-
-import tomli
-
-project = "BEC Widgets"
-copyright = "2023, Paul Scherrer Institute"
-author = "Paul Scherrer Institute"
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-current_path = pathlib.Path(__file__).parent.parent.resolve()
-version_path = f"{current_path}/pyproject.toml"
-
-
-def get_version():
-    """load the version from the version file"""
-    with open(version_path, "r", encoding="utf-8") as file:
-        res = tomli.loads(file.read())
-    return res["project"]["version"]
-
-
-release = get_version()
-
-extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    # "sphinx.ext.coverage",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",
-    "sphinx_toolbox.collapse",
-    "sphinx_copybutton",
-    "myst_parser",
-    "sphinx_design",
-    "sphinx_inline_tabs",
-]
-
-myst_enable_extensions = [
-    "amsmath",
-    "attrs_inline",
-    "colon_fence",
-    "deflist",
-    "dollarmath",
-    "fieldlist",
-    "html_admonition",
-    "html_image",
-    "replacements",
-    "smartquotes",
-    "strikethrough",
-    "substitution",
-    "tasklist",
-]
-
-autosummary_generate = True  # Turn on sphinx.ext.autosummary
-add_module_names = False  # Remove namespaces from class/method signatures
-autodoc_inherit_docstrings = True  # If no docstring, inherit from base class
-set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
-autoclass_content = "both"  # Include both class docstring and __init__
-autodoc_mock_imports = ["pyqtgraph", "qtpy", "PySide6"]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-language = "Python"
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = "pydata_sphinx_theme"
-html_static_path = ["_static"]
-html_css_files = ["custom.css"]
-html_logo = "../bec_widgets/assets/app_icons/bec_widgets_icon.png"

docs/developer/developer.md

@@ -1,52 +0,0 @@
-(developer)=
-# Developer 
-
-Welcome to the BEC Widgets developer guide! BEC Widgets is a framework for building graphical user interfaces (GUIs) for [BEC](https://bec.readthedocs.io/en/latest/), a Python package for beamline experiment control.
-
-This guide targets readers who want to develop new widgets or extend existing ones. If your goal is to use BEC Widgets to build GUIs for your experiments, please refer to the [user guide](#user).
-
-```{toctree}
----
-maxdepth: 2
-hidden: true
----
-
-introduction/introduction.md
-widget_development/widget_development.md
-api_reference/api_reference.md
-```
-
-
-***
-
-````{grid} 2
-:gutter: 5
-
-```{grid-item-card}
-:link: developer.introduction
-:link-type: ref
-:img-top: /assets/rocket_launch_48dp.svg
-:text-align: center
-:class-item: index-card
-
-## Introduction
-
-An introduction into the single-resposibility principle and the modular design of BEC Widgets.
-```
-
-```{grid-item-card}
-:link: developer.widget_development
-:link-type: ref
-:img-top: /assets/apps_48dp.svg
-:text-align: center
-:class-item: index-card
-
-## Widget Development
-
-Learn how to develop a new modular widget for BEC Widgets.
-```
-
-````{grid} 2
-
-
-

docs/developer/introduction/concepts.md

@@ -1,14 +0,0 @@
-(developer.concepts)=
-# Concepts
-This section provides an overview of the core concepts of BEC Widgets, which are based on the single-responsibility principle and modular design.
-
-## Moduler Design
-We develop widgets with the single-responsibility principle in mind, meaning each widget is designed for a specific task. Our goal is to keep widgets simple, using them primarily for visualization or to initiate actions within BEC. Following these ideas, widgets should be designed to be reusable in various applications, making them versatile building blocks for larger GUIs. 
-
-We offer up to three different options for composing larger GUIs from these modular widgets: BECDesigner, DockArea widget, or scripting from the command line interface. More information about these options can be found in the user sections on [applications](user.applications).
-
-## Client-Server Architecture
-
-BEC Widgets is built on top of the [BEC](https://bec.readthedocs.io/en/latest/) package, which provides the backend for beamline experiment control. BEC Widgets is a client of BEC, meaning it can interact with the backend through a client-server architecture. To make full usage of the available features of BEC, we recommend to check the documentation about [data access](https://bec.readthedocs.io/en/latest/developer/data_access/data_access.html) in which the messaging and event system of BEC is described.
-In the context of BEC Widgets, the [`BECDispatcher`](/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher) connects to this messaging and event system, allowing you to link your Qt [`Slots`](https://www.pythonguis.com/tutorials/pyside6-signals-slots-events/) to messages and event received from BEC.
-

docs/developer/introduction/contributing.md

@@ -1,28 +0,0 @@
-(developer.contributing)=
-# Contributing
-
-If you like to contribute to the development of BEC Widgets, you can follow the steps below to set up your development environment.
-BEC Widgets works in conjunction with [BEC](https://bec.readthedocs.io/en/latest/). 
-Therefore, we recommend that you install BEC first following the [developer instructions](https://bec.readthedocs.io/en/latest/developer/getting_started/install_developer_env.html) and include BEC Widgets. 
-
-If you already have a BEC environment set up, you can install BEC Widgets in editable mode into your BEC Python environment.
-
-**Prerequisites**
-1. **Python Version:** BEC Widgets requires Python version 3.10 or higher. Verify your Python version to ensure compatibility.
-2. **BEC Installation:** BEC Widgets works in conjunction with BEC. While BEC is a dependency and will be installed automatically, you can find more information about BEC and its installation process in the [BEC documentation](https://beamline-experiment-control.readthedocs.io/en/latest/).
-3. **Qt Distributions:** BEC Widgets supports [PySide6](https://doc.qt.io/qtforpython-6/quickstart.html) and [PyQt6](https://www.riverbankcomputing.com/static/Docs/PyQt6/introduction.html). We use [qtpy](https://pypi.org/project/QtPy/) to abstract the underlying QT distribution.
-
-**Clone the Repository**: 
-```bash
-git clone https://gitlab.psi.ch/bec/bec_widgets
-cd bec_widgets
-```
-**Install in Editable Mode**:
-
-Please install the package in editable mode into your BEC Python environemnt. 
-```bash
-pip install -e '.[dev,pyside6]'
-```
-This installs the package together with [PySide6](https://doc.qt.io/qtforpython-6/quickstart.html).
-
-

docs/developer/introduction/introduction.md

@@ -1,16 +0,0 @@
-(developer.introduction)=
-# Introduction
-BEC Widgets is a framework providing modular components that can be integrated into various larger GUI applications. Each widget serves a specific purpose adhering to the single-responsibility principle as detailed in our [concepts section](developer.concepts), and offers a straightforward, user-friendly interface.
-These widgets provide data visualisation tools and experimental control interfaces by triggering actions within BEC. 
-If you're interested in contributing to BEC Widgets, please refer to our [contributing guide](developer.contributing), which provides instructions for setting up your development environment and creating your own widgets.
-
-```{toctree}
----
-maxdepth: 2
-hidden: false
----
-
-concepts/
-contributing/
-useful_links/
-```

docs/developer/introduction/useful_links.md

@@ -1,23 +0,0 @@
-(developer.useful_links)=
-
-# Useful Links
-
-If you're new to the Qt framework, here are some helpful resources to get you started. In BEC Widgets, we use Qt
-distributions based on Qt6, specifically PyQt6 and PySide6. However, all code should be written using
-the [`qtpy`](https://pypi.org/project/QtPy/) abstraction layer, which allows compatibility with both. While both PyQt6
-and PySide6 are supported, we prefer PySide6 as it is the official Python binding from the Qt Company. It offers
-advantages like bundling all necessary libraries in a single package with pip installation and staying more up-to-date
-compared to PyQt6.
-
-Below is a list of useful links to help you start developing with Qt and QtDesigner:
-
-- [Python GUIs](https://www.pythonguis.com): A great resource with tutorials and examples for creating GUIs in Python
-  using various frameworks.
-- [PySide6 Quick Start Guide](https://doc.qt.io/qtforpython-6/index.html): The official documentation for PySide6,
-  including quick start guides and tutorials.
-- [QtDesigner Official Documentation](https://doc.qt.io/qt-6/qtdesigner-manual.html): Comprehensive documentation for
-  QtDesigner.
-- [Simple PyQt Tutorial from RealPython](https://realpython.com/python-pyqt-gui-calculator/): A beginner-friendly
-  tutorial on creating your first GUI application with PyQt.
-- [PyQtGraph Documentation](https://pyqtgraph.readthedocs.io/en/latest/): BEC Widgets relies on PyQtGraph for plotting;
-  this is the official documentation.

docs/developer/widget_development/bec_dispatcher.md

@@ -1,143 +0,0 @@
-(developer.bec_dispatcher)=
-
-# BECDispatcher
-
-## Overview
-
-The [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-is a powerful tool that
-simplifies the process of connecting Qt slots to message updates from the BEC server. It enables real-time communication
-between your widget and the BEC server by listening to specific message channels and triggering callbacks when new data
-is received.
-
-This tool is especially useful for creating widgets that need to respond to dynamic data, such as device readbacks or
-scan updates. By
-using [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher),
-you
-can create callback functions that react to incoming messages and update your widget's state or perform other tasks
-based on the data received.
-
-## How It Works
-
-When you create a widget that needs to respond to updates from the BEC server, you can use
-the [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-to
-connect specific Qt slots (callback functions) to message endpoints. These endpoints are defined within the BEC system
-and represent specific channels of information (
-e.g., [`device readback`](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_lib.endpoints.MessageEndpoints.html#bec_lib.endpoints.MessageEndpoints.device_readback),
-[`scan_segment`](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_lib.endpoints.MessageEndpoints.html#bec_lib.endpoints.MessageEndpoints.scan_segment),
-etc.).
-
-### Step-by-Step Guide
-
-1. **Create a Callback Function**: Define a function within your widget that will handle the data received from the BEC
-   server. This function should usually accept two parameters: `msg_content` (the message content) and `metadata` (
-   additional
-   information about the message).
-
-    ```python
-    # Example for a callback function that updates a widget display based on motor readback data
-   from qtpy.QtCore import Slot
-   
-    @Slot(dict, dict)
-    def on_device_readback(self, msg_content, metadata):
-        # Process the incoming data
-        new_value = msg_content["signals"]['motor_x']["value"]
-        # Update the widget's display or perform another action
-        self.update_display(new_value)
-    ```
-
-2. **Connect the Slot to an Endpoint**: Use
-   the [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-   to connect your callback function to a specific
-   endpoint. The endpoint represents the type of data or message you're interested in.
-
-    ```python
-   from bec_lib.endpoints import MessageEndpoints
-   
-    self.bec_dispatcher.connect_slot(self.on_device_readback, MessageEndpoints.device_readback("motor_x"))
-    ```
-
-3. **Handle Incoming Data**: Your callback function will be triggered automatically whenever a new message is received
-   on the connected endpoint. Use the data in `msg_content` to update your widget or perform other actions.
-
-4. **Clean Up Connections**: If your widget is being destroyed or you no longer need to listen for updates, make sure to
-   disconnect your slots from
-   the [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-   to avoid memory or thread leaks.
-
-    ```python
-    self.bec_dispatcher.disconnect_slot(self.on_device_readback, MessageEndpoints.device_readback("motor_x"))
-    ```
-
-### Example: Motor Map Widget
-
-The [`BECMotorMap`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.widgets.figure.plots.motor_map.motor_map.BECMotorMap.html#bec-widgets-widgets-figure-plots-motor-map-motor-map-becmotormap)
-widget is a great example of
-how [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-can be used to handle real-time data updates. This
-widget listens for updates on specific motor positions and dynamically updates the motor map display.
-
-Here's a breakdown of
-how [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-is used in
-the [`BECMotorMap`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.widgets.figure.plots.motor_map.motor_map.BECMotorMap.html#bec-widgets-widgets-figure-plots-motor-map-motor-map-becmotormap)
-widget:
-
-1. **Connecting to Motor Readbacks**:
-   The widget connects to
-   the [`device readback`](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_lib.endpoints.MessageEndpoints.html#bec_lib.endpoints.MessageEndpoints.device_readback)
-   endpoints using
-   the [`connect_slot`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher.connect_slot)
-   method
-   of [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher).
-   This allows
-   the widget to receive real-time updates about the motor positions.
-
-```{literalinclude} ../../../bec_widgets/widgets/figure/plots/motor_map/motor_map.py
-:language: python
-:pyobject: BECMotorMap._connect_motor_to_slots
-:dedent: 4
-```
-
-2. **Handling Readback Data**:
-   The `on_device_readback` slot is called whenever new data is received from the motor readback. This slot processes
-   the data and updates the motor map plot accordingly.
-
-```{literalinclude} ../../../bec_widgets/widgets/figure/plots/motor_map/motor_map.py
-:language: python
-:pyobject: BECMotorMap.on_device_readback
-:dedent: 4
-```
-
-3. **Updating the Plot**:
-   The motor map plot is updated in response to the new data, providing a real-time visualization of the motor's
-   position.
-
-```{literalinclude} ../../../bec_widgets/widgets/figure/plots/motor_map/motor_map.py
-:language: python
-:pyobject: BECMotorMap._update_plot
-:dedent: 4
-```
-
-4. **Disconnecting When No Longer Needed**:
-   The widget ensures that connections are properly cleaned up when no longer needed.
-
-```{literalinclude} ../../../bec_widgets/widgets/figure/plots/motor_map/motor_map.py
-:language: python
-:pyobject: BECMotorMap._update_plot
-:dedent: 4
-```
-
-## Conclusion
-
-The [`BECDispatcher`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_dispatcher.BECDispatcher.html#bec_widgets.utils.bec_dispatcher.BECDispatcher)
-is a key tool for developing interactive and responsive widgets within the BEC framework. By
-leveraging this tool, you can create widgets that automatically respond to real-time data updates from the BEC server,
-enhancing the interactivity and functionality of your user interface.
-
-In next tutorials we will cover how to create a custom widget using the BECDispatcher and BECWidget base class.
-
-```{note}
-For more details on specific messages and endpoints, please refer to the [Message Endpoints Documentation](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_lib.endpoints.MessageEndpoints.html#bec-lib-endpoints-messageendpoints).
-```

docs/developer/widget_development/widget_development.md

@@ -1,13 +0,0 @@
-(developer.widget_development)=
-# Widget development
-This section provides an introduction to the building blocks of BEC Widgets: widgets. Widgets are the basic components of the graphical user interface (GUI) and are used to create larger applications. We will cover key topics such as how to develop new widgets or how to customise existing widgets. For details on the already available widgets and their usage, please refer to user section about [widgets](#user.widgets)
-
-```{toctree}
----
-maxdepth: 2
-hidden: false
----
-
-bec_dispatcher
-
-```

docs/index.md

@@ -1,74 +0,0 @@
-# BEC Widgets documentation
-
-A flexible and extensible framework for building graphical user interfaces in Python, optimized for use in the BEC environment.
-
-<br><br>
-
-<br><br>
-
-````{grid} 2
-:gutter: 5
-
-```{grid-item-card}
-:link: introduction
-:link-type: ref
-:img-top: /assets/index_getting_started.svg
-:text-align: center
-:class-item: index-card
-
-## Introduction
-
-General information about BEC Widgets.
-```
-
-```{grid-item-card}
-:link: user
-:link-type: ref
-:img-top:  /assets/index_user_guide.svg
-:text-align: center
-:class-item: index-card
-
-## User guide
-
-Information for users of BEC Widgets.
-```
-
-```{grid-item-card} 
-:link: developer
-:link-type: ref
-:img-top: /assets/index_contribute.svg
-:text-align: center
-:class-item: index-card
-
-## Developer guide
-
-Information for developers of BEC Widgets. 
-```
-
-```{grid-item-card} 
-:link: api_reference
-:link-type: ref
-:img-top: /assets/index_api.svg
-:text-align: center
-:class-item: index-card
-
-## API reference
-
-Comprehensive reference of all BEC Widget classes, functions, and methods.
-```
-
-````
-
-
-```{toctree}
----
-numbered: true
-maxdepth: 2
-hidden: true
----
-
-introduction/introduction
-user/user
-developer/developer
-api_reference/api_reference
-```

docs/introduction/introduction.md

@@ -1,18 +0,0 @@
-(introduction)=
-# Introduction
-
-## Overview
-
-BEC Widgets is a GUI framework developed with beamline scientists in mind, aiming to provide a modern and modular environment for interacting with experiments. This package offers a suite of widgets specifically designed to enhance the workflow of beamline experiments, including features for running scans and data visualization.
-
-Targeting the unique needs of beamline scientists, BEC Widgets stands out with its modular approach to widget design and high customizability. This flexibility allows for tailored solutions that meet the specific requirements of each beamline.
-
-**Key Features**:
-
-- **Integration:** Seamlessly integrates with [BEC (Beamline Experiment Control)](https://gitlab.psi.ch/bec/bec), ensuring a cohesive and efficient experiment control experience.
-- **Support for Pyside6 and PyQt6:** Provides compatibility with both Pyside6 and PyQt6, offering versatility in your development environment.
-- **Widget Modularity:** Features modular widgets that can be easily combined to create customized applications, perfectly aligning with the diverse needs of beamline experiments.
-
-## Getting Started
-
-For detailed usage instructions and examples showcasing the practical applications of BEC Widgets, please refer to the [User](#user) section. Developers interested in contributing or customizing BEC Widgets can find more information in the [Developer](#developer) section.

docs/make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs/requirements.txt

@@ -1,12 +0,0 @@
-sphinx
-sphinx_copybutton
-recommonmark
-sphinx-toolbox
-pydata-sphinx-theme
-sphinx-copybutton
-sphinx-inline-tabs
-myst-parser
-sphinx-design
-PySide6
-bec-widgets
-tomli

docs/user/api_reference/api_reference.md

@@ -1,11 +0,0 @@
-(user.api_reference)=
-# User API Reference
-
-```{eval-rst}
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-module-template.rst
-
-    bec_widgets.cli.client
-
-```

docs/user/applications/applications.md

@@ -1,10 +0,0 @@
-(user.applications)=
-# Applications
-
-**Coming soon**
-
-```{toctree}
----
-maxdepth: 1
-hidden: true
----