DOCS-2199: Viam Python SDK correctness pass

docs/examples/example.ipynb

@@ -359,7 +359,7 @@
     "#### Optional Validator and Reconfiguration Functions\n",
     "Modules also have support for validator and reconfiguration functions.\n",
     "\n",
-    "Custom validation can be done by specifiying a validate function. Validate functions can raise errors that will be returned to the parent through gRPC. Validate functions return a sequence of strings representing the implicit dependencies of the resource. If there are none, return an empty sequence `[]`.\n",
+    "Custom validation can be done by specifying a validate function. Validate functions can raise errors that will be returned to the parent through gRPC. Validate functions return a sequence of strings representing the implicit dependencies of the resource. If there are none, return an empty sequence `[]`.\n",
     "\n",
     "For example, let's say `MySensor` had a `multiplier` argument that is used to multiply the returned readings in `get_readings()`. The validation function can check if a multiplier attribute was provided and prevent erroneous resource start ups.\n",
     "\n",

src/viam/app/app_client.py

@@ -573,7 +573,7 @@ async def list_organization_members(self) -> Tuple[List[OrganizationMember], Lis
 
         Returns:
             Tuple[List[viam.proto.app.OrganizationMember], List[viam.proto.app.OrganizationInvite]]: A tuple containing two lists; the first
-                [0] of organization members, and the second [1] of organization invites.
+            [0] of organization members, and the second [1] of organization invites.
         """
         organization_id = await self._get_organization_id()
         request = ListOrganizationMembersRequest(organization_id=organization_id)
@@ -595,9 +595,9 @@ async def create_organization_invite(
                 authorizations to include in the invite. If not provided, full owner permissions will
                 be granted.
             send_email_invite (Optional[bool]): Whether or not an email should be sent to the recipient of an invite.
-            The user must accept the email to be added to the associated authorizations.
-            When set to false, the user automatically receives the associated authorization
-            on the next login of the user with the associated email address.
+                The user must accept the email to be added to the associated authorizations.
+                When set to false, the user automatically receives the associated authorization
+                on the next login of the user with the associated email address.
 
         Raises:
             GRPCError: if an invalid email is provided, or if the user is already a member of the org.
@@ -1370,7 +1370,7 @@ async def get_fragment(self, fragment_id: str) -> Fragment:
             # Get a fragment and print its name and when it was created.
             the_fragment = await cloud.get_fragment(
                 fragment_id="12a12ab1-1234-5678-abcd-abcd01234567")
-            print("Name: ", the_fragment.name, "\nCreated on: ", the_fragment.created_on)
+            print("Name: ", the_fragment.name, "\\nCreated on: ", the_fragment.created_on)
 
         Args:
             fragment_id (str): ID of the fragment to get.
@@ -1438,7 +1438,7 @@ async def update_fragment(
         response: UpdateFragmentResponse = await self._app_client.UpdateFragment(request, metadata=self._metadata)
         return Fragment.from_proto(response.fragment)
 
-    async def delete_fragment(self, fragment_id) -> None:
+    async def delete_fragment(self, fragment_id: str) -> None:
         """Delete a fragment.
 
         ::
@@ -1757,7 +1757,7 @@ async def create_key_from_existing_key_authorizations(self, id: str) -> Tuple[st
             id (str): the ID of the API key to duplication authorizations from
 
         Returns:
-            Tuple[str, str] The API key and API key id
+            Tuple[str, str]: The API key and API key id
         """
         request = CreateKeyFromExistingKeyAuthorizationsRequest(id=id)
         response: CreateKeyFromExistingKeyAuthorizationsResponse = await self._app_client.CreateKeyFromExistingKeyAuthorizations(

src/viam/app/data_client.py

@@ -201,7 +201,7 @@ async def tabular_data_by_filter(
             dest (str): Optional filepath for writing retrieved data.
 
         Returns:
-            List[Mapping[str, Any]]: The tabular data.
+            List[TabularData]: The tabular data.
         """
         filter = filter if filter else Filter()
         last = ""
@@ -255,13 +255,13 @@ async def binary_data_by_filter(
                 to true (i.e., both the files' data and metadata are returned).
             num_files (Optional[str]): Number of binary data to return. Passing 0 returns all binary data matching the filter no matter.
                 Defaults to 100 if no binary data is requested, otherwise 10. All binary data or the first `num_files` will be returned,
-                    whichever comes first.
+                whichever comes first.
 
         Raises:
             ValueError: If `num_files` is less than 0.
 
         Returns:
-            List[bytes]: The binary data.
+            List[BinaryData]: The binary data.
         """
         num_files = num_files if num_files else 10 if include_file_data else 100
         if num_files < 0:
@@ -338,7 +338,7 @@ async def binary_data_by_ids(
             GRPCError: If no `BinaryID` objects are provided.
 
         Returns:
-            List[bytes]: The binary data.
+            List[BinaryData]: The binary data.
         """
         request = BinaryDataByIDsRequest(binary_ids=binary_ids, include_binary=True)
         response: BinaryDataByIDsResponse = await self._data_client.BinaryDataByIDs(request, metadata=self._metadata)
@@ -367,6 +367,9 @@ async def delete_tabular_data(self, organization_id: str, delete_older_than_days
             organization_id (str): ID of organization to delete data from.
             delete_older_than_days (int): Delete data that was captured up to this many days ago. For example if `delete_older_than_days`
                 is 10, this deletes any data that was captured up to 10 days ago. If it is 0, all existing data is deleted.
+
+        Returns:
+            int: The number of items deleted.
         """
         request = DeleteTabularDataRequest(organization_id=organization_id, delete_older_than_days=delete_older_than_days)
         response: DeleteTabularDataResponse = await self._data_client.DeleteTabularData(request, metadata=self._metadata)
@@ -389,6 +392,9 @@ async def delete_binary_data_by_filter(self, filter: Optional[Filter]) -> int:
         Args:
             filter (viam.proto.app.data.Filter): Optional `Filter` specifying binary data to delete. Passing an empty `Filter` will lead to
                 all data being deleted. Exercise caution when using this option.
+
+        Returns:
+            int: The number of items deleted.
         """
         filter = filter if filter else Filter()
         request = DeleteBinaryDataByFilterRequest(filter=filter)
@@ -520,7 +526,7 @@ async def remove_tags_from_binary_data_by_ids(self, tags: List[str], binary_ids:
 
         Args:
             tags (List[str]): List of tags to remove from specified binary data. Must be non-empty.
-            file_ids (List[str]): List of `BinaryID` objects specifying binary data to untag. Must be non-empty.
+            binary_ids (List[BinaryID]): List of `BinaryID` objects specifying binary data to untag. Must be non-empty.
 
         Raises:
             GRPCError: If no binary_ids or tags are provided.
@@ -714,20 +720,20 @@ async def configure_database_user(self, organization_id: str, password: str) ->
     async def create_dataset(self, name: str, organization_id: str) -> str:
         """Create a new dataset.
 
-        Args:
-            name (str): The name of the dataset being created.
-            organization_id (str): The ID of the organization where the dataset is being created.
-
-        Returns:
-            str: The dataset ID of the created dataset.
-
         ::
 
             name = await data_client.create_dataset(
                 name="<dataset-name>",
                 organization_id="<your-org-id>"
             )
             print(name)
+
+        Args:
+            name (str): The name of the dataset being created.
+            organization_id (str): The ID of the organization where the dataset is being created.
+
+        Returns:
+            str: The dataset ID of the created dataset.
         """
         request = CreateDatasetRequest(name=name, organization_id=organization_id)
         response: CreateDatasetResponse = await self._dataset_client.CreateDataset(request, metadata=self._metadata)
@@ -736,18 +742,18 @@ async def create_dataset(self, name: str, organization_id: str) -> str:
     async def list_dataset_by_ids(self, ids: List[str]) -> Sequence[Dataset]:
         """Get a list of datasets using their IDs.
 
-        Args:
-            ids (List[str]): The IDs of the datasets being called for.
-
-        Returns:
-            Sequence[Dataset]: The list of datasets.
-
         ::
 
             datasets = await data_client.list_dataset_by_ids(
                 ids=["abcd-1234xyz-8765z-123abc"]
             )
             print(datasets)
+
+        Args:
+            ids (List[str]): The IDs of the datasets being called for.
+
+        Returns:
+            Sequence[Dataset]: The list of datasets.
         """
         request = ListDatasetsByIDsRequest(ids=ids)
         response: ListDatasetsByIDsResponse = await self._dataset_client.ListDatasetsByIDs(request, metadata=self._metadata)
@@ -757,18 +763,18 @@ async def list_dataset_by_ids(self, ids: List[str]) -> Sequence[Dataset]:
     async def list_datasets_by_organization_id(self, organization_id: str) -> Sequence[Dataset]:
         """Get the datasets in an organization.
 
-        Args:
-            organization_id (str): The ID of the organization.
-
-        Returns:
-            Sequence[Dataset]: The list of datasets in the organization.
-
         ::
 
             datasets = await data_client.list_dataset_by_ids(
                 ids=["abcd-1234xyz-8765z-123abc"]
             )
             print(datasets)
+
+        Args:
+            organization_id (str): The ID of the organization.
+
+        Returns:
+            Sequence[Dataset]: The list of datasets in the organization.
         """
         request = ListDatasetsByOrganizationIDRequest(organization_id=organization_id)
         response: ListDatasetsByOrganizationIDResponse = await self._dataset_client.ListDatasetsByOrganizationID(
@@ -780,31 +786,31 @@ async def list_datasets_by_organization_id(self, organization_id: str) -> Sequen
     async def rename_dataset(self, id: str, name: str) -> None:
         """Rename a dataset specified by the dataset ID.
 
-        Args:
-            id (str): The ID of the dataset.
-            name (str): The new name of the dataset.
-
         ::
 
             await data_client.rename_dataset(
                 id="abcd-1234xyz-8765z-123abc",
                 name="<dataset-name>"
             )
+
+        Args:
+            id (str): The ID of the dataset.
+            name (str): The new name of the dataset.
         """
         request = RenameDatasetRequest(id=id, name=name)
         await self._dataset_client.RenameDataset(request, metadata=self._metadata)
 
     async def delete_dataset(self, id: str) -> None:
         """Delete a dataset.
 
-        Args:
-            id (str): The ID of the dataset.
-
         ::
 
             await data_client.delete_dataset(
                 id="abcd-1234xyz-8765z-123abc"
             )
+
+        Args:
+            id (str): The ID of the dataset.
         """
         request = DeleteDatasetRequest(id=id)
         await self._dataset_client.DeleteDataset(request, metadata=self._metadata)
@@ -814,10 +820,6 @@ async def add_binary_data_to_dataset_by_ids(self, binary_ids: List[BinaryID], da
 
         This BinaryData will be tagged with the VIAM_DATASET_{id} label.
 
-        Args:
-            binary_ids (List[BinaryID]): The IDs of binary data to add to dataset.
-            dataset_id (str): The ID of the dataset to be added to.
-
         ::
 
             from viam.proto.app.data import BinaryID
@@ -841,6 +843,10 @@ async def add_binary_data_to_dataset_by_ids(self, binary_ids: List[BinaryID], da
                 binary_ids=my_binary_ids,
                 dataset_id="abcd-1234xyz-8765z-123abc"
             )
+
+        Args:
+            binary_ids (List[BinaryID]): The IDs of binary data to add to dataset.
+            dataset_id (str): The ID of the dataset to be added to.
         """
         request = AddBinaryDataToDatasetByIDsRequest(binary_ids=binary_ids, dataset_id=dataset_id)
         await self._data_client.AddBinaryDataToDatasetByIDs(request, metadata=self._metadata)
@@ -850,10 +856,6 @@ async def remove_binary_data_from_dataset_by_ids(self, binary_ids: List[BinaryID
 
         This BinaryData will lose the VIAM_DATASET_{id} tag.
 
-        Args:
-            binary_ids (List[BinaryID]): The IDs of binary data to remove from dataset.
-            dataset_id (str): The ID of the dataset to be removed from.
-
         ::
 
             from viam.proto.app.data import BinaryID
@@ -877,6 +879,10 @@ async def remove_binary_data_from_dataset_by_ids(self, binary_ids: List[BinaryID
                 binary_ids=my_binary_ids,
                 dataset_id="abcd-1234xyz-8765z-123abc"
             )
+
+        Args:
+            binary_ids (List[BinaryID]): The IDs of binary data to remove from dataset.
+            dataset_id (str): The ID of the dataset to be removed from.
         """
         request = RemoveBinaryDataFromDatasetByIDsRequest(binary_ids=binary_ids, dataset_id=dataset_id)
         await self._data_client.RemoveBinaryDataFromDatasetByIDs(request, metadata=self._metadata)
@@ -931,6 +937,9 @@ async def binary_data_capture_upload(
 
         Raises:
             GRPCError: If an invalid part ID is passed.
+
+        Returns:
+            str: the file_id of the uploaded data.
         """
         sensor_contents = SensorData(
             metadata=(
@@ -999,15 +1008,16 @@ async def tabular_data_capture_upload(
             tags (Optional[List[str]]): Optional list of tags to allow for tag-based data filtering when retrieving data.
             data_request_times (Optional[List[Tuple[datetime.datetime, datetime.datetime]]]): Optional list of tuples, each containing
                 `datetime` objects denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.
-
-
-        Passing a list of tabular data and Timestamps with length n > 1 will result in n datapoints being uploaded, all tied to the same
-        metadata.
+                Passing a list of tabular data and Timestamps with length n > 1 will result in n datapoints being uploaded, all tied to the
+                same metadata.
 
         Raises:
             GRPCError: If an invalid part ID is passed.
             ValueError: If a list of `Timestamp` objects is provided and its length does not match the length of the list of tabular
                 data.
+
+        Returns:
+            str: the file_id of the uploaded data.
         """
         sensor_contents = []
         if data_request_times:
@@ -1080,7 +1090,6 @@ async def streaming_data_capture_upload(
                 tags=["tag_1", "tag_2"]
             )
 
-
         Args:
             data (bytes): the data to be uploaded.
             part_id (str): Part ID of the resource associated with the file.

src/viam/app/ml_training_client.py

@@ -111,7 +111,7 @@ async def list_training_jobs(
         Args:
             org_id (str): the id of the org to request training job data from.
             training_status (Optional[TrainingStatus]): status of training jobs to filter the list by.
-            If unspecified, all training jobs will be returned.
+                If unspecified, all training jobs will be returned.
 
         Returns:
             List[viam.proto.app.mltraining.TrainingJobMetadata]: a list of training job data.

src/viam/components/arm/arm.py

@@ -192,10 +192,8 @@ async def get_kinematics(
             k_bytes = kinematics[1]
 
         Returns:
-            Tuple[KinematicsFileFormat.ValueType, bytes]:
-                - KinematicsFileFormat.ValueType:
-                  The format of the file, either in URDF format or Viam's kinematic parameter format (spatial vector algebra).
-
-                - bytes: The byte contents of the file.
+            Tuple[KinematicsFileFormat.ValueType, bytes]: A tuple containing two values; the first [0] value represents the format of the
+                file, either in URDF format or Viam's kinematic parameter format (spatial vector algebra), and the second [1] value
+                represents the byte contents of the file.
         """
         ...

src/viam/components/board/board.py

@@ -279,7 +279,7 @@ async def digital_interrupt_by_name(self, name: str) -> DigitalInterrupt:
             name (str): Name of the digital interrupt.
 
         Returns:
-            DigitalInterrupt: the digital interrupt.
+            DigitalInterrupt: The digital interrupt.
         """
         ...
 
@@ -299,7 +299,7 @@ async def gpio_pin_by_name(self, name: str) -> GPIOPin:
             name (str): Name of the GPIO pin.
 
         Returns:
-            GPIOPin: the pin.
+            GPIOPin: The pin.
         """
         ...
 
@@ -316,7 +316,7 @@ async def analog_reader_names(self) -> List[str]:
             names = await my_board.analog_reader_names()
 
         Returns:
-            List[str]: The names of the analog readers..
+            List[str]: The list of names of all known analog readers.
         """
         ...
 
@@ -350,7 +350,7 @@ async def status(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optio
             status = await my_board.status()
 
         Returns:
-            viam.proto.common.BoardStatus: the status.
+            viam.proto.common.BoardStatus: The status.
         """
         ...
 
@@ -369,7 +369,7 @@ async def set_power_mode(
             status = await my_board.set_power_mode(mode=PowerMode.POWER_MODE_OFFLINE_DEEP)
 
         Args:
-            mode: the desired power mode
+            mode (PowerMode): The desired power mode.
         """
         ...
 
@@ -386,7 +386,7 @@ async def write_analog(self, pin: str, value: int, *, timeout: Optional[float] =
             await my_board.write_analog(pin="11", value=48)
 
         Args:
-            pin (str): name of the pin.
-            value (int): value to write.
+            pin (str): The name of the pin.
+            value (int): The value to write.
         """
         ...