viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/proto/service/slam/__init__.py

@@ -0,0 +1,36 @@
+"""
+@generated by Viam.
+Do not edit manually!
+"""
+
+from ....gen.service.slam.v1.slam_grpc import SLAMServiceBase, SLAMServiceStub, UnimplementedSLAMServiceBase
+from ....gen.service.slam.v1.slam_pb2 import (
+    GetInternalStateRequest,
+    GetInternalStateResponse,
+    GetPointCloudMapRequest,
+    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/vision/__init__.py

@@ -0,0 +1,46 @@
+"""
+@generated by Viam.
+Do not edit manually!
+"""
+
+from ....gen.service.vision.v1.vision_grpc import UnimplementedVisionServiceBase, VisionServiceBase, VisionServiceStub
+from ....gen.service.vision.v1.vision_pb2 import (
+    CaptureAllFromCameraRequest,
+    CaptureAllFromCameraResponse,
+    Classification,
+    Detection,
+    GetClassificationsFromCameraRequest,
+    GetClassificationsFromCameraResponse,
+    GetClassificationsRequest,
+    GetClassificationsResponse,
+    GetDetectionsFromCameraRequest,
+    GetDetectionsFromCameraResponse,
+    GetDetectionsRequest,
+    GetDetectionsResponse,
+    GetObjectPointCloudsRequest,
+    GetObjectPointCloudsResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+)
+
+__all__ = [
+    "UnimplementedVisionServiceBase",
+    "VisionServiceBase",
+    "VisionServiceStub",
+    "CaptureAllFromCameraRequest",
+    "CaptureAllFromCameraResponse",
+    "Classification",
+    "Detection",
+    "GetClassificationsFromCameraRequest",
+    "GetClassificationsFromCameraResponse",
+    "GetClassificationsRequest",
+    "GetClassificationsResponse",
+    "GetDetectionsFromCameraRequest",
+    "GetDetectionsFromCameraResponse",
+    "GetDetectionsRequest",
+    "GetDetectionsResponse",
+    "GetObjectPointCloudsRequest",
+    "GetObjectPointCloudsResponse",
+    "GetPropertiesRequest",
+    "GetPropertiesResponse",
+]

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/proto/tagger/__init__.py

@@ -0,0 +1,6 @@
+"""
+@generated by Viam.
+Do not edit manually!
+"""
+
+__all__ = []

viam/resource/base.py

@@ -0,0 +1,123 @@
+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
+
+from viam.operations import Operation
+from viam.proto.common import ResourceName
+
+from .types import API
+
+if TYPE_CHECKING:
+    from viam.robot.client import RobotClient
+    from viam.utils import ValueTypes
+
+
+@runtime_checkable
+class ResourceBase(Protocol):
+    """
+    The base requirements for a 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.API.namespace,
+            type=cls.API.resource_type,
+            subtype=cls.API.resource_subtype,
+            name=name,
+        )
+
+    @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
+
+        Returns:
+            Self: The Resource, if it exists on the robot
+        """
+        ...
+
+    @abstractmethod
+    async def do_command(
+        self, command: Mapping[str, "ValueTypes"], *, timeout: Optional[float] = None, **kwargs
+    ) -> 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
+
+        Raises:
+            NotImplementedError: Raised if the Resource does not support arbitrary commands
+
+        Returns:
+            Mapping[str, ValueTypes]: Result of the executed command
+        """
+        ...
+
+    def get_operation(self, kwargs: Mapping[str, Any]) -> Operation:
+        """Get the ``Operation`` associated with the currently running function.
+
+        When writing custom resources, you should get the ``Operation`` by calling this function and check to see if it's cancelled.
+        If the ``Operation`` is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc.
+        ).
+
+        Args:
+            kwargs (Mapping[str, Any]): The kwargs object containing the operation
+
+        Returns:
+            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,153 @@
+import inspect
+import re
+from abc import ABCMeta
+from typing import Callable, ClassVar, Mapping, Sequence, 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 calls reconfigure()
+        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)
+        self.reconfigure(config, dependencies)
+        return self
+
+    @classmethod
+    def validate_config(cls, config: ComponentConfig) -> 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:
+            Sequence[str]: A list of implicit dependencies
+        """
+        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]
+        )
+
+    def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]):
+        logger.debug("reconfigure %s %s", self.API, self.MODEL)

viam/resource/manager.py

@@ -0,0 +1,126 @@
+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
+
+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)
+
+
+class ResourceManager:
+    """
+    Registry containing all components registered to this server.
+    """
+
+    resources: Dict[ResourceName, ResourceBase]
+    _short_to_long_name: Dict[str, List[ResourceName]]
+    _lock: RLock
+
+    def __init__(self, components: List[ResourceBase] = []) -> None:
+        self._lock = RLock()
+        self.resources = {}
+        self._short_to_long_name = {}
+        for component in components:
+            self.register(component)
+
+    def register(self, resource: ResourceBase):
+        """
+        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:
+            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:
+            resource (ResourceBase): The resource to register
+        """
+        Registry.lookup_api(resource.API)  # confirm the API is registered in Registry
+
+        _BaseClasses = (ResourceBase, ComponentBase, ServiceBase)
+        rnames: Dict[ResourceName, ResourceBase] = {}
+        for subtype in resource.__class__.mro():
+            if subtype in _BaseClasses:
+                continue
+            if hasattr(subtype, "get_resource_name"):
+                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]
+                if short_name in self._short_to_long_name and rn not in self._short_to_long_name[short_name]:
+                    self._short_to_long_name[short_name].append(rn)
+                elif short_name not in self._short_to_long_name:
+                    self._short_to_long_name[short_name] = [rn]
+
+        if rnames.keys() & self.resources.keys():
+            raise DuplicateResourceError(resource.name)
+
+        with self._lock:
+            self.resources.update(rnames)
+
+    def get_resource(self, of_type: Type[ResourceType], name: ResourceName) -> ResourceType:
+        """
+        Return a resource from the registry.
+        If a unique short name version is given, return a remote resource with the name.
+
+        Args:
+            of_type (Type[ResourceType]): The type of the resource
+            name (viam.proto.common.ResourceName): The name of the resource
+
+        Raises:
+            ResourceNotFoundError: Error if resource with the given type
+                                    and name does not exist in the registry
+
+        Returns:
+            ResourceType: The resource
+        """
+        with self._lock:
+            resource = self.resources.get(name, None)
+            if resource and isinstance(resource, of_type):
+                return resource
+
+            if name.name in self._short_to_long_name and len(self._short_to_long_name[name.name]) == 1:
+                return self.get_resource(of_type, self._short_to_long_name[name.name][0])
+            raise ResourceNotFoundError(name.subtype, name.name)
+
+    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:
+            try:
+                resource = self.resources[name]
+                await resource.close()
+            except Exception as e:
+                raise e
+            finally:
+                del self.resources[name]
+
+    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():
+            if rname.name == name:
+                return resource
+        raise ResourceNotFoundError("resource", name)