viam-sdk 0.25.2__py3-none-linux_armv7l.whl → 0.62.0__py3-none-linux_armv7l.whl

viam/module/module.py

@@ -1,16 +1,20 @@
 import argparse
 import io
 import logging as pylogging
+import os
 import sys
+from collections.abc import Iterable
 from inspect import iscoroutinefunction
 from threading import Lock
 from typing import List, Mapping, Optional, Sequence, Tuple
 
+from grpclib.metadata import Deadline
 from grpclib.utils import _service_name
 from typing_extensions import Self
 
 from viam import logging
 from viam.errors import ResourceNotFoundError, ValidationError
+from viam.logging import update_log_level
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.module import (
     AddResourceRequest,
@@ -26,15 +30,40 @@ from viam.proto.module import (
 from viam.proto.robot import ResourceRPCSubtype
 from viam.resource.base import ResourceBase
 from viam.resource.registry import Registry
-from viam.resource.types import RESOURCE_TYPE_COMPONENT, RESOURCE_TYPE_SERVICE, Model, ResourceName, Subtype, resource_name_from_string
+from viam.resource.types import API, RESOURCE_TYPE_COMPONENT, RESOURCE_TYPE_SERVICE, Model, ResourceName, resource_name_from_string
 from viam.robot.client import RobotClient
-from viam.rpc.dial import DialOptions
+from viam.rpc.dial import DialOptions, _host_port_from_url
 from viam.rpc.server import Server
 
+# These imports are required to register built-in resources with the registry
+from ..components.arm import Arm  # noqa: F401
+from ..components.audio_input import AudioInput  # noqa: F401
+from ..components.base import Base  # noqa: F401
+from ..components.board import Board  # noqa: F401
+from ..components.button import Button  # noqa: F401
+from ..components.camera import Camera  # noqa: F401
+from ..components.encoder import Encoder  # noqa: F401
+from ..components.gantry import Gantry  # noqa: F401
+from ..components.generic import Generic as GenericComponent  # noqa: F401
+from ..components.gripper import Gripper  # noqa: F401
+from ..components.input import Controller  # noqa: F401
+from ..components.motor import Motor  # noqa: F401
+from ..components.movement_sensor import MovementSensor  # noqa: F401
+from ..components.pose_tracker import PoseTracker  # noqa: F401
+from ..components.power_sensor import PowerSensor  # noqa: F401
+from ..components.sensor import Sensor  # noqa: F401
+from ..components.servo import Servo  # noqa: F401
+from ..components.switch import Switch  # noqa: F401
+from ..services.discovery import Discovery  # noqa: F401
+from ..services.generic import Generic as GenericService  # noqa: F401
+from ..services.motion import Motion  # noqa: F401
+from ..services.navigation import Navigation  # noqa: F401
+from ..services.slam import SLAM  # noqa: F401
+from ..services.vision import Vision  # noqa: F401
 from .service import ModuleRPCService
 from .types import Reconfigurable, Stoppable
 
-LOGGER = logging.getLogger(__name__)
+NO_MODULE_PARENT = os.environ.get("VIAM_NO_MODULE_PARENT", "").lower() == "true"
 
 
 def _parse_module_args() -> argparse.Namespace:
@@ -44,7 +73,8 @@ def _parse_module_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(description="Start this viam python module")
     p.add_argument("socket_path", help="path where this module will serve a unix socket")
     p.add_argument("--log-level", type=lambda name: pylogging._nameToLevel[name.upper()], default=logging.INFO)
-    return p.parse_args()
+    p.add_argument("--tcp-mode", action="store_true")
+    return p.parse_known_args()[0]
 
 
 class Module:
@@ -53,8 +83,10 @@ class Module:
     _ready: bool
     _log_level: int
     _lock: Lock
+    _tcp_mode: bool
     parent: Optional[RobotClient] = None
     server: Server
+    logger: pylogging.Logger
 
     @classmethod
     def from_args(cls) -> Self:
@@ -70,7 +102,7 @@ class Module:
             Module: a new Module instance
         """
         args = _parse_module_args()
-        return cls(args.socket_path, log_level=args.log_level)
+        return cls(args.socket_path, log_level=args.log_level, tcp_mode=args.tcp_mode)
 
     @classmethod
     async def run_with_models(cls, *models: ResourceBase):
@@ -82,7 +114,7 @@ class Module:
         for model in models:
             if not hasattr(model, "MODEL"):
                 raise TypeError(f"missing MODEL field on {model}. Resource implementations must define MODEL")
-            module.add_model_from_registry(model.SUBTYPE, model.MODEL)  # pyright: ignore [reportAttributeAccessIssue]
+            module.add_model_from_registry(model.API, model.MODEL)  # pyright: ignore [reportAttributeAccessIssue]
         await module.start()
 
     @classmethod
@@ -102,7 +134,7 @@ class Module:
             module.add_model_from_registry(*key.split("/"))  # pyright: ignore [reportArgumentType]
         await module.start()
 
-    def __init__(self, address: str, *, log_level: int = logging.INFO) -> None:
+    def __init__(self, address: str, *, log_level: int = logging.INFO, tcp_mode: bool = False) -> None:
         # When a module is launched by viam-server, its stdout is not connected to a tty.  In
         # response, python disables line buffering, which prevents `print` statements from being
         # immediately flushed to viam-server. This behavior can be confusing, interfere with
@@ -113,12 +145,21 @@ class Module:
         if isinstance(sys.stderr, io.TextIOWrapper):
             sys.stderr.reconfigure(line_buffering=True)
         self._address = address
+        self._tcp_mode = tcp_mode
         self.server = Server(resources=[], module_service=ModuleRPCService(self))
         self._log_level = log_level
+
+        module_name = os.environ.get("VIAM_MODULE_NAME")
+        # this can happen if the user is running an old version of viam-server that doesn't set `VIAM_MODULE_NAME`
+        if module_name is None:
+            module_name = __name__
+        self.logger = logging.getLogger(module_name)
         self._ready = True
         self._lock = Lock()
 
     async def _connect_to_parent(self):
+        if NO_MODULE_PARENT:
+            return
         if self.parent is None:
             if self._parent_address is None:
                 raise ValueError("Parent address not found")
@@ -129,7 +170,7 @@ class Module:
                     log_level=self._log_level,
                 ),
             )
-            LOGGER.debug("Starting module logging")
+            self.logger.debug("Starting module logging")
             logging.setParent(self.parent)
 
     async def _get_resource(self, name: ResourceName) -> ResourceBase:
@@ -152,18 +193,23 @@ class Module:
     async def start(self):
         """Start the module service and gRPC server"""
         try:
-            await self.server.serve(log_level=self._log_level, path=self._address)
+            if self._tcp_mode:
+                host, port = _host_port_from_url(self._address)
+                await self.server.serve(log_level=self._log_level, host=host, port=port)
+            else:
+                await self.server.serve(log_level=self._log_level, path=self._address)
         finally:
             await self.stop()
 
     async def stop(self):
         """Stop the module service and gRPC server"""
-        LOGGER.debug("Shutting down module")
+        self.logger.debug("Shutting down module")
         try:
+            logging.shutdown()
             if self.parent is not None:
                 await self.parent.close()
         except Exception as e:
-            LOGGER.error("Encountered error while shutting down module", exc_info=e)
+            self.logger.error("Encountered error while shutting down module", exc_info=e)
 
     def set_ready(self, ready: bool):
         """Set the module's ready state. The module automatically sets to READY on load. Setting to False can be useful
@@ -175,21 +221,24 @@ class Module:
         with self._lock:
             self._ready = ready
 
-    async def add_resource(self, request: AddResourceRequest):
+    async def add_resource(self, request: AddResourceRequest, *, deadline: Optional[Deadline] = None):
         dependencies = await self._get_dependencies(request.dependencies)
         config: ComponentConfig = request.config
-        subtype = Subtype.from_string(config.api)
+        api = API.from_string(config.api)
         model = Model.from_string(config.model, ignore_errors=True)
-        creator = Registry.lookup_resource_creator(subtype, model)
+        creator = Registry.lookup_resource_creator(api, model)
         resource = creator(config, dependencies)
+        if deadline is not None and deadline.time_remaining() <= 0:
+            raise TimeoutError("Deadline expired")
+        update_log_level(resource.logger, config.log_configuration.level.upper())
         self.server.register(resource)
 
     async def reconfigure_resource(self, request: ReconfigureResourceRequest):
         dependencies = await self._get_dependencies(request.dependencies)
         config: ComponentConfig = request.config
-        subtype = Subtype.from_string(config.api)
+        api = API.from_string(config.api)
         name = config.name
-        rn = ResourceName(namespace=subtype.namespace, type=subtype.resource_type, subtype=subtype.resource_subtype, name=name)
+        rn = ResourceName(namespace=api.namespace, type=api.resource_type, subtype=api.resource_subtype, name=name)
         resource = self.server.get_resource(ResourceBase, rn)
         if isinstance(resource, Reconfigurable):
             resource.reconfigure(config, dependencies)
@@ -207,38 +256,41 @@ class Module:
         rn = resource_name_from_string(request.name)
         resource = self.server.get_resource(ResourceBase, rn)
         if isinstance(resource, Stoppable):
-            if iscoroutinefunction(resource.stop):
-                await resource.stop()
-            else:
-                resource.stop()
+            try:
+                if iscoroutinefunction(resource.stop):
+                    await resource.stop()
+                else:
+                    resource.stop()
+            except Exception as e:
+                self.logger.warning(f"Could not remove resource named {resource.name}", exc_info=e)
         await self.server.remove_resource(rn)
 
     async def ready(self, request: ReadyRequest) -> ReadyResponse:
         self._parent_address = request.parent_address
         await self._connect_to_parent()
 
-        svcname_to_models: Mapping[Tuple[str, Subtype], List[Model]] = {}
-        for subtype_model_str in Registry.REGISTERED_RESOURCE_CREATORS().keys():
-            subtype_str, model_str = subtype_model_str.split("/")
-            subtype = Subtype.from_string(subtype_str)
+        svcname_to_models: Mapping[Tuple[str, API], List[Model]] = {}
+        for api_model_str in Registry.REGISTERED_RESOURCE_CREATORS().keys():
+            api_str, model_str = api_model_str.split("/")
+            api = API.from_string(api_str)
             model = Model.from_string(model_str)
 
-            registration = Registry.lookup_subtype(subtype)
+            registration = Registry.lookup_api(api)
             service = registration.rpc_service(self.server)
             service_name = _service_name(service)
 
-            models = svcname_to_models.get((service_name, subtype), [])
+            models = svcname_to_models.get((service_name, api), [])
             models.append(model)
-            svcname_to_models[(service_name, subtype)] = models
+            svcname_to_models[(service_name, api)] = models
 
         handlers: List[HandlerDefinition] = []
         for key, value in svcname_to_models.items():
-            svc_name, subtype = key
+            svc_name, api = key
             rpc_subtype = ResourceRPCSubtype(
                 subtype=ResourceName(
-                    namespace=subtype.namespace,
-                    type=subtype.resource_type,
-                    subtype=subtype.resource_subtype,
+                    namespace=api.namespace,
+                    type=api.resource_type,
+                    subtype=api.resource_subtype,
                     name="",
                 ),
                 proto_service=svc_name,
@@ -248,22 +300,43 @@ class Module:
 
         return ReadyResponse(ready=self._ready, handlermap=HandlerMap(handlers=handlers))
 
-    def add_model_from_registry(self, subtype: Subtype, model: Model):
+    def add_model_from_registry(self, api: API, model: Model):
         """Add a pre-registered model to this Module"""
 
         # All we need to do is double check that the model has already been registered
         try:
-            Registry.lookup_resource_creator(subtype, model)
+            Registry.lookup_resource_creator(api, model)
         except ResourceNotFoundError:
-            raise ValueError(f"Cannot add model because it has not been registered. Subtype: {subtype}. Model: {model}")
+            raise ValueError(f"Cannot add model because it has not been registered. API: {api}. Model: {model}")
 
     async def validate_config(self, request: ValidateConfigRequest) -> ValidateConfigResponse:
         config: ComponentConfig = request.config
-        subtype = Subtype.from_string(config.api)
+        api = API.from_string(config.api)
         model = Model.from_string(config.model)
-        validator = Registry.lookup_validator(subtype, model)
+        validator = Registry.lookup_validator(api, model)
         try:
-            dependencies = validator(config)
-            return ValidateConfigResponse(dependencies=dependencies)
+            # backwards compatibility. Support both ([], []) or [] with deprecation warning.
+            # If user's validate returns [str], it will be treated as required dependencies only.
+            # Incorect formats, e.g. int, will raise ValidationError.
+            _validator_return_test = validator(config)
+            if not (isinstance(_validator_return_test, tuple) and len(_validator_return_test) == 2):
+                msg = f"Your validate function {validator.__name__} did not return \
+                        type tuple[Sequence[str], Sequence[str]]. Got {_validator_return_test}."
+                self.logger.warning(msg)
+                if (isinstance(_validator_return_test, Iterable) and not isinstance(_validator_return_test, str)) and all(
+                    isinstance(e, str)
+                    for e in _validator_return_test  # type: ignore
+                ):
+                    self.logger.warning(
+                        f"Detected deprecated validate function signature. \
+                                        Treating all dependencies {_validator_return_test} as required dependencies. \
+                                        Please update to new signature Tuple[Sequence[str], Sequence[str]] soon."
+                    )
+                    return ValidateConfigResponse(dependencies=_validator_return_test)
+                else:
+                    raise ValidationError(msg)
+
+            dependencies, optional_dependencies = _validator_return_test
+            return ValidateConfigResponse(dependencies=dependencies, optional_dependencies=optional_dependencies)
         except Exception as e:
             raise ValidationError(f"{type(Exception)}: {e}").grpc_error

viam/module/resource_data_consumer.py

@@ -0,0 +1,41 @@
+import datetime
+import os
+from typing import Any, Dict, List, Optional
+
+from viam.app.viam_client import ViamClient
+
+
+class ResourceDataConsumer:
+    """Client for retrieving historical module data from app.
+
+    Inherit from this class in a module to get access to historical module data.
+    """
+
+    @classmethod
+    def construct_query(cls, part_id: str, resource_name: str, time_back: datetime.timedelta) -> List[Dict[str, Any]]:
+        return [
+            {
+                "$match": {
+                    "part_id": part_id,
+                    "component_name": resource_name,
+                    "time_received": {"$gte": datetime.datetime.now() - time_back},
+                }
+            }
+        ]
+
+    @classmethod
+    async def query_tabular_data(
+        cls, resource_name: str, time_back: datetime.timedelta, additional_stages: Optional[List[Dict[str, Any]]] = None, **kwargs
+    ) -> List[Dict[str, Any]]:
+        """Return historical data for this module, queried with MQL."""
+        viam_client = await ViamClient.create_from_env_vars()
+
+        org_id = os.environ["VIAM_PRIMARY_ORG_ID"]
+        part_id = os.environ["VIAM_MACHINE_PART_ID"]
+
+        query = cls.construct_query(part_id=part_id, resource_name=resource_name, time_back=time_back)
+
+        if additional_stages is not None:
+            query += additional_stages
+
+        return await viam_client.data_client.tabular_data_by_mql(org_id, query)

viam/module/service.py

@@ -1,7 +1,9 @@
 from typing import TYPE_CHECKING
 
+from grpclib import Status
 from grpclib.server import Stream
 
+from viam.errors import ViamGRPCError
 from viam.proto.module import (
     AddResourceRequest,
     AddResourceResponse,
@@ -29,7 +31,13 @@ class ModuleRPCService(ModuleServiceBase):
     async def AddResource(self, stream: Stream[AddResourceRequest, AddResourceResponse]) -> None:
         request = await stream.recv_message()
         assert request is not None
-        await self._module.add_resource(request)
+        try:
+            await self._module.add_resource(request, deadline=stream.deadline)
+        except TimeoutError:
+            raise ViamGRPCError(
+                message="Timeout while adding resource",
+                grpc_code=Status.DEADLINE_EXCEEDED,
+            )
         await stream.send_message(AddResourceResponse())
 
     async def ReconfigureResource(self, stream: Stream[ReconfigureResourceRequest, ReconfigureResourceResponse]) -> None:

viam/module/types.py

@@ -9,8 +9,7 @@ from viam.resource.base import ResourceBase
 class Reconfigurable(Protocol):
     """The Reconfigurable protocol defines the requirements for making a resource Reconfigurable"""
 
-    def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]):
-        ...
+    def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]): ...
 
 
 @runtime_checkable
@@ -21,5 +20,4 @@ class Stoppable(Protocol):
     All resources that physically move should be Stoppable.
     """
 
-    def stop(self, *, extra: Optional[Mapping[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
-        ...
+    def stop(self, *, extra: Optional[Mapping[str, Any]] = None, timeout: Optional[float] = None, **kwargs): ...