viam-sdk 0.3.0__py3-none-linux_armv6l.whl → 0.66.0__py3-none-linux_armv6l.whl

viam/proto/service/slam/__init__.py

@@ -2,7 +2,8 @@
 @generated by Viam.
 Do not edit manually!
 """
-from ....gen.service.slam.v1.slam_grpc import SLAMServiceBase, SLAMServiceStub
+
+from ....gen.service.slam.v1.slam_grpc import SLAMServiceBase, SLAMServiceStub, UnimplementedSLAMServiceBase
 from ....gen.service.slam.v1.slam_pb2 import (
     GetInternalStateRequest,
     GetInternalStateResponse,
@@ -10,15 +11,26 @@ from ....gen.service.slam.v1.slam_pb2 import (
     GetPointCloudMapResponse,
     GetPositionRequest,
     GetPositionResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+    MappingMode,
+    SensorInfo,
+    SensorType,
 )
 
 __all__ = [
     "SLAMServiceBase",
     "SLAMServiceStub",
+    "UnimplementedSLAMServiceBase",
     "GetInternalStateRequest",
     "GetInternalStateResponse",
     "GetPointCloudMapRequest",
     "GetPointCloudMapResponse",
     "GetPositionRequest",
     "GetPositionResponse",
+    "GetPropertiesRequest",
+    "GetPropertiesResponse",
+    "MappingMode",
+    "SensorInfo",
+    "SensorType",
 ]

viam/proto/service/video/__init__.py

@@ -0,0 +1,15 @@
+"""
+@generated by Viam.
+Do not edit manually!
+"""
+
+from ....gen.service.video.v1.video_grpc import UnimplementedVideoServiceBase, VideoServiceBase, VideoServiceStub
+from ....gen.service.video.v1.video_pb2 import GetVideoRequest, GetVideoResponse
+
+__all__ = [
+    "UnimplementedVideoServiceBase",
+    "VideoServiceBase",
+    "VideoServiceStub",
+    "GetVideoRequest",
+    "GetVideoResponse",
+]

viam/proto/service/vision/__init__.py

@@ -2,8 +2,11 @@
 @generated by Viam.
 Do not edit manually!
 """
