viam-sdk 0.25.2__py3-none-linux_armv7l.whl → 0.62.0__py3-none-linux_armv7l.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.
@@ -82,44 +70,44 @@ class Registry:
     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/types.py

@@ -1,6 +1,6 @@
 import re
 import sys
-from typing import TYPE_CHECKING, Callable, ClassVar, Mapping, Optional, Protocol, Sequence, runtime_checkable
+from typing import TYPE_CHECKING, Callable, ClassVar, Mapping, Optional, Protocol, Sequence, Tuple, runtime_checkable
 
 if sys.version_info >= (3, 10):
     from typing import TypeAlias
@@ -20,7 +20,7 @@ RESOURCE_TYPE_COMPONENT = "component"
 RESOURCE_TYPE_SERVICE = "service"
 
 
-class Subtype:
+class API:
     """Represents a known component/service (resource) API"""
 
     namespace: str
@@ -41,45 +41,45 @@ class Subtype:
         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: object) -> bool:
-        if isinstance(other, Subtype):
+        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))
 
 
@@ -203,12 +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) -> GetGeometriesResponse:
-        ...
+    async def GetGeometries(self, request: GetGeometriesRequest, *, timeout: Optional[float] = None, **kwargs) -> GetGeometriesResponse: ...