Skip to content

Commit 254c6bd

Browse files
dmgavdmgav
authored
Merge pull request #6 from dmgav/docs
New README.md file
2 parents d1e8102 + 86570c4 commit 254c6bd

File tree

5 files changed

+123
-43
lines changed

5 files changed

+123
-43
lines changed

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
BSD 3-Clause License
22

3-
Copyright (c) 2025, My Name.
3+
Copyright (c) 2025.
44
All rights reserved.
55

66
Redistribution and use in source and binary forms, with or without

‎README.md‎

Lines changed: 101 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,103 @@
11
# save-and-restore-api
22

3-
[![Actions Status][actions-badge]][actions-link]
4-
[![Documentation Status][rtd-badge]][rtd-link]
5-
6-
[![PyPI version][pypi-version]][pypi-link]
7-
[![Conda-Forge][conda-badge]][conda-link]
8-
[![PyPI platforms][pypi-platforms]][pypi-link]
9-
10-
[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
11-
12-
<!-- SPHINX-START -->
13-
14-
<!-- prettier-ignore-start -->
15-
[actions-badge]: https://github.com/dmgav/save-and-restore-api/workflows/CI/badge.svg
16-
[actions-link]: https://github.com/dmgav/save-and-restore-api/actions
17-
[conda-badge]: https://img.shields.io/conda/vn/conda-forge/save-and-restore-api
18-
[conda-link]: https://github.com/conda-forge/save-and-restore-api-feedstock
19-
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
20-
[github-discussions-link]: https://github.com/dmgav/save-and-restore-api/discussions
21-
[pypi-link]: https://pypi.org/project/save-and-restore-api/
22-
[pypi-platforms]: https://img.shields.io/pypi/pyversions/save-and-restore-api
23-
[pypi-version]: https://img.shields.io/pypi/v/save-and-restore-api
24-
[rtd-badge]: https://readthedocs.org/projects/save-and-restore-api/badge/?version=latest
25-
[rtd-link]: https://save-and-restore-api.readthedocs.io/en/latest/?badge=latest
26-
27-
<!-- prettier-ignore-end -->
3+
`save-and-restore-api` is a Python library for communicating with Save-and-Restore service
4+
(CS Studio Phoebus). The package provides syncronous (thread-based) and asynchronous (asyncio)
5+
versions of the API functions.
6+
7+
## How to Use the Library
8+
9+
The following example code creates a folder node named "My Folder" under the root node:
10+
11+
```python
12+
13+
from save_and_restore_api import SaveRestoreAPI
14+
15+
with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
16+
SR.auth_set(username="user", password="user_password")
17+
18+
root_folder_uid = SR.ROOT_NODE_UID
19+
node={"name": "My Folder", "nodeType": "FOLDER"}
20+
21+
folder = SR.node_add(root_folder_uid, node=node)
22+
23+
print(f"Created folder metadata: {folder}")
24+
```
25+
26+
Here is an async version of the same code:
27+
28+
```python
29+
30+
from save_and_restore_api.aio import SaveRestoreAPI
31+
32+
async with SaveRestoreAPI(base_url="http://localhost:8080/save-restore") as SR:
33+
await SR.auth_set(username="user", password="user_password")
34+
35+
root_folder_uid = SR.ROOT_NODE_UID
36+
node={"name": "My Folder", "nodeType": "FOLDER"}
37+
38+
folder = await SR.node_add(root_folder_uid, node=node)
39+
print(f"Created folder metadata: {folder}")
40+
```
41+
42+
## `save-and-restore` CLI Tool
43+
44+
`save-and-restore` CLI tool is installed with the package. The tool allows performing
45+
a limited set of basic operations on the nodes of the Save-and-Restore service.
46+
The currently selected set of operations:
47+
48+
- LOGIN: test login credentials;
49+
50+
- CONFIG ADD: create configuration node based on a list of PVs read from a file;
51+
52+
- CONFIG UPDATE: update an existing configuration node based on a list of PVs read from a file;
53+
54+
- CONFIG GET: get information about an existing configuration node, including the list of PVs.
55+
56+
The tool was primarily developed for adding snapshot configurations to Save-and-Restore
57+
based on lists of PVs loaded from local files. Typical use case is to create a configuration
58+
based on a list of PVs read from an autosave (`.sav`) file saved by an IOC. Currently only
59+
autosave files are supported, but support for other formats can be added if needed.
60+
The list of supported functions can also be extended.
61+
62+
## How to use `save-and-restore` CLI Tool
63+
64+
65+
Check login credentials. User password is requested interactively. Alternatively, the
66+
password can be passed using environment variable `SAVE_AND_RESTORE_API_USER_PASSWORD``.
67+
68+
```bash
69+
save-and-restore --base-url http://localhost:8080/save-restore --user-name=user LOGIN
70+
```
71+
72+
Read the configuration node named 'eiger_config'. Print the full configuration data
73+
(the list of PVs):
74+
75+
```bash
76+
save-and-restore --base-url http://localhost:8080/save-restore \
77+
CONFIG GET --config-name /detectors/imaging/eiger_config --show-data=ON
78+
```
79+
80+
Create a new configuration node named 'eiger_config'. Load the list of PVs from
81+
file ``eiger_pvs.sav``. Automatically create any missing parent folders in
82+
the path:
83+
84+
```bash
85+
save-and-restore --base-url=http://localhost:8080/save-restore --user-name=user \
86+
--create-folders=ON CONFIG ADD --config-name=/detectors/imaging/eiger_config \
87+
--file-name=eiger_pvs.sav --file-format=autosave
88+
```
89+
90+
Update an existing configuration node named 'eiger_config'. Load the list of PVs
91+
from the file ``eiger_pvs.sav``:
92+
93+
```bash
94+
save-and-restore --base-url http://localhost:8080/save-restore --user-name=user \
95+
CONFIG UPDATE --config-name /detectors/imaging/eiger_config \
96+
--file-name eiger_pvs.sav --file-format autosave
97+
```
98+
99+
Print full list of options:
100+
101+
```bash
102+
save-and-restore -h
103+
```

‎docs/source/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
You can adapt this file completely to your liking, but it should at least
44
contain the root `toctree` directive.
55
6-
Bluesky Queue Server API Documentation
7-
======================================
6+
Save and Restore API Documentation
7+
==================================
88

99
.. toctree::
1010
:maxdepth: 2

‎docs/source/installation.rst‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,3 @@ Installation
55
Installation from PyPI::
66

77
$ pip install save-and-restore-api
8-
9-
Installation from `conda-forge`::
10-
11-
$ conda install save-and-restore-api -c conda-forge

‎src/save_and_restore_api/tools/cli.py‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -111,22 +111,30 @@ def formatter(prog):
111111
"\n"
112112
"Examples:\n"
113113
"\n"
114-
" Read the configuration node named 'eiger_config'. Print the full config data:\n"
114+
" Check login credentials. User password is requested interactively. Alternatively,\n"
115+
" the password can be passed using environment variable `SAVE_AND_RESTORE_API_USER_PASSWORD`\n"
115116
"\n"
116-
" save-and-restore --host-url http://localhost:8080/save-restore \\\n"
117-
" CONFIG GET --config-name /detectors/imaging/eiger_config --show-data=ON\n"
117+
" save-and-restore --base-url http://localhost:8080/save-restore --user-name=user LOGIN\n"
118118
"\n"
119-
" Create a new configuration node named 'eiger_config':\n"
119+
" Read the configuration node named 'eiger_config'. Print the full configuration data\n"
120+
" (the list of PVs):\n"
120121
"\n"
121-
" save-and-restore --host-url=http://localhost:8080/save-restore --username=user\\\n"
122-
" --create-folders=true CONFIG ADD --config-name=/detectors/imaging/eiger_config \\\n"
123-
" --file-name=eiger_pvs.sav --file-format=autosave\n"
122+
" save-and-restore --base-url http://localhost:8080/save-restore \\\n"
123+
" CONFIG GET --config-name /detectors/imaging/eiger_config --show-data=ON\n"
124124
"\n"
125-
" Update an existing configuration node named 'eiger_config':\n"
125+
" Create a new configuration node named 'eiger_config'. Load the list of PVs from\n"
126+
" file ``eiger_pvs.sav``. Automatically create any missing parent folders in the path:\n"
126127
"\n"
127-
" save-and-restore --host-url http://localhost:8080/save-restore --username=user\\\n"
128-
" CONFIG UPDATE --config-name /detectors/imaging/eiger_config \\\n"
129-
" --file-name eiger_pvs.sav --file-format autosave\n",
128+
" save-and-restore --base-url=http://localhost:8080/save-restore --user-name=user \\\n"
129+
" --create-folders=ON CONFIG ADD --config-name=/detectors/imaging/eiger_config \\\n"
130+
" --file-name=eiger_pvs.sav --file-format=autosave\n"
131+
"\n"
132+
" Update an existing configuration node named 'eiger_config'. Load the list of PVs\n"
133+
" from the file ``eiger_pvs.sav``:\n"
134+
"\n"
135+
" save-and-restore --base-url http://localhost:8080/save-restore --user-name=user \\\n"
136+
" CONFIG UPDATE --config-name /detectors/imaging/eiger_config \\\n"
137+
" --file-name eiger_pvs.sav --file-format autosave\n",
130138
formatter_class=formatter,
131139
)
132140

0 commit comments

Comments
 (0)