-from ....gen.service.vision.v1.vision_grpc import VisionServiceBase, VisionServiceStub
+
+from ....gen.service.vision.v1.vision_grpc import UnimplementedVisionServiceBase, VisionServiceBase, VisionServiceStub
 from ....gen.service.vision.v1.vision_pb2 import (
+    CaptureAllFromCameraRequest,
+    CaptureAllFromCameraResponse,
     Classification,
     Detection,
     GetClassificationsFromCameraRequest,
@@ -16,11 +19,16 @@ from ....gen.service.vision.v1.vision_pb2 import (
     GetDetectionsResponse,
     GetObjectPointCloudsRequest,
     GetObjectPointCloudsResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
 )
 
 __all__ = [
+    "UnimplementedVisionServiceBase",
     "VisionServiceBase",
     "VisionServiceStub",
+    "CaptureAllFromCameraRequest",
+    "CaptureAllFromCameraResponse",
     "Classification",
     "Detection",
     "GetClassificationsFromCameraRequest",
@@ -33,4 +41,6 @@ __all__ = [
     "GetDetectionsResponse",
     "GetObjectPointCloudsRequest",
     "GetObjectPointCloudsResponse",
+    "GetPropertiesRequest",
+    "GetPropertiesResponse",
 ]

viam/proto/service/worldstatestore/__init__.py

@@ -0,0 +1,32 @@
+"""
+@generated by Viam.
+Do not edit manually!
+"""
+
+from ....gen.service.worldstatestore.v1.world_state_store_grpc import (
+    UnimplementedWorldStateStoreServiceBase,
+    WorldStateStoreServiceBase,
+    WorldStateStoreServiceStub,
+)
+from ....gen.service.worldstatestore.v1.world_state_store_pb2 import (
+    GetTransformRequest,
+    GetTransformResponse,
+    ListUUIDsRequest,
+    ListUUIDsResponse,
+    StreamTransformChangesRequest,
+    StreamTransformChangesResponse,
+    TransformChangeType,
+)
+
+__all__ = [
+    "UnimplementedWorldStateStoreServiceBase",
+    "WorldStateStoreServiceBase",
+    "WorldStateStoreServiceStub",
+    "GetTransformRequest",
+    "GetTransformResponse",
+    "ListUUIDsRequest",
+    "ListUUIDsResponse",
+    "StreamTransformChangesRequest",
+    "StreamTransformChangesResponse",
+    "TransformChangeType",
+]

viam/proto/stream/__init__.py

@@ -0,0 +1,36 @@
+"""
+@generated by Viam.
+Do not edit manually!
+"""
+
+from ...gen.stream.v1.stream_grpc import StreamServiceBase, StreamServiceStub, UnimplementedStreamServiceBase
+from ...gen.stream.v1.stream_pb2 import (
+    AddStreamRequest,
+    AddStreamResponse,
+    GetStreamOptionsRequest,
+    GetStreamOptionsResponse,
+    ListStreamsRequest,
+    ListStreamsResponse,
+    RemoveStreamRequest,
+    RemoveStreamResponse,
+    Resolution,
+    SetStreamOptionsRequest,
+    SetStreamOptionsResponse,
+)
+
+__all__ = [
+    "StreamServiceBase",
+    "StreamServiceStub",
+    "UnimplementedStreamServiceBase",
+    "AddStreamRequest",
+    "AddStreamResponse",
+    "GetStreamOptionsRequest",
+    "GetStreamOptionsResponse",
+    "ListStreamsRequest",
+    "ListStreamsResponse",
+    "RemoveStreamRequest",
+    "RemoveStreamResponse",
+    "Resolution",
+    "SetStreamOptionsRequest",
+    "SetStreamOptionsResponse",
+]

viam/resource/base.py

@@ -1,4 +1,5 @@
-from abc import abstractclassmethod, abstractmethod
+from abc import abstractmethod
+from logging import Logger
 from typing import TYPE_CHECKING, Any, ClassVar, Mapping, Optional, Protocol, runtime_checkable
 
 from typing_extensions import Self
@@ -6,7 +7,7 @@ from typing_extensions import Self
 from viam.operations import Operation
 from viam.proto.common import ResourceName
 
-from .types import Subtype
+from .types import API
 
 if TYPE_CHECKING:
     from viam.robot.client import RobotClient
@@ -19,31 +20,48 @@ class ResourceBase(Protocol):
     The base requirements for a Resource.
     """
 
-    SUBTYPE: ClassVar["Subtype"]
-    """The Subtype of the Resource"""
+    API: ClassVar["API"]
+    """The API of the Resource"""
 
     name: str
     """The name of the Resource"""
 
+    logger: Logger
+    """A logger allowing for setting log levels on a per-resource basis"""
+
     @classmethod
     def get_resource_name(cls, name: str) -> ResourceName:
         """
         Get the ResourceName for this Resource with the given name
 
+        ::
+
+            # Can be used with any resource, using an arm as an example
+            my_arm_name = Arm.get_resource_name("my_arm")
+
         Args:
             name (str): The name of the Resource
+
+        Returns:
+            ResourceName: The ResourceName of this Resource
         """
         return ResourceName(
-            namespace=cls.SUBTYPE.namespace,
-            type=cls.SUBTYPE.resource_type,
-            subtype=cls.SUBTYPE.resource_subtype,
+            namespace=cls.API.namespace,
+            type=cls.API.resource_type,
+            subtype=cls.API.resource_subtype,
             name=name,
         )
 
-    @abstractclassmethod
+    @classmethod
+    @abstractmethod
     def from_robot(cls, robot: "RobotClient", name: str) -> Self:
         """Get the Resource named ``name`` from the provided robot.
 
+        ::
+
+            # Can be used with any resource, using an arm as an example
+            my_arm = Arm.from_robot(robot, "my_arm")
+
         Args:
             robot (RobotClient): The robot
             name (str): The name of the Resource
@@ -59,6 +77,11 @@ class ResourceBase(Protocol):
     ) -> Mapping[str, "ValueTypes"]:
         """Send/Receive arbitrary commands to the Resource
 
+        ::
+
+            command = {"cmd": "test", "data1": 500}
+            result = await component.do_command(command)
+
         Args:
             command (Mapping[str, ValueTypes]): The command to execute
 
@@ -84,3 +107,17 @@ class ResourceBase(Protocol):
             viam.operations.Operation: The operation associated with this function
         """
         return kwargs.get(Operation.ARG_NAME, Operation._noop())
+
+    async def close(self):
+        """Safely shut down the resource and prevent further use.
+
+        Close must be idempotent. Later configuration may allow a resource to be "open" again.
+        If a resource does not want or need a close function, it is assumed that the resource does not need to return errors when future
+        non-Close methods are called.
+
+        ::
+
+            await component.close()
+
+        """
+        return

viam/resource/easy_resource.py

@@ -0,0 +1,149 @@
+import inspect
+import re
+from abc import ABCMeta
+from typing import Callable, ClassVar, Mapping, Sequence, Tuple, Union
+
+from viam.proto.app.robot import ComponentConfig
+from viam.proto.common import ResourceName
+
+from .. import logging
+from ..errors import MethodNotImplementedError
+from .base import ResourceBase
+from .registry import Registry, ResourceCreatorRegistration
+from .types import API, Model, ModelFamily
+
+modelRegex = re.compile(r"^([^:]+):([^:]+):([^:]+)$")
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_model(orig: Union[str, Model]) -> Model:
+    "take a model or string and turn it into a Model"
+    if isinstance(orig, Model):
+        return orig
+    match = modelRegex.match(orig)
+    if not match:
+        raise ValueError(f"MODEL {orig} doesn't match expected format 'org:type:name'")
+    *family, name = match.groups()
+    return Model(ModelFamily(*family), name)
+
+
+def _create_stub_fn(name: str, is_async: bool) -> Callable:
+    """
+    This creates a sync or async stub function which returns a MethodNotImplementedError.
+    The stub_model decorator uses these to stub out an abstract base class.
+    """
+    if is_async:
+        # note: this is a pyright bug https://github.com/microsoft/pyright/issues/2136
+        async def stub_fn(*args, **kwargs):  # pyright: ignore [reportRedeclaration]
+            logger.info(f"{name} not implemented")
+            raise MethodNotImplementedError(name)
+
+    else:
+
+        def stub_fn(*args, **kwargs):
+            logger.info(f"{name} not implemented")
+            raise MethodNotImplementedError(name)
+
+    stub_fn.__name__ = f"{name}_stub"
+    return stub_fn
+
+
+def stub_model(cls: ABCMeta) -> ABCMeta:
+    """
+    Class decorator which adds error implementations of abstract functions. This means they will fail
+    when called, rather than the default where they fail when instantiated. This is intended for developers
+    who want to build and test incrementally, not for production use.
+
+    Example:
+
+        @stub_model
+        class MyMotor(Motor, EasyResource):
+            MODEL = 'viam:motor:easy-resource-example'
+
+    Normally this class would fail to instantiate. With the decorator, it will succeed but the unimplemented
+    methods will throw errors at runtime.
+    """
+    for attr in list(cls.__abstractmethods__):
+        val = getattr(cls, attr)
+        is_async = inspect.iscoroutinefunction(val)
+        stub_fn = _create_stub_fn(attr, is_async)
+        setattr(cls, attr, stub_fn)
+        logger.debug("patched %s.%s with %s", cls, attr, stub_fn)
+        cls.__abstractmethods__ -= {attr}
+    return cls
+
+
+class EasyResource:
+    """
+    EasyResource is a mixin that simplifies the process of creating Viam modules (extension programs)
+    and resources (the resource classes provided by those extension programs).
+
+    Basic usage:
+
+    ::
+
+        class MyModel(Sensor, EasyResource):
+            MODEL = "my-org:sensor:my-sensor"
+
+            async def get_readings(self, **kwargs):
+                return {"ok": True}
+
+    See examples/easy_resource/main.py for extended usage.
+    """
+
+    API: ClassVar[API]
+    MODEL: ClassVar[Model]
+
+    def __init_subclass__(cls, register=True, **kwargs):
+        """
+        When you subclass this mixin, it parses cls.MODEL and registers cls in global registry.
+        """
+        super().__init_subclass__(**kwargs)
+        if not hasattr(cls, "MODEL"):
+            raise ValueError("Please define a MODEL with the format 'org:type:name' on your class, for example 'viam:camera:IMX219'")
+        cls.MODEL = _parse_model(cls.MODEL)
+        if register:
+            cls.register()
+
+    def __init__(self, name: str):
+        # note: this mirrors the constructor for ComponentBase and ServiceBase.
+        self.name = name
+
+    @classmethod
+    def new(cls, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]):
+        """
+        This is passed to register_resource_creator. The default implementation only sets the resource name
+        when an instance of your model is instantiated. You can override this in your subclass.
+        """
+        self = cls(config.name)
+        logger.debug("created %s %s %s", cls.API, cls.MODEL, config.name)
+        return self
+
+    @classmethod
+    def validate_config(cls, config: ComponentConfig) -> Tuple[Sequence[str], Sequence[str]]:
+        """This method allows you to validate the configuration object received from the machine,
+        as well as to return any implicit dependencies based on that `config`.
+
+        Args:
+            config (ComponentConfig): The configuration for this resource
+
+        Returns:
+            Tuple[Sequence[str], Sequence[str]]: One list of required implicit dependencies and one of optional deps.
+        """
+        return [], []
+
+    @classmethod
+    def register(cls):
+        """
+        This adds the model to the global registry. It is called by __init_subclass__ and you typically
+        won't call it directly.
+        """
+        logger.debug("registering %s %s", cls.API, cls.MODEL)
+        # note: We could fix this pyright-ignore if EasyResource inherited ResourceBase, but that crashes in the mro()
+        # walk in ResourceManager.register.
+        Registry.register_resource_creator(
+            cls.API,
+            cls.MODEL,
+            ResourceCreatorRegistration(cls.new, cls.validate_config),  # pyright: ignore [reportArgumentType]
+        )

