viam-sdk 0.25.2__py3-none-linux_armv7l.whl → 0.62.0__py3-none-linux_armv7l.whl

viam/app/ml_training_client.py

@@ -46,16 +46,14 @@ class MLTrainingClient:
         async def main():
 
             # Make a ViamClient
-            viam_client = await connect()
-            # Instantiate an MLTrainingClient to run ML training client API methods on
-            ml_training_client = viam_client.ml_training_client
-
-            viam_client.close()
+            async with await connect() as viam_client:
+                # Instantiate an MLTrainingClient to run ML training client API methods on
+                ml_training_client = viam_client.ml_training_client
 
         if __name__ == '__main__':
             asyncio.run(main())
 
-    For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+    For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/>`_.
     """
 
     def __init__(self, channel: Channel, metadata: Mapping[str, str]):
@@ -65,7 +63,7 @@ class MLTrainingClient:
             channel (grpclib.client.Channel): Connection to app.
             metadata (Mapping[str, str]): Required authorization token to send requests to app.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/>`_.
         """
         self._metadata = metadata
         self._ml_training_client = MLTrainingServiceStub(channel)
@@ -84,27 +82,29 @@ class MLTrainingClient:
 
         ::
 
+            from viam.proto.app.mltraining import ModelType
+
             job_id = await ml_training_client.submit_training_job(
-                organization_id=organization_id,
-                dataset_id=dataset_id,
-                model_name="your-model-name",
+                org_id="<organization-id>",
+                dataset_id="<dataset-id>",
+                model_name="<your-model-name>",
                 model_version="1",
-                model_type="ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION",
-                tags=tags
+                model_type=ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION,
+                tags=["tag1", "tag2"]
             )
 
         Args:
-            org_id (str): the id of the org to submit the training job to
-            dataset_id (str): the id of the dataset
-            model_name (str): the model name
-            model_version (str): the model version
-            model_type (ModelType.ValueType): the model type
-            tags (List[str]): the tags
+            org_id (str): the ID of the org to submit the training job to.
+            dataset_id (str): the ID of the dataset to train the model on.
+            model_name (str): the model name.
+            model_version (str): the model version.
+            model_type (ModelType.ValueType): the model type.
+            tags (List[str]): the labels to train the model on.
 
         Returns:
-            str: the id of the training job
+            str: the ID of the training job.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#submittrainingjob>`_.
         """
 
         request = SubmitTrainingJobRequest(
@@ -119,36 +119,39 @@ class MLTrainingClient:
         return response.id
 
     async def submit_custom_training_job(
-        self, org_id: str, dataset_id: str, registry_item_id: str, model_name: str, model_version: str
+        self, org_id: str, dataset_id: str, registry_item_id: str, registry_item_version: str, model_name: str, model_version: str
     ) -> str:
         """Submit a custom training job.
 
         ::
 
             job_id = await ml_training_client.submit_custom_training_job(
-                organization_id=organization_id,
-                dataset_id=dataset_id,
-                registry_item_id="your-registry-item-id",
-                model_name="your-model-name",
+                org_id="<organization-id>",
+                dataset_id="<dataset-id>",
+                registry_item_id="viam:classification-tflite",
+                registry_item_version="2024-08-13T12-11-54",
+                model_name="<your-model-name>",
                 model_version="1"
             )
 
         Args:
-            org_id (str): the id of the org to submit the training job to
-            dataset_id (str): the id of the dataset
-            registry_item_id (List[str]): the id of the registry item
-            model_name (str): the model name
-            model_version (str): the model version
+            org_id (str): the ID of the org to submit the training job to.
+            dataset_id (str): the ID of the dataset to train the model on.
+            registry_item_id (str): the ID of the training script from the registry.
+            registry_item_version (str): the version of the training script from the registry.
+            model_name (str): the model name.
+            model_version (str): the model version.
 
         Returns:
-            str: the id of the training job
+            str: the ID of the training job.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#submitcustomtrainingjob>`_.
         """
 
         request = SubmitCustomTrainingJobRequest(
             dataset_id=dataset_id,
             registry_item_id=registry_item_id,
+            registry_item_version=registry_item_version,
             organization_id=org_id,
             model_name=model_name,
             model_version=model_version,
@@ -162,15 +165,15 @@ class MLTrainingClient:
         ::
 
             job_metadata = await ml_training_client.get_training_job(
-                id="INSERT YOUR JOB ID")
+                id="<job-id>")
 
         Args:
-            id (str): the id of the requested training job.
+            id (str): the ID of the requested training job.
 
         Returns:
-            viam.proto.app.mltraining.TrainingJobMetadata: training job data.
+            viam.proto.app.mltraining.TrainingJobMetadata: the training job data.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#gettrainingjob>`_.
         """
 
         request = GetTrainingJobRequest(id=id)
@@ -188,19 +191,19 @@ class MLTrainingClient:
         ::
 
             jobs_metadata = await ml_training_client.list_training_jobs(
-                org_id="INSERT YOUR ORG ID")
+                org_id="<org-id>")
 
             first_job_id = jobs_metadata[1].id
 
         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.
+            org_id (str): the ID of the org to request training job data from.
+            training_status (Optional[TrainingStatus]): the status to filter the training jobs list by.
                 If unspecified, all training jobs will be returned.
 
         Returns:
-            List[viam.proto.app.mltraining.TrainingJobMetadata]: a list of training job data.
+            List[viam.proto.app.mltraining.TrainingJobMetadata]: the list of training job data.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#listtrainingjobs>`_.
         """
 
         training_status = training_status if training_status else TrainingStatus.TRAINING_STATUS_UNSPECIFIED
@@ -215,15 +218,15 @@ class MLTrainingClient:
         ::
 
             await ml_training_client.cancel_training_job(
-                id="INSERT YOUR JOB ID")
+                id="<job-id>")
 
         Args:
