Docstring Format
The CDK turns docstrings into the descriptions a SiLA client shows for features, endpoints, parameters, responses, and errors. Clients may not use Python, so a docstring describes the SiLA interface, not the Python code.
General format
| Rule | Why |
|---|---|
Use Google style. Don't use reStructuredText directives such as .. parameter:: or .. return::. | The CDK treats RST directives as deprecated and warns. |
Don't put types in Args: or Returns: entries. Write Path: ..., not Path (str): .... | The CDK warns and ignores them. Types come from the signature. |
Don't state units anywhere in a docstring. Annotate a sila.constraints.Unit on the parameter or return type instead. | A unit in prose is invisible to clients and goes stale when the annotation changes. |
Indent entries under Args:, Returns:, Yields:, and Raises: by 2 spaces. | This is the format the CDK parses. |
Don't include Python examples (>>> ...) or an Examples: section. | A client may not be using Python at all. |
Refer to other endpoints by their SiLA identifier, such as DoorController.Lock, not by Python access syntax such as door_lock.lock(). | Clients see SiLA identifiers, not your Python names. |
Feature docstrings
Open with what the feature controls or provides, and the context in which it applies.
class TemperatureController(sila.Feature):
"""Control and monitor the temperature of the incubation chamber."""
If an endpoint has to be called in a specific order, or depends on device state, explain it in plain text.
Command docstrings
| Section | Contents |
|---|---|
| Summary | One line saying what the command does. |
Args: | One entry per parameter, in signature order, name in PascalCase. Don't document parameters that don't exist; the CDK warns and drops them. |
Yields: | Observable commands only: the intermediate response from intermediate: sila.Intermediate[T], name in PascalCase. |
Returns: | The response, name in PascalCase. One entry per value when the command returns a tuple. |
Raises: | Only when this command needs different guidance than the exception's default description. See Error entries. |
from ...io.units import CELSIUS
@sila.ObservableCommand()
async def start_ramp(
self,
target: typing.Annotated[float, CELSIUS],
*,
status: sila.Status,
intermediate: sila.Intermediate[typing.Annotated[float, CELSIUS]],
) -> typing.Annotated[float, CELSIUS]:
"""
Ramp the chamber to the target temperature.
Args:
Target: The temperature to ramp to.
Yields:
Temperature: The current chamber temperature.
Returns:
FinalTemperature: The chamber temperature once the ramp has finished.
"""
Property docstrings
Describe the value in one line. Don't add Args: (a property never takes parameters) or Returns:.
@sila.UnobservableProperty()
async def get_clamp_state(self) -> bool:
"""Whether the clamp is currently securing labware."""
Structure docstrings
Document each dataclass field in an Attributes: section, name in PascalCase.
from ...io.units import BYTES
@dataclasses.dataclass
class Metadata:
"""
Metadata about a file.
Attributes:
Size: The size of the file.
Owner: The username of the file's owner.
CreatedAt: The timestamp when the file was created.
LastModified: The timestamp when the file was last modified.
"""
size: typing.Annotated[int, BYTES]
owner: str
created_at: datetime.datetime
last_modified: datetime.datetime
Error entries
The CDK merges the errors= list on the decorator and the Raises: section of the docstring into one set of errors, keyed by identifier. The description comes from the exception class docstring, unless a Raises: entry overrides it for that one endpoint.
- Add a
Raises:entry only when this endpoint needs different guidance than the exception's default description. - Only list execution errors that a caller can reasonably react to on this endpoint. Don't document errors that can happen on any endpoint, such as
ConnectionErrororHardwareError. - Never list validation, framework, or communication errors.
See the Error Handling guide for how declared errors reach the client.
Last updated