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

viam/resource/registry.py

@@ -1,26 +1,20 @@
 from dataclasses import dataclass
 from threading import Lock
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Coroutine, Dict, Generic, Mapping, Type, TypeVar
+from typing import TYPE_CHECKING, Callable, ClassVar, Dict, Generic, Mapping, Type, TypeVar
 
-from google.protobuf.struct_pb2 import Struct
 from grpclib.client import Channel
 
 from viam.errors import DuplicateResourceError, ResourceNotFoundError, ValidationError
-from viam.proto.robot import Status
 
 from .base import ResourceBase
 
 if TYPE_CHECKING:
     from .rpc_service_base import ResourceRPCServiceBase
-    from .types import Model, ResourceCreator, Subtype, Validator
+    from .types import API, Model, ResourceCreator, Validator
 
 Resource = TypeVar("Resource", bound=ResourceBase)
 
 
-async def default_create_status(resource: ResourceBase) -> Status:
-    return Status(name=resource.get_resource_name(resource.name), status=Struct())
-
-
 @dataclass
 class ResourceCreatorRegistration:
     """An object representing a resource creator to be registered.
@@ -33,7 +27,7 @@ class ResourceCreatorRegistration:
     """A function that can create a resource given a mapping of dependencies (``ResourceName`` to ``ResourceBase``
     """
 
-    validator: "Validator" = lambda x: []
+    validator: "Validator" = lambda x: ([], [])
     """A function that can validate a resource and return implicit dependencies.
 
     If called without a validator function, default to a function returning an empty Sequence
@@ -63,12 +57,6 @@ class ResourceRegistration(Generic[Resource]):
     """A function that will create the RPC client for this resource
     """
 
-    create_status: Callable[[Resource], Coroutine[Any, Any, Status]] = default_create_status
-    """A function to create a Status object for this resource.
-
-    If the resource does not provide a custom status type, the default implementation can be used.
-    """
-
 
 class Registry:
     """The global registry of robotic parts.
@@ -76,50 +64,50 @@ class Registry:
     **NB** The Registry should almost never be used directly
 
     The Registry keeps track of the types of Resources that are available on robots using this SDK. All the base resource types are
-    pre-registered (e.g. Arm, Motor).
+    pre-registered (for example Arm, Motor).
 
     If you create a new resource type that is not an extension of any of the existing base resource types, then you must register said
     resource using ``Registry.register(...)``.
     """
 
-    _SUBTYPES: ClassVar[Dict["Subtype", ResourceRegistration]] = {}
+    _APIS: ClassVar[Dict["API", ResourceRegistration]] = {}
     _RESOURCES: ClassVar[Dict[str, ResourceCreatorRegistration]] = {}
     _lock: ClassVar[Lock] = Lock()
 
     @classmethod
-    def register_subtype(cls, registration: ResourceRegistration[Resource]):
-        """Register a Subtype with the Registry
+    def register_api(cls, registration: ResourceRegistration[Resource]):
+        """Register a API with the Registry
 
         Args:
-            registration (ResourceRegistration): Object containing registration data for the subtype
+            registration (ResourceRegistration): Object containing registration data for the API
 
         Raises:
-            DuplicateResourceError: Raised if the Subtype to register is already in the registry
+            DuplicateResourceError: Raised if the API to register is already in the registry
             ValidationError: Raised if registration is missing any necessary parameters
         """
         with cls._lock:
-            if registration.resource_type.SUBTYPE in cls._SUBTYPES:
-                raise DuplicateResourceError(str(registration.resource_type.SUBTYPE))
+            if registration.resource_type.API in cls._APIS:
+                raise DuplicateResourceError(str(registration.resource_type.API))
 
             if registration.resource_type and registration.rpc_service and registration.create_rpc_client:
-                cls._SUBTYPES[registration.resource_type.SUBTYPE] = registration
+                cls._APIS[registration.resource_type.API] = registration
             else:
                 raise ValidationError("Passed resource registration does not have correct parameters")
 
     @classmethod
-    def register_resource_creator(cls, subtype: "Subtype", model: "Model", registration: ResourceCreatorRegistration):
-        """Register a specific ``Model`` and validator function for the specific resource ``Subtype`` with the Registry
+    def register_resource_creator(cls, api: "API", model: "Model", registration: ResourceCreatorRegistration):
+        """Register a specific ``Model`` and validator function for the specific resource ``API`` with the Registry
 
         Args:
-            subtype (Subtype): The Subtype of the resource
+            api (API): The API of the resource
             model (Model): The Model of the resource
             registration (ResourceCreatorRegistration): The registration functions of the model
 
         Raises:
-            DuplicateResourceError: Raised if the Subtype and Model pairing is already registered
+            DuplicateResourceError: Raised if the API and Model pairing is already registered
             ValidationError: Raised if registration does not have creator
         """
-        key = f"{subtype}/{model}"
+        key = f"{api}/{model}"
         with cls._lock:
             if key in cls._RESOURCES:
                 raise DuplicateResourceError(key)
@@ -130,78 +118,78 @@ class Registry:
                 raise ValidationError("A creator function was not provided")
 
     @classmethod
-    def lookup_subtype(cls, subtype: "Subtype") -> ResourceRegistration:
-        """Lookup and retrieve a registered Subtype by its name
+    def lookup_api(cls, api: "API") -> ResourceRegistration:
+        """Lookup and retrieve a registered API by its name
 
         Args:
-            subtype (str): The subtype of the resource
+            api (str): The API of the resource
 
         Raises:
-            ResourceNotFoundError: Raised if the Subtype is not registered
+            ResourceNotFoundError: Raised if the API is not registered
 
         Returns:
             ResourceRegistration: The registration object of the resource
         """
         with cls._lock:
             try:
-                return cls._SUBTYPES[subtype]
+                return cls._APIS[api]
             except KeyError:
-                raise ResourceNotFoundError(subtype.resource_type, subtype.resource_subtype)
+                raise ResourceNotFoundError(api.resource_type, api.resource_subtype)
 
     @classmethod
-    def lookup_resource_creator(cls, subtype: "Subtype", model: "Model") -> "ResourceCreator":
-        """Lookup and retrieve a registered resource creator by its subtype and model
+    def lookup_resource_creator(cls, api: "API", model: "Model") -> "ResourceCreator":
+        """Lookup and retrieve a registered resource creator by its API and model
 
         Args:
-            subtype (Subtype): The Subtype of the resource
+            api (API): The API of the resource
             model (Model): The Model of the resource
 
         Raises:
-            ResourceNotFoundError: Raised if the Subtype Model pairing is not registered
+            ResourceNotFoundError: Raised if the API Model pairing is not registered
 
         Returns:
             ResourceCreator: The function to create the resource
         """
         with cls._lock:
             try:
-                return cls._RESOURCES[f"{subtype}/{model}"].creator
+                return cls._RESOURCES[f"{api}/{model}"].creator
             except KeyError:
-                raise ResourceNotFoundError(subtype.resource_type, subtype.resource_subtype)
+                raise ResourceNotFoundError(api.resource_type, api.resource_subtype)
 
     @classmethod
-    def lookup_validator(cls, subtype: "Subtype", model: "Model") -> "Validator":
-        """Lookup and retrieve a registered validator function by its subtype and model. If there is none, return None
+    def lookup_validator(cls, api: "API", model: "Model") -> "Validator":
+        """Lookup and retrieve a registered validator function by its API and model. If there is none, return None
 
         Args:
-            subtype (Subtype): The Subtype of the resource
+            api (API): The API of the resource
             model (Model): The Model of the resource
 
         Returns:
             Validator: The function to validate the resource
         """
         try:
-            return cls._RESOURCES[f"{subtype}/{model}"].validator
+            return cls._RESOURCES[f"{api}/{model}"].validator
         except AttributeError:
-            return lambda x: []
+            return lambda x: ([], [])
         except KeyError:
-            raise ResourceNotFoundError(subtype.resource_type, subtype.resource_subtype)
+            raise ResourceNotFoundError(api.resource_type, api.resource_subtype)
 
     @classmethod
-    def REGISTERED_SUBTYPES(cls) -> Mapping["Subtype", ResourceRegistration]:
+    def REGISTERED_APIS(cls) -> Mapping["API", ResourceRegistration]:
         """The dictionary of all registered resources
-        - Key: Subtype of the resource
+        - Key: API of the resource
         - Value: The registration object for the resource
 
         Returns:
-            Mapping[Subtype, ResourceRegistration]: All registered resources
+            Mapping[API, ResourceRegistration]: All registered resources
         """
         with cls._lock:
-            return cls._SUBTYPES.copy()
+            return cls._APIS.copy()
 
     @classmethod
     def REGISTERED_RESOURCE_CREATORS(cls) -> Mapping[str, "ResourceCreatorRegistration"]:
         """The dictionary of all registered resources
-        - Key: subtype/model
+        - Key: API/model
         - Value: The ResourceCreatorRegistration for the resource
 
         Returns:

viam/resource/rpc_client_base.py

@@ -1,4 +1,6 @@
-from typing import Any, Protocol, runtime_checkable
+from random import choice
+from string import ascii_lowercase
+from typing import Any, Dict, Protocol, runtime_checkable
 
 from grpclib.client import Channel
 
@@ -12,6 +14,36 @@ class ResourceRPCClientBase(Protocol):
     Resource RPC clients must inherit from this class
     """
 
+    class Metadata:
+        metadata: Dict[str, str] = {}
+
+        def enable_debug_logging(self, key: str = ""):
+            """Enables server-side debug logging for resource methods.
+
+            Args:
+                key (str): The key to associate debug logs with. If not provided, will default to a randomly generated string value.
+            """
+            if key == "":
+                key = "".join(choice(ascii_lowercase) for i in range(6))
+            self.metadata["dtname"] = key
+
+        def disable_debug_logging(self):
+            """Disables server-side debug logging for resource methods."""
+            del self.metadata["dtname"]
+
+        def add_metadata(self, key: str, value: str):
+            """Adds a key-value pair to the metadata"""
+            self.metadata[key] = value
+
+        def delete_metadata(self, key: str):
+            """Removes a key-value pair from the metadata by key"""
+            del self.metadata[key]
+
+        @property
+        def proto(self):
+            """Returns metadata in a gRPC-appropriate form"""
+            return [(k, v) for k, v in self.metadata.items()]
+
     channel: Channel
     client: Any
 

viam/resource/rpc_service_base.py

@@ -1,13 +1,17 @@
 import abc
-from typing import Generic, Type
+from typing import TYPE_CHECKING, Generic, Type
 
 from viam.components.component_base import ComponentBase
-from viam.resource.manager import ResourceManager, ResourceType
+from viam.errors import ResourceNotFoundError
+from viam.resource.manager import ResourceType
 from viam.rpc.types import RPCServiceBase
 from viam.services.service_base import ServiceBase
 
 from .base import ResourceBase
 
+if TYPE_CHECKING:
+    from viam.resource.manager import ResourceManager
+
 
 class ResourceRPCServiceBase(abc.ABC, RPCServiceBase, Generic[ResourceType]):
     """
@@ -16,9 +20,9 @@ class ResourceRPCServiceBase(abc.ABC, RPCServiceBase, Generic[ResourceType]):
     """
 
     RESOURCE_TYPE = Type
-    manager: ResourceManager
+    manager: "ResourceManager"
 
-    def __init__(self, manager: ResourceManager):
+    def __init__(self, manager: "ResourceManager"):
         self.manager = manager
 
     def get_resource(self, name: str) -> ResourceType:
@@ -31,11 +35,14 @@ class ResourceRPCServiceBase(abc.ABC, RPCServiceBase, Generic[ResourceType]):
             name (str): Name of the resource
 
         Raises:
-            ResourceNotFoundError
+            GRPCError with the status code Status.NOT_FOUND
 
         Returns:
             ResourceType: The resource
         """
-        if self.RESOURCE_TYPE == ComponentBase or self.RESOURCE_TYPE == ResourceBase or self.RESOURCE_TYPE == ServiceBase:
-            return self.manager._resource_by_name_only(name)  # type: ignore
-        return self.manager.get_resource(self.RESOURCE_TYPE, self.RESOURCE_TYPE.get_resource_name(name))  # type: ignore
+        try:
+            if self.RESOURCE_TYPE == ComponentBase or self.RESOURCE_TYPE == ResourceBase or self.RESOURCE_TYPE == ServiceBase:
+                return self.manager._resource_by_name_only(name)  # type: ignore
+            return self.manager.get_resource(self.RESOURCE_TYPE, self.RESOURCE_TYPE.get_resource_name(name))  # type: ignore
+        except ResourceNotFoundError as e:
+            raise e.grpc_error

viam/resource/types.py

@@ -1,6 +1,6 @@
 import re
 import sys
-from typing import TYPE_CHECKING, Callable, ClassVar, Mapping, Sequence
+from typing import TYPE_CHECKING, Callable, ClassVar, Mapping, Optional, Protocol, Sequence, Tuple, runtime_checkable
 
 if sys.version_info >= (3, 10):
     from typing import TypeAlias
@@ -10,7 +10,7 @@ else:
 from typing_extensions import Self
 
 from viam.proto.app.robot import ComponentConfig
-from viam.proto.common import ResourceName
+from viam.proto.common import GetGeometriesRequest, GetGeometriesResponse, ResourceName
 
 if TYPE_CHECKING:
     from .base import ResourceBase
@@ -20,64 +20,66 @@ RESOURCE_TYPE_COMPONENT = "component"
 RESOURCE_TYPE_SERVICE = "service"
 
 
-class Subtype:
+class API:
     """Represents a known component/service (resource) API"""
 
     namespace: str
     """The namespace of the resource"""
 
     resource_type: str
-    """The type of the resource, e.g. `component` or `service`"""
+    """The type of the resource, for example `component` or `service`"""
 
     resource_subtype: str
-    """The subtype of the resource e.g. `servo`, `arm`, `vision`"""
+    """The subtype of the resource for example `servo`, `arm`, `vision`"""
 
     def __init__(self, namespace: str, resource_type: str, resource_subtype: str):
-        self.namespace = namespace.lower()
-        self.resource_type = resource_type.lower()
-        self.resource_subtype = resource_subtype.lower()
+        self.namespace = namespace
+        self.resource_type = resource_type
+        self.resource_subtype = resource_subtype
 
     def __str__(self) -> str:
         return f"{self.namespace}:{self.resource_type}:{self.resource_subtype}"
 
     def __repr__(self) -> str:
-        return f"<viam.resource.types.Subtype {str(self)} at {hex(id(self))}>"
+        return f"<viam.resource.types.API {str(self)} at {hex(id(self))}>"
 
     def __hash__(self) -> int:
         return hash(str(self))
 
-    def __eq__(self, other: "Subtype") -> bool:
-        return str(self) == str(other)
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, API):
+            return str(self) == str(other)
+        return False
 
     @classmethod
     def from_resource_name(cls, resource_name: ResourceName) -> Self:
-        """Convert a ```ResourceName``` into a ```Subtype```
+        """Convert a ```ResourceName``` into a ```API```
 
         Args:
             resource_name (viam.proto.common.ResourceName): The ResourceName to convert
 
         Returns:
-            Self: A new Subtype
+            Self: A new API
         """
         return cls(resource_name.namespace, resource_name.type, resource_name.subtype)
 
     @classmethod
     def from_string(cls, string: str) -> Self:
-        """Create a ```Subtype``` from its string representation (namespace:resource_type:resource_subtype)
+        """Create a ```API``` from its string representation (namespace:resource_type:resource_subtype)
 
         Args:
-            string (str): The Subtype as a string
+            string (str): The API as a string
 
         Raises:
-            ValueError: Raised if the string does not represent a valid Subtype
+            ValueError: Raised if the string does not represent a valid API
 
         Returns:
-            Self: A new Subtype
+            Self: A new API
         """
         regex = re.compile(r"^([\w-]+):([\w-]+):([\w-]+)$")
         match = regex.match(string)
         if not match:
-            raise ValueError(f"{string} is not a valid Subtype")
+            raise ValueError(f"{string} is not a valid API")
         return cls(match.group(1), match.group(2), match.group(3))
 
 
@@ -95,8 +97,8 @@ class ModelFamily:
     DEFAULT: ClassVar["ModelFamily"]
 
     def __init__(self, namespace: str, family: str):