-            id (str): the id of the job to be canceled.
+            id (str): the ID of the job to cancel.
 
         Raises:
-            GRPCError: if no training job exists with the given id.
+            GRPCError: if no training job exists with the given ID.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#canceltrainingjob>`_.
         """
 
         request = CancelTrainingJobRequest(id=id)
@@ -235,12 +238,12 @@ class MLTrainingClient:
         ::
 
             await ml_training_client.delete_completed_training_job(
-                id="INSERT YOUR JOB ID")
+                id="<job-id>")
 
         Args:
-            id (str): the id of the training job
+            id (str): the ID of the training job to delete.
 
-        For more information, see `ML Training Client API <https://docs.viam.com/appendix/apis/ml-training-client/>`_.
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#deletecompletedtrainingjob>`_.
         """
         request = DeleteCompletedTrainingJobRequest(id=id)
         await self._ml_training_client.DeleteCompletedTrainingJob(request, metadata=self._metadata)

viam/app/provisioning_client.py

@@ -41,11 +41,9 @@ class ProvisioningClient:
         async def main():
 
             # Make a ViamClient
-            viam_client = await connect()
-            # Instantiate a ProvisioningClient to run provisioning client API methods on
-            provisioning_client = viam_client.provisioning_client
-
-            viam_client.close()
+            async with await connect() as viam_client:
+                # Instantiate a ProvisioningClient to run provisioning client API methods on
+                provisioning_client = viam_client.provisioning_client
 
         if __name__ == '__main__':
             asyncio.run(main())

viam/app/viam_client.py

@@ -1,4 +1,5 @@
-from typing import Mapping, Optional
+import os
+from typing import Any, Mapping, Optional
 
 from grpclib.client import Channel
 from typing_extensions import Self
@@ -9,7 +10,8 @@ from viam.app.billing_client import BillingClient
 from viam.app.data_client import DataClient
 from viam.app.ml_training_client import MLTrainingClient
 from viam.app.provisioning_client import ProvisioningClient
-from viam.rpc.dial import DialOptions, _dial_app, _get_access_token
+from viam.robot.client import RobotClient
+from viam.rpc.dial import Credentials, DialOptions, _dial_app, _get_access_token
 
 LOGGER = logging.getLogger(__name__)
 
