usov_i-org/bec
1
0
Fork 0
mirror of https://github.com/ivan-usov-org/bec.git synced 2025-04-21 18:20:01 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: updated docs for bec plugins

Browse Source
This commit is contained in:
wakonig_k 2024-04-23 22:55:46 +02:00
parent 8e16efb21a
commit 29b89dd017
1 changed files with 39 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
docs/source/developer/bec_plugins.md
View File

@ -8,19 +8,19 @@ BEC plugins are a way to extend the functionality of BEC. They are written in Py
* Customizing the BEC CLI startup procedure (e.g. to load additional modules) * Customizing the BEC CLI startup procedure (e.g. to load additional modules)
* Customizing the file structure * Customizing the file structure
Plugins are commonly provided to BEC by installing them as a Python package `bec_plugins`. Clients and BEC services can then load the specific plugins they need. Plugins are commonly provided to BEC by installing them as a Python package. Clients and BEC services can then load the specific plugins they need.
## Plugin Structure ## Plugin Structure
The following sections describe the structure of a BEC plugin. As plugins typically live on gitlab, we will use the following example structure of a "beamline_XX_plugins" repository to explain the different parts of BEC plugins. Instead of creating the structure manually, you can also use the script located in BEC library to create the structure for you. The following sections describe the structure of a BEC plugin. As plugins typically live on gitlab, we will use the following example structure of a "beamline_XX_bec" repository to explain the different parts of BEC plugins. Instead of creating the structure manually, you can also use the script located in BEC library to create the structure for you.
```bash ```bash
python ./<path_to_bec>/bec/bec_lib/util_scripts/create_plugin_structure.py <path_to_new_plugin> python ./<path_to_bec>/bec/bec_lib/util_scripts/create_plugin_structure.py <path_to_new_plugin>
``` ```
``` ```
beamline_XX_plugins/ beamline_XX_bec/
├── bec_plugins/ ├── beamline_XX_bec/
│ ├── bec_client/ │ ├── bec_ipython_client/
│ │ ├── high_level_interface/ │ │ ├── high_level_interface/
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ └── custom_hli.py │ │ │ └── custom_hli.py
@ -34,33 +34,37 @@ beamline_XX_plugins/
│ │ │ ├── post_startup.py │ │ │ ├── post_startup.py
│ │ │ └── pre_startup.py │ │ │ └── pre_startup.py
│ │ └── __init__.py │ │ └── __init__.py
│ ├── scan_server/ │ ├── bec_widgets/
│ │ ├── scan_plugins/
│ │ │ ├── __init__.py
│ │ │ └── custom_scan.py
│ │ └── __init__.py │ │ └── __init__.py
│ ├── device_server/
│ │ ├── __init__.py
│ │ └── startup.py
│ ├── dap_services/ │ ├── dap_services/
│ │ ├── __init__.py │ │ ├── __init__.py
│ │ └── custom_dap.py │ │ └── custom_dap.py
│ ├── deployments/
│ │ ├── __init__.py
│ │ └── device_server/
│ │ ├── __init__.py
│ │ └── startup.py
│ ├── device_configs/
│ │ ├── __init__.py
│ │ └── tomography_config.yaml
│ ├── devices/ │ ├── devices/
│ │ ├── __init__.py │ │ ├── __init__.py
│ │ └── custom_XX_device.py │ │ └── custom_XX_device.py
│ └── device_configs/ │ ├── file_writer/
│ ├── __init__.py │ │ └── __init__.py
│ └── tomography_config.yaml │ └── scans/
│ ├── custom_scan.py
│ └── __init__.py
├── bin/ ├── bin/
│ └── helper_script.sh │ └── helper_script.sh
├── setup.cfg ├── tests
└── setup.py └── pyproject.toml
``` ```
<!-- done with https://tree.nathanfriend.io --> <!-- done with https://tree.nathanfriend.io -->
<!-- <!--
beamline_XX_plugins beamline_XX_bec
bec_plugins beamline_XX_bec
bec_client bec_ipython_client
high_level_interface high_level_interface
__init__.py __init__.py
custom_hli.py custom_hli.py
@ -74,86 +78,30 @@ beamline_XX_plugins
post_startup.py post_startup.py
pre_startup.py pre_startup.py
__init__.py __init__.py
scan_server bec_widgets
scan_plugins
__init__.py __init__.py
custom_scan.py dap_services
__init__.py
custom_dap.py
deployments
__init__.py __init__.py
device_server device_server
__init__.py __init__.py
startup.py startup.py
dap_services
__init__.py
custom_dap.py
devices
__init__.py
custom_XX_device.py
device_configs device_configs
__init__.py __init__.py
tomography_config.yaml tomography_config.yaml
devices
__init__.py
custom_XX_device.py
file_writer
__init__.py
scans
custom_scan.py
__init__.py
bin bin
helper_script.sh helper_script.sh
setup.cfg tests
setup.py pyproject.toml
--> -->
Within the root directory of your repository, place the [setup files](#setup_files) and the plugins folder. The plugins folder contains the actual plugins and is structured as follows:
* `bec_client`: Contains plugins that are used by the BEC client. This includes plugins to customize the startup procedure, adding helper classes and functions to the CLI or adding aliases to the CLI to simplify the usage of BEC.
* `device_server`: Contains plugins that are used by the device server.
* `scan_server`: Contains plugins that are used by the scan server. This includes plugins to add new scan types.
* `devices`: Contains plugins that are used to add support for new devices that are not covered by the shared ophyd_devices package.
* `device_configs`: Contains the configuration files for the devices.
{#setup_files}
### Setup files
The setup files are used to install the plugin as a Python package. The `setup.py` file is the main file that is used to install the package. It contains the information about the package and the dependencies. The `setup.cfg` file contains additional information about the package. For more information about the setup files, see the [Python documentation](https://packaging.python.org/tutorials/packaging-projects/).
**setup.py**
```python
from setuptools import setup
if __name__ == "__main__":
setup(
# specify the additional dependencies
install_requires=["pyyaml", "pyepics"],
# if you have additional dependencies for development, specify them here
extras_require={"dev": ["pytest", "pytest-random-order", "coverage"]},
)
```
**setup.cfg**
```cfg
[metadata]
name = bec_plugins
description = BEC plugins to modify the behaviour of services within the BEC framework
long_description = file: README.md
long_description_content_type = text/markdown
url = https://gitlab.psi.ch/bec/bec
project_urls =
Bug Tracker = https://gitlab.psi.ch/bec/bec/issues
classifiers =
Programming Language :: Python :: 3
Development Status :: 3 - Alpha
Topic :: Scientific/Engineering
[options]
package_dir =
= .
packages = find:
python_requires = >=3.10
[options.packages.find]
where = .
```
``` {note}
While the `setup.py` file can (and probably should) be modified to fit your needs, the `setup.cfg` file and especially the name of the package ("bec_plugins") should not be changed. This is because the BEC services and clients look for plugins in a package called "bec_plugins".
```