viam.resource.registry
======================

.. py:module:: viam.resource.registry


Attributes
----------

.. autoapisummary::

   viam.resource.registry.Resource


Classes
-------

.. autoapisummary::

   viam.resource.registry.ResourceCreatorRegistration
   viam.resource.registry.ResourceRegistration
   viam.resource.registry.Registry


Module Contents
---------------

.. py:data:: Resource

.. py: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``.


   .. py:attribute:: creator
      :type:  viam.resource.types.ResourceCreator

      A function that can create a resource given a mapping of dependencies (``ResourceName`` to ``ResourceBase``


   .. py:attribute:: validator
      :type:  viam.resource.types.Validator

      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


.. py:class:: ResourceRegistration

   Bases: :py:obj:`Generic`\ [\ :py:obj:`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``.


   .. py:attribute:: resource_type
      :type:  Type[Resource]

      The type of the Resource to be registered


   .. py:attribute:: rpc_service
      :type:  Type[viam.resource.rpc_service_base.ResourceRPCServiceBase]

      The type of the RPC service of the resource. This must extend from ``RPCServiceBase``


   .. py:attribute:: create_rpc_client
      :type:  Callable[[str, grpclib.client.Channel], Resource]

      A function that will create the RPC client for this resource


.. py: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(...)``.


   .. py:method:: register_api(registration: ResourceRegistration[Resource])
      :classmethod:


      Register a API with the Registry

      :param registration: Object containing registration data for the API
      :type registration: ResourceRegistration

      :raises DuplicateResourceError: Raised if the API to register is already in the registry
      :raises ValidationError: Raised if registration is missing any necessary parameters



   .. py:method:: register_resource_creator(api: viam.resource.types.API, model: viam.resource.types.Model, registration: ResourceCreatorRegistration)
      :classmethod:


      Register a specific ``Model`` and validator function for the specific resource ``API`` with the Registry

      :param api: The API of the resource
      :type api: API
      :param model: The Model of the resource
      :type model: Model
      :param registration: The registration functions of the model
      :type registration: ResourceCreatorRegistration

      :raises DuplicateResourceError: Raised if the API and Model pairing is already registered
      :raises ValidationError: Raised if registration does not have creator



   .. py:method:: lookup_api(api: viam.resource.types.API) -> ResourceRegistration
      :classmethod:


      Lookup and retrieve a registered API by its name

      :param api: The API of the resource
      :type api: str

      :raises ResourceNotFoundError: Raised if the API is not registered

      :returns: The registration object of the resource
      :rtype: ResourceRegistration



   .. py:method:: lookup_resource_creator(api: viam.resource.types.API, model: viam.resource.types.Model) -> viam.resource.types.ResourceCreator
      :classmethod:


      Lookup and retrieve a registered resource creator by its API and model

      :param api: The API of the resource
      :type api: API
      :param model: The Model of the resource
      :type model: Model

      :raises ResourceNotFoundError: Raised if the API Model pairing is not registered

      :returns: The function to create the resource
      :rtype: ResourceCreator



   .. py:method:: lookup_validator(api: viam.resource.types.API, model: viam.resource.types.Model) -> viam.resource.types.Validator
      :classmethod:


      Lookup and retrieve a registered validator function by its API and model. If there is none, return None

      :param api: The API of the resource
      :type api: API
      :param model: The Model of the resource
      :type model: Model

      :returns: The function to validate the resource
      :rtype: Validator



   .. py:method:: REGISTERED_APIS() -> Mapping[viam.resource.types.API, ResourceRegistration]
      :classmethod:


      The dictionary of all registered resources
      - Key: API of the resource
      - Value: The registration object for the resource

      :returns: All registered resources
      :rtype: Mapping[API, ResourceRegistration]



   .. py:method:: REGISTERED_RESOURCE_CREATORS() -> Mapping[str, ResourceCreatorRegistration]
      :classmethod:


      The dictionary of all registered resources
      - Key: API/model
      - Value: The ResourceCreatorRegistration for the resource

      :returns: All registered resources
      :rtype: Mapping[str, ResourceCreatorRegistration]