viam/resource/manager.py

@@ -1,6 +1,7 @@
 from threading import RLock
 from typing import Dict, List, Type, TypeVar
 
+from viam.logging import getLogger
 from viam.proto.common import ResourceName
 from viam.resource.base import ResourceBase
 from viam.resource.registry import Registry
@@ -9,6 +10,7 @@ from ..components.component_base import ComponentBase
 from ..errors import DuplicateResourceError, ResourceNotFoundError
 from ..services.service_base import ServiceBase
 
+LOGGER = getLogger(__name__)
 ResourceType = TypeVar("ResourceType", bound=ResourceBase)
 
 
@@ -28,29 +30,30 @@ class ResourceManager:
         for component in components:
             self.register(component)
 
-    def register(self, component: ResourceBase):
+    def register(self, resource: ResourceBase):
         """
-        Register a new component with the registry.
-        Components may not have the same name.
-        If a component is remote and the short name is unique, save a short name version.
+        Register a new resource with the registry.
+        Resources may not have the same name.
+        If a resource is remote and the short name is unique, save a short name version.
 
         Raises:
-            DuplicateComponentError: Error if attempting to register component
-                                     with the name of an existing component
+            DuplicateResourceError: Error if attempting to register resource
+                                     with the name of an existing resource
+            ResourceNotFoundError: Raised if the API of the resource is not registered
 
         Args:
-            component (ResourceBase): The component to register
+            resource (ResourceBase): The resource to register
         """
