bec-widgets 0.52.1__py3-none-any.whl → 0.53.1__py3-none-any.whl

docs/_templates/custom-class-template.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/conf.py

@@ -0,0 +1,81 @@
+# 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",
+]
+
+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__
+
+# 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 = ["css/custom.css"]
+html_logo = "_static/bec.png"
+html_theme_options = {"show_nav_level": 1, "navbar_align": "content"}

docs/developer/developer.md

@@ -0,0 +1,26 @@
+(developer)=
+# Development
+
+```{toctree}
+---
+maxdepth: 1
+hidden: true
+---
+reference/
+```
+
+To contribute to the development of BEC Widgets, start by setting up the development environment:
+
+1. **Clone the Repository**: 
+```bash
+git clone https://gitlab.psi.ch/bec/bec_widgets
+cd bec_widgets
+```
+2. **Install in Editable Mode**:
+
+Installing the package in editable mode allows you to make changes to the code and test them in real-time.
+```bash
+pip install -e .[dev,pyqt6]
+```
+
+

docs/developer/reference.md

@@ -0,0 +1,10 @@
+## API Reference
+
+```{eval-rst}
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   bec_widgets
+```

docs/index.md

@@ -0,0 +1,39 @@
+# BEC Widgets documentation
+
+<br><br>
+
+````{grid} 3
+:gutter: 5
+
+```{grid-item-card}  Introduction
+:link: introduction
+:link-type: ref
+
+General information.
+```
+
+```{grid-item-card}  User
+:link: user
+:link-type: ref
+
+Information for users.
+```
+
+```{grid-item-card}  Developer
+:link: developer
+:link-type: ref
+
+Information for developers.
+```
+````
+
+
+```{toctree}
+---
+numbered: true
+maxdepth: 1
+---
+
+introduction/introduction
+user/user
+developer/developer

docs/introduction/introduction.md

@@ -0,0 +1,18 @@
+(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 PyQt5 and PyQt6:** Provides compatibility with both PyQt5 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

@@ -0,0 +1,35 @@
+@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

@@ -0,0 +1,10 @@
+sphinx
+sphinx_copybutton
+recommonmark
+sphinx-toolbox
+pydata-sphinx-theme
+sphinx-copybutton
+myst-parser
+sphinx-design
+bec-widgets
+tomli

docs/user/apps/modular_app.md

@@ -0,0 +1,6 @@
+(user.apps.modular_app)=
+
+# Modular Application
+
+
+_to be added..._

docs/user/apps/motor_app.md

@@ -0,0 +1,34 @@
+(user.apps.motor_app)=
+# Motor Alignment
+
+The Motor Alignment Application is a key component of the BEC Widgets suite, designed to facilitate precise alignment of motors. 
+Users can easily launch this app using the script located at  `/bec_widgets/example/motor_movement/motor_example.py` script. 
+The application's primary function is to enable users to align motors to specific positions and to visually track the motor's trajectory.
+
+## Controlling Motors
+
+In the top middle panel of the application, users will find combobox dropdown menus for selecting the motors they wish to track on the x and y axes of the motor map. 
+These motors are automatically loaded from the current active BEC instance, ensuring seamless integration and ease of use.
+
+There are two primary methods to control motor movements:
+
+
+1. **Manual Control with Arrow Keys:** Users can manually drive the motors using arrow keys. Before doing so, they need to select the step size for each motor, allowing for precise and incremental movements.
+2. **Direct Position Entry:** Alternatively, users can input a desired position in the text input box and then click the Go button. This action will move the motor directly to the specified coordinates.
+
+As the motors are moved, their trajectory is plotted in real-time, providing users with a visual representation of the motor's path. This feature is particularly useful for understanding the movement patterns and making necessary adjustments.
+
+
+## Saving and Exporting Data
+
+Users have the ability to save the current motor position in a table widget. This functionality is beneficial for recalling and returning to specific positions. By clicking the Go button in the table widget, the motors will automatically move back to the saved position.
+
+Additionally, users can annotate each saved position with notes and comments directly in the table widget. This feature is invaluable for keeping track of specific alignment settings or observations. The contents of the table, including the notes, can be exported to a .csv file. This exported data can be used for initiating scans or for record-keeping purposes.
+
+The table widget also supports saving and loading functionalities, allowing users to preserve their motor positions and notes across sessions. The saved files are in a user-friendly format for ease of access and use.
+
+
+## Example of Use
+
+![Motor app example](motor_app_10fps.gif)
+

docs/user/apps/plot_app.md

@@ -0,0 +1,6 @@
+(user.apps.plot_app)=
+
+# General Plotting Tool
+
+
+_to be added..._

docs/user/apps.md

@@ -0,0 +1,39 @@
+(user.apps)=
+# Applications
+
+In the `bec_widgets/examples` directory, you will find practical applications that demonstrate the capabilities of BEC Widgets in real-world scenarios. These applications showcase the adaptability and functionality of the framework for various beamline experiment needs.
+
+**Motor Alignment Tool**
+
+This tool assists in aligning motors with samples during experiments. It enables users to move motors, visually track their movement, and record positions for precise alignment.
+
+- **Location:** `bec_widgets/examples/motor_movement`
+- **Further Details:** [Motor Alignment Tool Documentation](#user.apps.motor_app) 
+
+**General Plotting Live Acquisition Tool**
+
+This application is designed for live data visualization. It allows users to view real-time signals from detectors in a multi-grid layout, facilitating immediate analysis during experiments.
+
+- **Location:** `bec_widgets/examples/plot_app`
+- **Further Details:** [General Plotting Live Acquisition Tool Documentation](#user.apps.plot_app) 
+
+
+**Modular Application**
+
+A bespoke application built entirely using BEC Widgets' modular components. This example illustrates the framework's flexibility in creating customized GUIs tailored to specific experimental setups.
+
+- **Location:** `bec_widgets/examples/modular_app`
+- **Further Details:** [Modular Application](#user.apps.modular_app) 
+
+---
+Note: The documentation for these applications is currently under development. The provided links will direct you to their respective pages once the documentation is complete.
+
+```{toctree}
+---
+maxdepth: 1
+hidden: true
+---
+
+apps/motor_app
+apps/plot_app
+apps/modular_app

