viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/resource/registry.py

@@ -0,0 +1,199 @@
+from dataclasses import dataclass
+from threading import Lock
+from typing import TYPE_CHECKING, Callable, ClassVar, Dict, Generic, Mapping, Type, TypeVar
+
+from grpclib.client import Channel
+
+from viam.errors import DuplicateResourceError, ResourceNotFoundError, ValidationError
+
+from .base import ResourceBase
+
+if TYPE_CHECKING:
+    from .rpc_service_base import ResourceRPCServiceBase
+    from .types import API, Model, ResourceCreator, Validator
+
+Resource = TypeVar("Resource", bound=ResourceBase)
+
+
+@dataclass
+class ResourceCreatorRegistration:
+    """An object representing a resource creator to be registered.
+
+    If creating a custom Resource creator, you should register the creator by creating a ``ResourceCreatorRegistration`` object and
+    registering it to the ``Registry``.
+    """
+
+    creator: "ResourceCreator"
+    """A function that can create a resource given a mapping of dependencies (``ResourceName`` to ``ResourceBase``
+    """
+
+    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
+    """
+
+
+@dataclass
+class ResourceRegistration(Generic[Resource]):
+    """An object representing a resource to be registered.
+
+    This object is generic over the ``ResourceBase``, and it includes various functionality for the resource,
+    such as creating its RPC client or status.
+
+    If creating a custom Resource type, you should register the resource by creating a ``ResourceRegistration`` object and registering it
+    to the ``Registry``.
+    """
+
+    resource_type: Type[Resource]
+    """The type of the Resource to be registered
+    """
+
+    rpc_service: Type["ResourceRPCServiceBase"]
+    """The type of the RPC service of the resource. This must extend from ``RPCServiceBase``
+    """
+
+    create_rpc_client: Callable[[str, Channel], Resource]
+    """A function that will create the RPC client for this resource
+    """
+
+
+class Registry:
+    """The global registry of robotic parts.
+
+    **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 (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(...)``.
+    """
+
+    _APIS: ClassVar[Dict["API", ResourceRegistration]] = {}
+    _RESOURCES: ClassVar[Dict[str, ResourceCreatorRegistration]] = {}
+    _lock: ClassVar[Lock] = Lock()
+
+    @classmethod
+    def register_api(cls, registration: ResourceRegistration[Resource]):
+        """Register a API with the Registry
+
+        Args:
+            registration (ResourceRegistration): Object containing registration data for the API
+
+        Raises:
+            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.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._APIS[registration.resource_type.API] = registration
+            else:
+                raise ValidationError("Passed resource registration does not have correct parameters")
+
+    @classmethod
+    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:
+            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 API and Model pairing is already registered
+            ValidationError: Raised if registration does not have creator
+        """
+        key = f"{api}/{model}"
+        with cls._lock:
+            if key in cls._RESOURCES:
+                raise DuplicateResourceError(key)
+
+            if registration.creator:
+                cls._RESOURCES[key] = registration
+            else:
+                raise ValidationError("A creator function was not provided")
+
+    @classmethod
+    def lookup_api(cls, api: "API") -> ResourceRegistration:
+        """Lookup and retrieve a registered API by its name
+
+        Args:
+            api (str): The API of the resource
+
+        Raises:
+            ResourceNotFoundError: Raised if the API is not registered
+
+        Returns:
+            ResourceRegistration: The registration object of the resource
+        """
+        with cls._lock:
+            try:
+                return cls._APIS[api]
+            except KeyError:
+                raise ResourceNotFoundError(api.resource_type, api.resource_subtype)
+
+    @classmethod
+    def lookup_resource_creator(cls, api: "API", model: "Model") -> "ResourceCreator":
+        """Lookup and retrieve a registered resource creator by its API and model
+
+        Args:
+            api (API): The API of the resource
+            model (Model): The Model of the resource
+
+        Raises:
+            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"{api}/{model}"].creator
+            except KeyError:
+                raise ResourceNotFoundError(api.resource_type, api.resource_subtype)
+
+    @classmethod
+    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:
+            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"{api}/{model}"].validator
+        except AttributeError:
+            return lambda x: []
+        except KeyError:
+            raise ResourceNotFoundError(api.resource_type, api.resource_subtype)
+
+    @classmethod
+    def REGISTERED_APIS(cls) -> Mapping["API", ResourceRegistration]:
+        """The dictionary of all registered resources
+        - Key: API of the resource
+        - Value: The registration object for the resource
+
+        Returns:
+            Mapping[API, ResourceRegistration]: All registered resources
+        """
+        with cls._lock:
+            return cls._APIS.copy()
+
+    @classmethod
+    def REGISTERED_RESOURCE_CREATORS(cls) -> Mapping[str, "ResourceCreatorRegistration"]:
+        """The dictionary of all registered resources
+        - Key: API/model
+        - Value: The ResourceCreatorRegistration for the resource
+
+        Returns:
+            Mapping[str, ResourceCreatorRegistration]: All registered resources
+        """
+        with cls._lock:
+            return cls._RESOURCES.copy()