@@ -18,19 +20,51 @@ class ViamClient:
     """gRPC client for all communication and interaction with app.
 
     `ViamClient` class for creating and managing specialized client instances.
-    There is currently 1 way to instantiate a `ViamClient` object::
+    There are currently 2 ways to instantiate a `ViamClient` object::
 
         ViamClient.create_from_dial_options(...)
+        ViamClient.create_from_env_vars()
     """
 
+    @classmethod
+    async def create_from_env_vars(cls, dial_options: Optional[DialOptions] = None, app_url: Optional[str] = None) -> Self:
+        """Create `ViamClient` using credentials set in the environment as `VIAM_API_KEY` and `VIAM_API_KEY_ID`.
+
+        ::
+
+            client = await ViamClient.create_from_env_vars()
+
+        Args:
+            dial_options (Optional[viam.rpc.dial.DialOptions]): Options for authorization and connection to app.
+                If not provided, default options will be selected. Note that `creds` and `auth_entity`
+                fields will be overwritten by the values set by a module.
+            app_url: (Optional[str]): URL of app. Uses app.viam.com if not specified.
+
+        Raises:
+            ValueError: If there are no env vars set by the module, or if they are set improperly
+
+        """
+        dial_options = dial_options if dial_options else DialOptions()
+        api_key = os.environ.get("VIAM_API_KEY")
+        if api_key is None:
+            raise ValueError("api key cannot be None")
+        api_key_id = os.environ.get("VIAM_API_KEY_ID")
+        if api_key_id is None:
+            raise ValueError("api key ID cannot be None")
+        credentials = Credentials(type="api-key", payload=api_key)
+        dial_options.credentials = credentials
+        dial_options.auth_entity = api_key_id
+
+        return await cls.create_from_dial_options(dial_options, app_url)
+
     @classmethod
     async def create_from_dial_options(cls, dial_options: DialOptions, app_url: Optional[str] = None) -> Self:
-        """Create `ViamClient` that establishes a connection to the Viam app.
+        """Create `ViamClient` that establishes a connection to Viam.
 
         ::
 
             dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
-            ViamClient.create_from_dial_options(dial_options)
+            client = await ViamClient.create_from_dial_options(dial_options)
 
         Args:
             dial_options (viam.rpc.dial.DialOptions): Required information for authorization and connection to app.
@@ -51,9 +85,7 @@ class ViamClient:
             raise ValueError("dial_options.auth_entity cannot be None.")
 
         self = cls()
-        self._location_id = None
-        if dial_options.credentials.type == "robot-location-secret":
-            self._location_id = dial_options.auth_entity.split(".")[1]
+        self._dial_options = dial_options
         if app_url is None:
             app_url = "app.viam.com"
         self._channel = await _dial_app(app_url)
@@ -64,7 +96,7 @@ class ViamClient:
     _channel: Channel
     _metadata: Mapping[str, str]
     _closed: bool = False
-    _location_id: Optional[str]
+    _dial_options: DialOptions
 
     @property
     def data_client(self) -> DataClient:
@@ -105,7 +137,7 @@ class ViamClient:
                 # Instantiate an AppClient called "fleet" to run fleet management API methods on
                 fleet = viam_client.app_client
         """
-        return AppClient(self._channel, self._metadata, self._location_id)
+        return AppClient(self._channel, self._metadata)
 
     @property
     def ml_training_client(self) -> MLTrainingClient:
@@ -171,7 +203,25 @@ class ViamClient:
         """
         return ProvisioningClient(self._channel, self._metadata)
 
-    def close(self):
+    async def __aenter__(self) -> "ViamClient":
+        """A ViamClient can act as an asynchronous context manager. It will do nothing special when
+        the context is entered.
+        """
+        return self
+
+    async def __aexit__(self, exc_type: Optional[type], exc_value: Optional[BaseException], traceback: Optional[Any]) -> None:
+        """A ViamClient can act as an asynchronous context manager. It will close itself when
+        the context is exited.
+
+        ::
+
+            async with ViamClient.create_from_dial_options(...) as client:
+                await do_something_with(client)
+            # client is closed here
+        """
+        self.close()
+
+    def close(self) -> None:
         """Close opened channels used for the various service stubs initialized."""
         if self._closed:
             LOGGER.debug("ViamClient is already closed.")