docs/user/customisation.md

@@ -0,0 +1,13 @@
+(user.customisation)=
+# Customisation
+
+BEC Widgets are designed to be used with QtDesigner to quicly design GUI.
+
+
+## Example of promoting widgets in Qt Designer
+
+_Work in progress_
+
+## Implementation of plugins into Qt Designer
+
+_Work in progress_

docs/user/installation.md

@@ -0,0 +1,46 @@
+(user.installation)=
+# Installation
+
+
+**Prerequisites**
+
+Before installing BEC Widgets, please ensure the following requirements are met:
+
+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/).
+
+**Standard Installation**
+
+Install BEC Widgets using the pip package manager. Open your terminal and execute:
+
+```bash
+pip install bec_widgets
+```
+
+This command installs BEC Widgets along with its dependencies, including the default PyQt6.
+
+**Selecting a PyQt Version**
+
+BEC Widgets supports both PyQt5 and PyQt6. To install a specific version, use:
+
+For PyQt6:
+
+```bash
+pip install bec_widgets[pyqt6]
+```
+
+For PyQt5:
+
+```bash
+pip install bec_widgets[pyqt5]
+```
+
+**Troubleshooting**
+
+If you encounter issues during installation, particularly with PyQt, try purging the pip cache:
+
+```bash
+pip cache purge
+```
+
+This can resolve conflicts or issues with package installations.

docs/user/user.md