viam/resource/rpc_client_base.py

@@ -0,0 +1,65 @@
+from random import choice
+from string import ascii_lowercase
+from typing import Any, Dict, Protocol, runtime_checkable
+
+from grpclib.client import Channel
+
+from viam.rpc.types import RPCServiceStubBase
+
+
+@runtime_checkable
+class ResourceRPCClientBase(Protocol):
+    """
+    Base RPC client for a resource.
+    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
+
+
+class ReconfigurableResourceRPCClientBase(ResourceRPCClientBase):
+    """A base RPC client that can reset its channel.
+
+    Useful if connection is lost and then regained.
+    """
+
+    def reset_channel(self, channel: Channel):
+        """Called when the RPC channel was reset. Passes in the new channel.
+
+        Args:
+            channel (Channel): The new RPC Channel
+        """
+        self.channel = channel
+        if isinstance(self.client, RPCServiceStubBase):
+            self.client = self.client.__class__(channel)

viam/resource/rpc_service_base.py

@@ -0,0 +1,48 @@
+import abc
+from typing import TYPE_CHECKING, Generic, Type
+
+from viam.components.component_base import ComponentBase
+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]):
+    """
+    Base RPC service for a resource.
+    All resource RPC services must inherit from this class.
+    """
+
+    RESOURCE_TYPE = Type
+    manager: "ResourceManager"
+
+    def __init__(self, manager: "ResourceManager"):
+        self.manager = manager
+
+    def get_resource(self, name: str) -> ResourceType:
+        """
+        Return the resource with the given name if it exists in the registry.
+        If the resource does not exist in the registry,
+        this function will raise an error
+
+        Args:
+            name (str): Name of the resource
+
+        Raises:
+            GRPCError with the status code Status.NOT_FOUND
+
+        Returns:
+            ResourceType: The resource
+        """
+        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

@@ -0,0 +1,213 @@
+import re
+import sys
+from typing import TYPE_CHECKING, Callable, ClassVar, Mapping, Optional, Protocol, Sequence, runtime_checkable
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+from typing_extensions import Self
+
+from viam.proto.app.robot import ComponentConfig
+from viam.proto.common import GetGeometriesRequest, GetGeometriesResponse, ResourceName
+
+if TYPE_CHECKING:
+    from .base import ResourceBase
+
+RESOURCE_NAMESPACE_RDK = "rdk"
+RESOURCE_TYPE_COMPONENT = "component"
+RESOURCE_TYPE_SERVICE = "service"
+
+
+class API:
+    """Represents a known component/service (resource) API"""
+
+    namespace: str
+    """The namespace of the resource"""
+
+    resource_type: str
+    """The type of the resource, for example `component` or `service`"""
+
+    resource_subtype: str
+    """The subtype of the resource for example `servo`, `arm`, `vision`"""
+
+    def __init__(self, namespace: str, resource_type: str, resource_subtype: str):
+        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.API {str(self)} at {hex(id(self))}>"
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+    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 ```API```
+
+        Args:
+            resource_name (viam.proto.common.ResourceName): The ResourceName to convert
+
+        Returns:
+            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 ```API``` from its string representation (namespace:resource_type:resource_subtype)
+
+        Args:
+            string (str): The API as a string
+
+        Raises:
+            ValueError: Raised if the string does not represent a valid API
+
+        Returns:
+            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 API")
+        return cls(match.group(1), match.group(2), match.group(3))
+
+
+class ModelFamily:
+    """Represents a family of related models"""
+
+    namespace: str
+    """The namespace of the model family"""
+
+    family: str
+    """The family name"""
+
+    DEFAULT_FAMILY_NAME: ClassVar[str] = "builtin"
+
+    DEFAULT: ClassVar["ModelFamily"]
+
+    def __init__(self, namespace: str, family: str):
+        self.namespace = namespace
+        self.family = family
+
+    def __str__(self) -> str:
+        return f"{self.namespace}:{self.family}"
+
+    def __repr__(self) -> str:
+        return f"<viam.resource.types.ModelFamily {str(self)} at {hex(id(self))}>"
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+    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)
+
+
+class Model:
+    """Represents a specific model within a family of models"""
+
+    model_family: ModelFamily
+    """The family to which this model belongs"""
+
+    name: str
+    """The name of the model"""
+
+    def __init__(self, model_family: ModelFamily, name: str):
+        self.model_family = model_family
+        self.name = name
+
+    def __str__(self) -> str:
+        return f"{self.model_family}:{self.name}"
+
+    def __repr__(self) -> str:
+        return f"<viam.resource.types.Model {str(self)} at {hex(id(self))}>"
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+    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:
+        """Create a ```Model``` from its string representation (namespace:family:name).
+
+        Args:
+            model (str): The Model as a string
+            ignore_errors (bool, optional): If namespace or family are not found in the string, default to empty string
+                                            rather than raise an exception. Defaults to False.
+
+        Raises:
+            ValueError: Raised if the provided string is not a valid Model
+
+        Returns:
+            Self: The Model
+        """
+        regex = re.compile(r"^([\w-]+):([\w-]+):([\w-]+)$")
+        match = regex.match(model)
+        if match:
+            namespace = match.group(1)
+            family = match.group(2)
+            name = match.group(3)
+            model_family = ModelFamily(namespace, family)
+        elif ignore_errors:
+            model_family = ModelFamily("", "")
+            name = model
+        else:
+            raise ValueError(f"{model} is not a valid Model")
+
+        return cls(model_family, name)
+
+
+def resource_name_from_string(string: str) -> ResourceName:
+    """Create a ResourceName from its string representation (namespace:resource_type:resource_subtype/<optional_remote:>name)
+
+    Args:
+        string (str): The ResourceName as a string
+
+    Raises:
+        ValueError: Raised if the provided string is not a valid ResourceName
+
+    Returns:
+        viam.proto.common.ResourceName: The new ResourceName
+    """
+    regex = re.compile(r"^([\w-]+:[\w-]+:(?:[\w-]+))\/?([\w-]+:(?:[\w-]+:)*)?(.+)?$")
+    match = regex.match(string)
+    if not match:
+        raise ValueError(f"{string} is not a valid ResourceName")
+    parts = match[1].split(":")
+    if len(parts) != 3:
+        raise ValueError(f"{string} is not a valid ResourceName")
+    if match[2]:
+        name = f"{match[2]}{match[3]}"
+    else:
+        name = match[3]
+    return ResourceName(namespace=parts[0], type=parts[1], subtype=parts[2], name=name)
+
+
+ResourceCreator: TypeAlias = Callable[[ComponentConfig, Mapping[ResourceName, "ResourceBase"]], "ResourceBase"]
+Validator: TypeAlias = Callable[[ComponentConfig], 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: ...