Skip to content

Commit 6a7da09

Browse files
dmgavdmgav
committed
DOC: remaining docstrings
1 parent cd1016f commit 6a7da09

File tree

2 files changed

+100
-30
lines changed

2 files changed

+100
-30
lines changed

‎src/save_and_restore_api/_api_threads.py‎

Lines changed: 97 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ def send_request(
104104
Timeout for this request in seconds. If not specified or None, the default timeout set in the
105105
class constructor is used.
106106
auth : httpx.BasicAuth, optional
107-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
107+
Object with authentication data (generated using ``auth_gen()`` method). If not specified or None,
108108
then the authentication set using ``auth_set`` method is used.
109109
110110
Returns
@@ -287,8 +287,7 @@ def node_add(self, parentNodeId, *, node, auth=None, **kwargs):
287287
Node metadata. The required fields are ``name`` and ``nodeType``.
288288
Supported node types: ``"FOLDER"``, ``"CONFIGURATION"``.
289289
auth : httpx.BasicAuth
290-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
291-
then the authentication set using ``auth_set`` method is used.
290+
Object with authentication data (generated using ``auth_gen()`` method).
292291
293292
Returns
294293
-------
@@ -337,8 +336,7 @@ def node_delete(self, nodeId, *, auth=None):
337336
nodeId : str
338337
Unique ID of the node to be deleted.
339338
auth : httpx.BasicAuth
340-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
341-
then the authentication set using ``auth_set`` method is used.
339+
Object with authentication data (generated using ``auth_gen()`` method).
342340
343341
Returns
344342
-------
@@ -360,8 +358,7 @@ def nodes_delete(self, uniqueIds, *, auth=None):
360358
uniqueIds : list[str]
361359
List of UIDs of the nodes to delete.
362360
auth : httpx.BasicAuth
363-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
364-
then the authentication set using ``auth_set`` method is used.
361+
Object with authentication data (generated using ``auth_gen()`` method).
365362
366363
Returns
367364
-------
@@ -493,8 +490,7 @@ def config_update(self, *, configurationNode, configurationData, auth=None):
493490
Configuration data (``configurationData``). ``uniqueId`` field must be identical to the
494491
``uniqueId`` field in ``configurationNode``.
495492
auth : httpx.BasicAuth
496-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
497-
then the authentication set using ``auth_set`` method is used.
493+
Object with authentication data (generated using ``auth_gen()`` method).
498494
499495
Returns
500496
-------
@@ -542,8 +538,7 @@ def tags_add(self, *, uniqueNodeIds, tag, auth=None):
542538
tag : dict
543539
Tag to be added. The dictionary must contain the ``name`` key and optionally ``comment`` key.
544540
auth : httpx.BasicAuth, optional
545-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
546-
then the authentication set using ``auth_set`` method is used.
541+
Object with authentication data (generated using ``auth_gen()`` method).
547542
548543
Returns
549544
-------
@@ -568,6 +563,8 @@ def tags_delete(self, *, uniqueNodeIds, tag, auth=None):
568563
tag : dict
569564
Tag to be deleted. The dictionary must contain the ``name`` key. The ``comment`` key
570565
is optional and ignored by the API.
566+
auth : httpx.BasicAuth, optional
567+
Object with authentication data (generated using ``auth_gen()`` method).
571568
572569
Returns
573570
-------
@@ -622,8 +619,7 @@ def take_snapshot_save(self, uniqueNodeId, *, name=None, comment=None, auth=None
622619
Description of the new snapshot node. If not specified or None, the comment
623620
is set to date and time of the snapshot, e.g. ``2025-10-12 22:49:50.577``.
624621
auth : httpx.BasicAuth, optional
625-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
626-
then the authentication set using ``auth_set`` method is used.
622+
Object with authentication data (generated using ``auth_gen()`` method).
627623
628624
Returns
629625
-------
@@ -676,8 +672,7 @@ def snapshot_add(self, parentNodeId, *, snapshotNode, snapshotData, auth=None):
676672
snapshotData : dict
677673
Snapshot data (``snapshotData``). The required field is ``"snapshotItems"``.
678674
auth : httpx.BasicAuth, optional
679-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
680-
then the authentication set using ``auth_set`` method is used.
675+
Object with authentication data (generated using ``auth_gen()`` method).
681676
682677
Returns
683678
-------
@@ -707,8 +702,7 @@ def snapshot_update(self, *, snapshotNode, snapshotData, auth=None):
707702
Snapshot data (``snapshotData``). ``uniqueId`` field must be identical to the
708703
``uniqueId`` field in ``snapshotNode``.
709704
auth : httpx.BasicAuth, optional
710-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
711-
then the authentication set using ``auth_set`` method is used.
705+
Object with authentication data (generated using ``auth_gen()`` method).
712706
713707
Returns
714708
-------
@@ -822,8 +816,7 @@ def composite_snapshot_add(self, parentNodeId, *, compositeSnapshotNode, composi
822816
``"referencedSnapshotNodes"``, which points to the list of UIDs of the nodes included in
823817
the composite snapshot.
824818
auth : httpx.BasicAuth, optional
825-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
826-
then the authentication set using ``auth_set`` method is used.
819+
Object with authentication data (generated using ``auth_gen()`` method).
827820
828821
Returns
829822
-------
@@ -855,8 +848,7 @@ def composite_snapshot_update(self, *, compositeSnapshotNode, compositeSnapshotD
855848
Composite snapshot data (``compositeSnapshotData``). ``uniqueId`` field must be identical to the
856849
``uniqueId`` field in ``compositeSnapshotNode``.
857850
auth : httpx.BasicAuth, optional
858-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
859-
then the authentication set using ``auth_set`` method is used.
851+
Object with authentication data (generated using ``auth_gen()`` method).
860852
861853
Returns
862854
-------
@@ -888,8 +880,7 @@ def composite_snapshot_consistency_check(self, uniqueNodeIds, *, auth=None):
888880
uniqueNodeIds : list of str
889881
List of UIDs of snapshots and composite snapshots included in the composite snapshot.
890882
auth : httpx.BasicAuth, optional
891-
Object with authentication data (generated using ``auth_gen`` method). If not specified or None,
892-
then the authentication set using ``auth_set`` method is used.
883+
Object with authentication data (generated using ``auth_gen()`` method).
893884
894885
Returns
895886
-------
@@ -918,7 +909,7 @@ def restore_node(self, nodeId, *, auth=None):
918909
nodeId : str
919910
Unique ID of the snapshot node.
920911
auth : httpx.BasicAuth, optional
921-
Object with authentication data (generated using ``auth_gen`` method).
912+
Object with authentication data (generated using ``auth_gen()`` method).
922913
923914
Returns
924915
-------
@@ -944,7 +935,7 @@ def restore_items(self, *, snapshotItems, auth=None):
944935
List of snapshot items (PVs) to be restored. The format is consistent with
945936
the format of ``snapshotData["snapshotItems"]``.
946937
auth : httpx.BasicAuth, optional
947-
Object with authentication data (generated using ``auth_gen`` method).
938+
Object with authentication data (generated using ``auth_gen()`` method).
948939
949940
Returns
950941
-------
@@ -1000,6 +991,18 @@ def filter_add(self, filter, *, auth=None):
1000991
Add a filter to the list stored in the database.
1001992
1002993
API: PUT /filter
994+
995+
Parameters
996+
----------
997+
filter : dict
998+
Filter to be added. The dictionary must contain the ``name`` and ``filter`` keys.
999+
auth : httpx.BasicAuth, optional
1000+
Object with authentication data (generated using ``auth_gen()`` method).
1001+
1002+
Returns
1003+
-------
1004+
dict
1005+
Added filter as returned by the server.
10031006
"""
10041007
method, url, body_json = self._prepare_filter_add(filter=filter)
10051008
return self.send_request(method, url, body_json=body_json, auth=auth)
@@ -1009,6 +1012,11 @@ def filters_get(self):
10091012
Get the list of all the filters from the database.
10101013
10111014
API: GET /filters
1015+
1016+
Returns
1017+
-------
1018+
list[dict]
1019+
List of all filters in the database.
10121020
"""
10131021
method, url = self._prepare_filters_get()
10141022
return self.send_request(method, url)
@@ -1018,6 +1026,17 @@ def filter_delete(self, name, *, auth=None):
10181026
Delete filter with the given name from the database.
10191027
10201028
API: DELETE /filter/{name}
1029+
1030+
Parameters
1031+
----------
1032+
name : str
1033+
Name of the filter to be deleted.
1034+
auth : httpx.BasicAuth, optional
1035+
Object with authentication data (generated using ``auth_gen()`` method).
1036+
1037+
Returns
1038+
-------
1039+
None
10211040
"""
10221041
method, url = self._prepare_filter_delete(name=name)
10231042
return self.send_request(method, url, auth=auth)
@@ -1032,6 +1051,20 @@ def structure_move(self, nodeIds, *, newParentNodeId, auth=None):
10321051
by ``newParentNodeId``. The API requires 'admin' priviledges.
10331052
10341053
API: POST /move
1054+
1055+
Parameters
1056+
----------
1057+
nodeIds : list[str]
1058+
List of node unique IDs to be moved.
1059+
newParentNodeId : str
1060+
Unique ID of the new parent node.
1061+
auth : httpx.BasicAuth, optional
1062+
Object with authentication data (generated using ``auth_gen()`` method).
1063+
1064+
Returns
1065+
-------
1066+
dict
1067+
Dictionary with metadata for the new parent node.
10351068
"""
10361069
method, url, body_json, params = self._prepare_structure_move(
10371070
nodeIds=nodeIds, newParentNodeId=newParentNodeId
@@ -1040,10 +1073,24 @@ def structure_move(self, nodeIds, *, newParentNodeId, auth=None):
10401073

10411074
def structure_copy(self, nodeIds, *, newParentNodeId, auth=None):
10421075
"""
1043-
Copy nodes specified by a list of UIDs ``nodeIds`` to a new parent node specified
1076+
Copy nodes specified by a list of UIDs ``nodeIds`` to the new parent node specified
10441077
by ``newParentNodeId``. The API requires 'admin' priviledges.
10451078
10461079
API: POST /copy
1080+
1081+
Parameters
1082+
----------
1083+
nodeIds : list[str]
1084+
List of node unique IDs to be moved.
1085+
newParentNodeId : str
1086+
Unique ID of the new parent node.
1087+
auth : httpx.BasicAuth, optional
1088+
Object with authentication data (generated using ``auth_gen()`` method).
1089+
1090+
Returns
1091+
-------
1092+
dict
1093+
Dictionary with metadata for the new parent node.
10471094
"""
10481095
method, url, body_json, params = self._prepare_structure_copy(
10491096
nodeIds=nodeIds, newParentNodeId=newParentNodeId
@@ -1052,9 +1099,20 @@ def structure_copy(self, nodeIds, *, newParentNodeId, auth=None):
10521099

10531100
def structure_path_get(self, uniqueNodeId):
10541101
"""
1055-
Get path for the node with specified uniqueNodeId.
1102+
Get path for the node with specified uniqueNodeId. The path contains a sequence
1103+
of nodes starting from the root node. Node names are separated by '/' character.
10561104
10571105
API: GET /path/{uniqueNodeId}
1106+
1107+
Parameters
1108+
----------
1109+
uniqueNodeId : str
1110+
Unique ID of the node.
1111+
1112+
Returns
1113+
-------
1114+
str
1115+
Path of the node with names of nodes separated by '/' character.
10581116
"""
10591117
method, url = self._prepare_structure_path_get(uniqueNodeId=uniqueNodeId)
10601118
return self.send_request(method, url)
@@ -1063,9 +1121,20 @@ def structure_path_nodes(self, path):
10631121
"""
10641122
Get a list of nodes that match the specified path. The path can point to multiple
10651123
nodes as long as node type is different (e.g. a folder and a configuration may have
1066-
the same name).
1124+
the same name and may be simultaneously present in the list).
10671125
10681126
API: GET /path
1127+
1128+
Parameters
1129+
----------
1130+
path : str
1131+
Path of the node with names of nodes separated by '/' character.
1132+
1133+
Returns
1134+
-------
1135+
list[dict]
1136+
List of nodes that match the specified path. Each node is represented as a dictionary
1137+
with node metadata as returned by the server.
10691138
"""
10701139
method, url, params = self._prepare_structure_path_nodes(path=path)
10711140
return self.send_request(method, url, params=params)

‎tests/common.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,9 @@ def _clear():
118118
# Delete all filters
119119
filters = SR.filters_get()
120120
for f in filters:
121-
if f.startswith("filter_prefix"):
122-
SR.filter_delete(f["name"])
121+
f_name = f["name"]
122+
if f_name.startswith(filter_prefix):
123+
SR.filter_delete(f_name)
123124

124125
_clear()
125126
yield

0 commit comments

Comments
 (0)