@@ -179,3 +229,47 @@ class ViamClient:
         LOGGER.debug("Closing gRPC channel to app.")
         self._channel.close()
         self._closed = True
+
+    async def connect_to_machine(self, *, address: Optional[str] = None, id: Optional[str] = None) -> RobotClient:
+        """Connect to a machine using existing credentials.
+
+        A connection can be attempted using either the machine's address or its ID.
+        If both an address and ID are provided, the address will take precedence and the ID will be ignored.
+
+        ::
+
+            async def connect() -> ViamClient:
+                # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
+                dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+                return await ViamClient.create_from_dial_options(dial_options)
+
+
+            async def main():
+                viam_client = await connect()
+
+                # Connect to a machine and obtain a RobotClient
+                # Replace "<MACHINE_ADDRESS>" (including brackets) with your machine's connection address
+                machine = await viam_client.connect_to_machine(address="<MACHINE_ADDRESS>")
+
+        Args:
+            address (Optional[str]): The address (FQDN) of the machine. Defaults to None.
+            id (Optional[str]): The ID (as a UUID) of the machine. Defaults to None.
+
+        Raises:
+            ValueError: If neither an address nor ID is provided.
+
+        Returns:
+            RobotClient: The active connection to the machine.
+        """
+        if address is None and id is None:
+            raise ValueError("Either a machine address or ID must be provided")
+
+        if id is not None and address is None:
+            parts = await self.app_client.get_robot_parts(id)
+            main_part = next(p for p in parts if p.main_part)
+            address = main_part.fqdn
+
+        opts = RobotClient.Options(dial_options=self._dial_options)
+
+        assert address is not None
+        return await RobotClient.at_address(address, opts)

viam/components/arm/__init__.py

@@ -1,11 +1,6 @@
-import asyncio
-
 from viam.proto.common import KinematicsFileFormat, Pose
 from viam.proto.component.arm import JointPositions
-from viam.proto.component.arm import Status as ArmStatus
-from viam.proto.robot import Status
 from viam.resource.registry import Registry, ResourceRegistration
-from viam.utils import message_to_struct
 
 from .arm import Arm
 from .client import ArmClient
@@ -18,23 +13,4 @@ __all__ = [
     "Pose",
 ]
 
-
-async def create_status(component: Arm) -> Status:
-    (
-        end_position,
-        joint_positions,
-        is_moving,
-    ) = await asyncio.gather(
-        component.get_end_position(),
-        component.get_joint_positions(),
-        component.is_moving(),
-    )
-    s = ArmStatus(
-        end_position=end_position,
-        joint_positions=joint_positions,
-        is_moving=is_moving,
-    )
-    return Status(name=Arm.get_resource_name(component.name), status=message_to_struct(s))
-
-
-Registry.register_subtype(ResourceRegistration(Arm, ArmRPCService, lambda name, channel: ArmClient(name, channel), create_status))
+Registry.register_api(ResourceRegistration(Arm, ArmRPCService, lambda name, channel: ArmClient(name, channel)))

viam/components/arm/arm.py

@@ -1,7 +1,7 @@
 import abc
 from typing import Any, Dict, Final, Optional, Tuple
 
-from viam.resource.types import RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, Subtype
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
 
 from ..component_base import ComponentBase
 from . import JointPositions, KinematicsFileFormat, Pose
@@ -23,10 +23,10 @@ class Arm(ComponentBase):
         # To use move_to_joint_positions:
         from viam.proto.component.arm import JointPositions
 
-    For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+    For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/>`_.
     """
 
-    SUBTYPE: Final = Subtype(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "arm")  # pyright: ignore [reportIncompatibleVariableOverride]
+    API: Final = API(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "arm")  # pyright: ignore [reportIncompatibleVariableOverride]
 
     @abc.abstractmethod
     async def get_end_position(
@@ -41,7 +41,7 @@ class Arm(ComponentBase):
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Get the end position of the arm as a Pose.
             pos = await my_arm.get_end_position()
@@ -52,7 +52,7 @@ class Arm(ComponentBase):
             Location is expressed as distance, which is represented by x, y, and z coordinate values.
             Orientation is expressed as an orientation vector, which is represented by o_x, o_y, o_z, and theta values.
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#getendposition>`_.
         """
         ...
 
@@ -70,7 +70,7 @@ class Arm(ComponentBase):
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Create a Pose for the arm.
             examplePose = Pose(x=5, y=5, z=5, o_x=5, o_y=5, o_z=5, theta=20)
@@ -84,7 +84,7 @@ class Arm(ComponentBase):
                 Location is expressed as distance, which is represented by x, y, and z coordinate values.
                 Orientation is expressed as an orientation vector, which is represented by o_x, o_y, o_z, and theta values.
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#movetoposition>`_.
         """
         ...
 
@@ -102,15 +102,14 @@ class Arm(ComponentBase):
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Declare a list of values with your desired rotational value for each joint on
-            # the arm.
+            # the arm. This example is for a 5dof arm.
             degrees = [0.0, 45.0, 0.0, 0.0, 0.0]
 
             # Declare a new JointPositions with these values.
-            jointPos = arm.move_to_joint_positions(
-                JointPositions(values=[0.0, 45.0, 0.0, 0.0, 0.0]))
+            jointPos = JointPositions(values=degrees)
 
             # Move each joint of the arm to the position these values specify.
             await my_arm.move_to_joint_positions(positions=jointPos)
@@ -118,7 +117,7 @@ class Arm(ComponentBase):
         Args:
             positions (JointPositions): The destination ``JointPositions`` for the arm.
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#movetojointpositions>`_.
         """
         ...
 
@@ -135,7 +134,7 @@ class Arm(ComponentBase):
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Get the current position of each joint on the arm as JointPositions.
             pos = await my_arm.get_joint_positions()
@@ -145,7 +144,7 @@ class Arm(ComponentBase):
             ``JointPositions`` can have one attribute, ``values``, a list of joint positions with rotational values (degrees)
             and translational values (mm).
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#getjointpositions>`_.
         """
         ...
 
@@ -162,12 +161,12 @@ class Arm(ComponentBase):
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Stop all motion of the arm. It is assumed that the arm stops immediately.
             await my_arm.stop()
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#stop>`_.
         """
         ...
 
@@ -178,31 +177,31 @@ class Arm(ComponentBase):
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Stop all motion of the arm. It is assumed that the arm stops immediately.
             await my_arm.stop()
 
             # Print if the arm is currently moving.
-            print(my_arm.is_moving())
+            print(await my_arm.is_moving())
 
         Returns:
             bool: Whether the arm is moving.
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#ismoving>`_.
         """
         ...
 
     @abc.abstractmethod
     async def get_kinematics(
-        self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None
+        self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs
     ) -> Tuple[KinematicsFileFormat.ValueType, bytes]:
         """
         Get the kinematics information associated with the arm.
 
         ::
 
-            my_arm = Arm.from_robot(robot=robot, name="my_arm")
+            my_arm = Arm.from_robot(robot=machine, name="my_arm")
 
             # Get the kinematics information associated with the arm.
             kinematics = await my_arm.get_kinematics()
@@ -219,6 +218,6 @@ class Arm(ComponentBase):
             Viam's kinematic parameter format (spatial vector algebra) (``KinematicsFileFormat.KINEMATICS_FILE_FORMAT_SVA``),
             and the second [1] value represents the byte contents of the file.
 
-        For more information, see `Arm component <https://docs.viam.com/components/arm/>`_.
+        For more information, see `Arm component <https://docs.viam.com/dev/reference/apis/components/arm/#getkinematics>`_.
         """
         ...