-        self.namespace = namespace.lower()
-        self.family = family.lower()
+        self.namespace = namespace
+        self.family = family
 
     def __str__(self) -> str:
         return f"{self.namespace}:{self.family}"
@@ -107,8 +109,10 @@ class ModelFamily:
     def __hash__(self) -> int:
         return hash(str(self))
 
-    def __eq__(self, other: "ModelFamily") -> bool:
-        return str(self) == str(other)
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, ModelFamily):
+            return str(self) == str(other)
+        return False
 
 
 ModelFamily.DEFAULT = ModelFamily(RESOURCE_NAMESPACE_RDK, ModelFamily.DEFAULT_FAMILY_NAME)
@@ -125,7 +129,7 @@ class Model:
 
     def __init__(self, model_family: ModelFamily, name: str):
         self.model_family = model_family
-        self.name = name.lower()
+        self.name = name
 
     def __str__(self) -> str:
         return f"{self.model_family}:{self.name}"
@@ -136,8 +140,10 @@ class Model:
     def __hash__(self) -> int:
         return hash(str(self))
 
-    def __eq__(self, other: "Model") -> bool:
-        return str(self) == str(other)
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Model):
+            return str(self) == str(other)
+        return False
 
     @classmethod
     def from_string(cls, model: str, *, ignore_errors=False) -> Self:
@@ -197,4 +203,11 @@ def resource_name_from_string(string: str) -> ResourceName:
 
 
 ResourceCreator: TypeAlias = Callable[[ComponentConfig, Mapping[ResourceName, "ResourceBase"]], "ResourceBase"]
-Validator: TypeAlias = Callable[[ComponentConfig], Sequence[str]]
+Validator: TypeAlias = Callable[[ComponentConfig], Tuple[Sequence[str], Sequence[str]]]
+
+
+@runtime_checkable
+class SupportsGetGeometries(Protocol):
+    """The SupportsGetGeometries protocol defines the requirements for a resource to call get_geometries."""
+
+    async def GetGeometries(self, request: GetGeometriesRequest, *, timeout: Optional[float] = None, **kwargs) -> GetGeometriesResponse: ...