-        Registry.lookup_subtype(component.SUBTYPE)  # confirm the subtype is registered in Registry
+        Registry.lookup_api(resource.API)  # confirm the API is registered in Registry
 
         _BaseClasses = (ResourceBase, ComponentBase, ServiceBase)
         rnames: Dict[ResourceName, ResourceBase] = {}
-        for subtype in component.__class__.mro():
+        for subtype in resource.__class__.mro():
             if subtype in _BaseClasses:
                 continue
             if hasattr(subtype, "get_resource_name"):
-                rn = subtype.get_resource_name(component.name)  # type: ignore
-                rnames[rn] = component
+                rn = subtype.get_resource_name(resource.name)  # type: ignore
+                rnames[rn] = resource
         for rn in rnames:
             if ":" in rn.name:
                 short_name = rn.name.split(":")[-1]
@@ -60,7 +63,7 @@ class ResourceManager:
                     self._short_to_long_name[short_name] = [rn]
 
         if rnames.keys() & self.resources.keys():
-            raise DuplicateResourceError(component.name)
+            raise DuplicateResourceError(resource.name)
 
         with self._lock:
             self.resources.update(rnames)
@@ -90,14 +93,32 @@ class ResourceManager:
                 return self.get_resource(of_type, self._short_to_long_name[name.name][0])
             raise ResourceNotFoundError(name.subtype, name.name)
 
-    def remove_resource(self, name: ResourceName):
+    async def remove_resource(self, name: ResourceName):
         """Remove the resource with the specified ```ResourceName```.
 
         Args:
             name (viam.proto.common.ResourceName): The ResourceName of the resource
         """
         with self._lock:
-            del self.resources[name]
+            try:
+                resource = self.resources[name]
+                await resource.close()
+            finally:
+                try:
+                    del self.resources[name]
+                except KeyError:
+                    pass
+
+    async def close(self):
+        """Close the resourcce manager by removing all resources.
+        Please note that any errors will not raise an exception. Errors will still be logged."""
+        rns = [key for key in self.resources.keys()]
+        with self._lock:
+            for rn in rns:
+                try:
+                    await self.remove_resource(rn)
+                except Exception as e:
+                    LOGGER.error(f"Error while closing {rn.name}:", e)
 
     def _resource_by_name_only(self, name: str) -> ResourceBase:
         for rname, resource in self.resources.items():