Skip to content

Commit 15a7540

Browse files
pylessardpylessard
authored
Fixed SDK doc (#258)
Missing fields and broken links
1 parent fbbae2d commit 15a7540

File tree

8 files changed

+117
-18
lines changed

8 files changed

+117
-18
lines changed

‎scrutiny/core/embedded_enum.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ def add_value(self, name: str, value: int) -> None:
7575
:param name: Enumerator name
7676
:param value: Enumerator value
7777
78-
:raises IndexError: If the enumerator name is already defined in the enum with a different value
78+
:raise IndexError: If the enumerator name is already defined in the enum with a different value
7979
8080
"""
8181
if name in self.vals and self.vals[name] != value:
@@ -92,7 +92,7 @@ def get_value(self, name: str) -> int:
9292
9393
:param name: Enumerator name
9494
95-
:raises ValueError: If the given enumerator name is not part of the enumeration
95+
:raise ValueError: If the given enumerator name is not part of the enumeration
9696
"""
9797
if name not in self.vals:
9898
raise ValueError('%s is not a valid name for enum %s' % (name, self.name))

‎scrutiny/sdk/client.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1897,11 +1897,11 @@ def wt_get_info_callback(state: CallbackState, response: Optional[api_typing.S2C
18971897
return container.obj
18981898

18991899
def get_var_watchable_info(self, path: str) -> DetailedVarWatchableConfiguration:
1900-
""" Performs a call to :meth:`get_watchable_info<scrutiny.clientScrutinyClient.get_watchable_info>` for a single watchable
1901-
of type ``Variable``.
1900+
""" Performs a call to :meth:`get_watchable_info<scrutiny.sdk.client.ScrutinyClient.get_watchable_info>` for a single watchable
1901+
of type :attr:`Variable<scrutiny.sdk.WatchableType.Variable>`.
19021902
19031903
:param path: Server path to the watchable
1904-
:raises BadTypeError: If the requested watchable is not an variable
1904+
:raise BadTypeError: If the requested watchable is not an variable
19051905
19061906
"""
19071907
d = self.get_watchable_info([path])
@@ -1911,11 +1911,11 @@ def get_var_watchable_info(self, path: str) -> DetailedVarWatchableConfiguration
19111911
return info
19121912

19131913
def get_alias_watchable_info(self, path: str) -> DetailedAliasWatchableConfiguration:
1914-
""" Performs a call to :meth:`get_watchable_info<scrutiny.clientScrutinyClient.get_watchable_info>` for a single watchable
1915-
of type ``Alias``.
1914+
""" Performs a call to :meth:`get_watchable_info<scrutiny.sdk.client.ScrutinyClient.get_watchable_info>` for a single watchable
1915+
of type :attr:`Alias<scrutiny.sdk.WatchableType.Alias>`.
19161916
19171917
:param path: Server path to the watchable
1918-
:raises BadTypeError: If the requested watchable is not an alias
1918+
:raise BadTypeError: If the requested watchable is not an alias
19191919
19201920
"""
19211921
d = self.get_watchable_info([path])
@@ -1925,11 +1925,11 @@ def get_alias_watchable_info(self, path: str) -> DetailedAliasWatchableConfigura
19251925
return info
19261926

19271927
def get_rpv_watchable_info(self, path: str) -> DetailedRPVWatchableConfiguration:
1928-
""" Performs a call to :meth:`get_watchable_info<scrutiny.clientScrutinyClient.get_watchable_info>` for a single watchable
1929-
of type ``RPV``.
1928+
""" Performs a call to :meth:`get_watchable_info<scrutiny.sdk.client.ScrutinyClient.get_watchable_info>` for a single watchable
1929+
of type :attr:`RPV<scrutiny.sdk.WatchableType.RuntimePublishedValue>`.
19301930
19311931
:param path: Server path to the watchable
1932-
:raises BadTypeError: If the requested watchable is not a Runtime Published Value
1932+
:raise BadTypeError: If the requested watchable is not a Runtime Published Value
19331933
19341934
"""
19351935
d = self.get_watchable_info([path])

‎scrutiny/sdk/definitions.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -851,7 +851,7 @@ def has_enum(self) -> bool:
851851
def get_enum(self) -> EmbeddedEnum:
852852
""" Returns the enum associated with this watchable
853853
854-
:raises BadEnumError: If the watchable has no enum assigned
854+
:raise BadEnumError: If the watchable has no enum assigned
855855
"""
856856
self._assert_has_enum()
857857
assert self.enum is not None
@@ -866,7 +866,7 @@ def parse_enum_val(self, val: str) -> int:
866866
867867
:param val: The enumerator name to convert
868868
869-
:raises BadEnumError: If the watchable has no enum assigned or the given value is not a valid enumerator
869+
:raise BadEnumError: If the watchable has no enum assigned or the given value is not a valid enumerator
870870
:raise TypeError: Given parameter not of the expected type
871871
"""
872872
validation.assert_type(val, 'val', str)
@@ -948,10 +948,10 @@ class VariableFactoryInterface:
948948
"""An optional enumeration associated with the possible values of the item"""
949949

950950
array_dims: Dict[str, Tuple[int, ...]]
951-
"""The dims of each subpath that are arrays element"""
951+
"""The dimensions of each subpath that are arrays element"""
952952

953953
def count_possible_paths(self) -> int:
954-
"""Returns how many path his factory can generate"""
954+
"""Returns how many path this factory can generate"""
955955
if not self._is_valid():
956956
return 0
957957

‎scrutiny/sdk/docs/source/_static/exception_hierarchy.drawio‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
<mxfile host="65bd71144e">
2+
<diagram id="YjDBSU52wkaKRwKGG119" name="Page-1">
3+
<mxGraphModel dx="1086" dy="625" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="#ffffff" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0"/>
6+
<mxCell id="1" parent="0"/>
7+
<mxCell id="4" style="edgeStyle=none;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="2" target="3">
8+
<mxGeometry relative="1" as="geometry"/>
9+
</mxCell>
10+
<mxCell id="2" value="Exception" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
11+
<mxGeometry x="120" y="20" width="150" height="30" as="geometry"/>
12+
</mxCell>
13+
<mxCell id="16" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="5">
14+
<mxGeometry relative="1" as="geometry"/>
15+
</mxCell>
16+
<mxCell id="18" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="6">
17+
<mxGeometry relative="1" as="geometry"/>
18+
</mxCell>
19+
<mxCell id="19" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="7">
20+
<mxGeometry relative="1" as="geometry"/>
21+
</mxCell>
22+
<mxCell id="20" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="8">
23+
<mxGeometry relative="1" as="geometry"/>
24+
</mxCell>
25+
<mxCell id="22" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="9">
26+
<mxGeometry relative="1" as="geometry"/>
27+
</mxCell>
28+
<mxCell id="23" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="10">
29+
<mxGeometry relative="1" as="geometry"/>
30+
</mxCell>
31+
<mxCell id="24" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="12">
32+
<mxGeometry relative="1" as="geometry"/>
33+
</mxCell>
34+
<mxCell id="25" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="13">
35+
<mxGeometry relative="1" as="geometry"/>
36+
</mxCell>
37+
<mxCell id="26" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="3" target="11">
38+
<mxGeometry relative="1" as="geometry"/>
39+
</mxCell>
40+
<mxCell id="3" value="ScrutinySDKException" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
41+
<mxGeometry x="120" y="80" width="150" height="30" as="geometry"/>
42+
</mxCell>
43+
<mxCell id="5" value="ConnectionError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
44+
<mxGeometry x="230" y="140" width="150" height="30" as="geometry"/>
45+
</mxCell>
46+
<mxCell id="6" value="InvalidValueError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
47+
<mxGeometry x="230" y="180" width="150" height="30" as="geometry"/>
48+
</mxCell>
49+
<mxCell id="7" value="OperationFailure" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
50+
<mxGeometry x="230" y="220" width="150" height="30" as="geometry"/>
51+
</mxCell>
52+
<mxCell id="8" value="TimeoutException" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
53+
<mxGeometry x="230" y="260" width="150" height="30" as="geometry"/>
54+
</mxCell>
55+
<mxCell id="9" value="NameNotFoundError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
56+
<mxGeometry x="230" y="300" width="150" height="30" as="geometry"/>
57+
</mxCell>
58+
<mxCell id="10" value="BadTypeError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
59+
<mxGeometry x="230" y="340" width="150" height="30" as="geometry"/>
60+
</mxCell>
61+
<mxCell id="27" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="11" target="14">
62+
<mxGeometry relative="1" as="geometry"/>
63+
</mxCell>
64+
<mxCell id="28" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;rounded=0;curved=0;" edge="1" parent="1" source="11" target="15">
65+
<mxGeometry relative="1" as="geometry"/>
66+
</mxCell>
67+
<mxCell id="11" value="ApiError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
68+
<mxGeometry x="230" y="460" width="150" height="30" as="geometry"/>
69+
</mxCell>
70+
<mxCell id="12" value="BadEnum" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
71+
<mxGeometry x="230" y="380" width="150" height="30" as="geometry"/>
72+
</mxCell>
73+
<mxCell id="13" value="NotAllowedError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
74+
<mxGeometry x="230" y="420" width="150" height="30" as="geometry"/>
75+
</mxCell>
76+
<mxCell id="14" value="BadResponseError" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
77+
<mxGeometry x="340" y="510" width="150" height="30" as="geometry"/>
78+
</mxCell>
79+
<mxCell id="15" value="ErrorResponseException" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;" vertex="1" parent="1">
80+
<mxGeometry x="340" y="550" width="150" height="30" as="geometry"/>
81+
</mxCell>
82+
</root>
83+
</mxGraphModel>
84+
</diagram>
85+
</mxfile>

‎scrutiny/sdk/docs/source/_static/exception_hierarchy.png‎

-39.3 KB
Loading

‎scrutiny/sdk/docs/source/accessing_variables.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ A handle will exist if a previous call to :meth:`watch<scrutiny.sdk.client.Scru
6565
:member-order: bysource
6666
:members: server_path, name, type, datatype, value, value_bool, value_int, value_float,
6767
value_enum, has_enum, get_enum, parse_enum_val,
68-
last_update_timestamp, last_write_timestamp, update_counter
68+
last_update_timestamp, last_write_timestamp, update_counter,
69+
var_details, alias_details, rpv_details, server_id, is_dead
6970

7071
-----
7172

‎scrutiny/sdk/docs/source/exceptions.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,11 @@ The inheritance hierarchy goes as follows.
5454

5555
-----
5656

57+
.. autoclass:: scrutiny.sdk.exceptions.BadTypeError
58+
:exclude-members: __init__, __new__
59+
60+
-----
61+
5762
.. autoclass:: scrutiny.sdk.exceptions.ApiError
5863
:exclude-members: __init__, __new__
5964

‎scrutiny/sdk/watchable_handle.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ def has_enum(self) -> bool:
220220
def get_enum(self) -> EmbeddedEnum:
221221
""" Returns the enum associated with this watchable
222222
223-
:raises BadEnumError: If the watchable has no enum assigned
223+
:raise BadEnumError: If the watchable has no enum assigned
224224
"""
225225
self._assert_configured()
226226
assert self._configuration is not None
@@ -231,7 +231,7 @@ def parse_enum_val(self, val: str) -> int:
231231
232232
:param val: The enumerator name to convert
233233
234-
:raises BadEnumError: If the watchable has no enum assigned or the given value is not a valid enumerator
234+
:raise BadEnumError: If the watchable has no enum assigned or the given value is not a valid enumerator
235235
:raise TypeError: Given parameter not of the expected type
236236
"""
237237
self._assert_configured()
@@ -346,25 +346,33 @@ def update_counter(self) -> int:
346346

347347
@property
348348
def is_dead(self) -> bool:
349+
"""Return ``True`` if the watchable handle has lost its validity, ``False`` otherwise.
350+
If ``True``, the handle can be discarded. A new call to :meth:`watch()<scrutiny.sdk.client.ScrutinyClient.watch>` must be performed to get a new valid handle."""
349351
status = ValueStatus(self._status) # copy for atomicity
350352
return status not in (ValueStatus.Valid, ValueStatus.NeverSet)
351353

352354
@property
353355
def var_details(self) -> DetailedVarWatchableConfiguration:
356+
"""Returns the variable-specific metadata. Raises a :class:`BadTypeError<scrutiny.sdk.exceptions.BadTypeError>` if the
357+
:attr:`type<scrutiny.sdk.watchable_handle.WatchableHandle.type>` != :attr:`Variable<scrutiny.sdk.WatchableType.Variable>`"""
354358
self._assert_configured()
355359
if not isinstance(self._configuration, DetailedVarWatchableConfiguration):
356360
raise sdk_exceptions.BadTypeError(f"Watchable {self._shortname} is not a variable. Type={self.type.name}")
357361
return self._configuration
358362

359363
@property
360364
def alias_details(self) -> DetailedAliasWatchableConfiguration:
365+
"""Returns the alias-specific metadata. Raises a :class:`BadTypeError<scrutiny.sdk.exceptions.BadTypeError>` if the
366+
:attr:`type<scrutiny.sdk.watchable_handle.WatchableHandle.type>` != :attr:`Alias<scrutiny.sdk.WatchableType.Alias>`"""
361367
self._assert_configured()
362368
if not isinstance(self._configuration, DetailedAliasWatchableConfiguration):
363369
raise sdk_exceptions.BadTypeError(f"Watchable {self._shortname} is not an alias. Type={self.type.name}")
364370
return self._configuration
365371

366372
@property
367373
def rpv_details(self) -> DetailedRPVWatchableConfiguration:
374+
"""Returns the RPV-specific metadata. Raises a :class:`BadTypeError<scrutiny.sdk.exceptions.BadTypeError>` if the
375+
:attr:`type<scrutiny.sdk.watchable_handle.WatchableHandle.type>` != :attr:`RuntimePublishedValue<scrutiny.sdk.WatchableType.RuntimePublishedValue>`"""
368376
self._assert_configured()
369377
if not isinstance(self._configuration, DetailedRPVWatchableConfiguration):
370378
raise sdk_exceptions.BadTypeError(f"Watchable {self._shortname} is not a Runtime Published Value. Type={self.type.name}")

0 commit comments

Comments
 (0)