@@ -0,0 +1,38 @@
+(user)=
+# User
+
+**Overview**
+
+Welcome to the User section of the BEC Widgets documentation! BEC Widgets is a versatile GUI framework tailored for beamline scientists, enabling efficient and intuitive interaction with beamline experiments. This section is designed to guide both new and experienced users through the essential aspects of utilizing BEC Widgets.
+
+**Key Topics**
+
+- [Installing BEC Widgets](#user.installation): Instructions for installing BEC Widgets on your system.
+
+- [Example Applications](#user.apps): Overview of bespoke applications and demonstrations of BEC Widgets in action, showcasing its use in real-world beamline scenarios.
+
+- [Widgets Overview](#user.widgets): Detailed information on the variety of widgets available, their functions, and how to use them effectively.
+
+- [Customization and Configuration](#user.customisation): Tips on customizing and configuring BEC Widgets to suit your specific experimental needs using Qt Designer.
+
+**Bug Reports and Feature Requests**
+
+We value your feedback and contributions to improving BEC Widgets. If you encounter any issues or have ideas for new features, we encourage you to report them.
+
+- **Bug Reports:** If you find a bug or an issue, please report it on our repository's [Issues page](https://gitlab.psi.ch/bec/bec-widgets/-/issues?sort=created_date&state=opened). We have a template for bug reporting to help you provide all necessary information.
+- **Feature Requests:** Have an idea for a new feature or an enhancement? Share it with us on the [Issues page](https://gitlab.psi.ch/bec/bec-widgets/-/issues?sort=created_date&state=opened) of our repository. We have a feature request template that you can use to describe your proposal.
+
+**Development**
+
+For advanced details about BEC Widgets’ internal architecture, development contributions, or customization techniques, please explore the [Developer](#developer) section. 
+
+```{toctree}
+---
+maxdepth: 3
+hidden: true
+---
+
+installation
+apps
+widgets
+customisation

docs/user/widgets.md

@@ -0,0 +1,41 @@
+(user.widgets)=
+# Widgets
+
+## Visualization Widgets
+
+BEC Widgets includes a variety of visualization widgets designed to cater to diverse data representation needs in beamline experiments. These widgets enhance the user experience by providing intuitive and interactive data visualizations.
+
+### 1D Waveform Widget
+
+**Purpose:** This widget provides a straightforward visualization of 1D data. It is particularly useful for plotting positioner movements against detector readings, enabling users to observe correlations and patterns in a simple, linear format.
+
+**Key Features:**
+- Real-time plotting of positioner versus detector values.
+- Interactive controls for zooming and panning through the data.
+- Customizable visual elements such as line color and style.
+
+**Example of Use:**
+![Waveform 1D](./widgets/w1D.gif)
+### 2D Scatter Plot
+
+**Purpose:** The 2D scatter plot widget is designed for more complex data visualization. It employs a false color map to represent a third dimension (z-axis), making it an ideal tool for visualizing multidimensional data sets.
+
+**Key Features:**
+
+- 2D scatter plot with color-coded data points based on a third variable (two positioners for x/y vs. one detector for colormap).
+- Interactive false color map for enhanced data interpretation.
+- Tools for selecting and inspecting specific data points.
+
+**Example of Use:**
+![Waveform 1D](./widgets/scatter_2D.gif)
+### Motor Position Map
+
+**Purpose:** A specialized component derived from the Motor Alignment Tool. It's focused on tracking and visualizing the position of motors, crucial for precise alignment and movement tracking during scans.
+
+**Key Features:**
+- Real-time tracking of motor positions.
+- Visual representation of motor trajectories, aiding in alignment tasks.
+- Ability to record and recall specific motor positions for repetitive tasks.
+
+**Example of Use:**
+![Waveform 1D](./widgets/motor.gif)

pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bec_widgets"
+version = "0.53.1"
+description = "BEC Widgets"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pydantic",
+    "qtconsole",
+    "jedi",
+    "qtpy",
+    "pyqtgraph",
+    "bec_lib",
+    "zmq",
+    "h5py",
+    "pyqtdarktheme",
+    "black",
+]
+
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-random-order",
+    "pytest-timeout",
+    "coverage",
+    "pytest-qt",
+    "isort",
+    "fakeredis",
+]
+pyqt5 = ["PyQt5>=5.9"]
+pyqt6 = ["PyQt6>=6.7"]
+
+[project.urls]
+"Bug Tracker" = "https://gitlab.psi.ch/bec/bec_widgets/issues"
+Homepage = "https://gitlab.psi.ch/bec/bec_widgets"
+
+[tool.hatch.build.targets.wheel]
+include = ["*"]
+
+[tool.black]
+line-length = 100
+skip-magic-trailing-comma = true
+
+[tool.isort]
+profile = "black"
+line_length = 100
+multi_line_output = 3
+include_trailing_comma = true
+
+[tool.semantic_release]
+build_command = "python -m build"
+version_toml = ["pyproject.toml:project.version"]
+
+[tool.semantic_release.commit_author]
+env = "GIT_COMMIT_AUTHOR"
+default = "semantic-release <semantic-release>"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = [
+    "build",
+    "chore",
+    "ci",
+    "docs",
+    "feat",
+    "fix",
+    "perf",
+    "style",
+    "refactor",
+    "test",
+]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+default_bump_level = 0
+
+[tool.semantic_release.remote]
+name = "origin"
+type = "gitlab"
+ignore_token_for_push = false
+
+[tool.semantic_release.remote.token]
+env = "GL_TOKEN"
+
+[tool.semantic_release.publish]
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = true