:py:mod:`viam.operations`
=========================

.. py:module:: viam.operations


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

Classes
~~~~~~~

.. autoapisummary::

   viam.operations.Operation



Functions
~~~~~~~~~

.. autoapisummary::

   viam.operations.opid_from_metadata
   viam.operations.run_with_operation



Attributes
~~~~~~~~~~

.. autoapisummary::

   viam.operations.P
   viam.operations.T
   viam.operations.METADATA_KEY


.. py:class:: Operation(method: str, cancel_event: asyncio.Event, opid: Optional[uuid.UUID] = None)


   An Operation represents a running operation.

   Every request made to a robot's components will create a new Operation on the server. For custom components built with this python-sdk,
   you should check whether the operation has been cancelled to prevent long-running tasks from leaking.

   .. py:attribute:: ARG_NAME
      :value: 'viam_operation'

      

   .. py:attribute:: id
      :type: uuid.UUID

      

   .. py:attribute:: method
      :type: str

      

   .. py:attribute:: time_started
      :type: float

      

   .. py:method:: is_cancelled() -> bool
      :async:


   .. py:method:: __str__() -> str

      Return str(self).



.. py:data:: P

   

.. py:data:: T

   

.. py:data:: METADATA_KEY
   :value: 'opid'

   

.. py:function:: opid_from_metadata(metadata: Optional[Mapping[str, str]]) -> Optional[uuid.UUID]


.. py:function:: run_with_operation(func: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, Coroutine[Any, Any, T]]

   Run a component function with an ``Operation``.
   Running a function with an Operation will allow the function
   to know if/when the calling task was cancelled and take appropriate action
   (.e.g. stop long running tasks and exit early).

   If a timeout is provided to the function, the operation will cancel when the timeout is reached.

   An example use case is if a gRPC client disconnects after making a request.
   Rather than continue to run a task for a receiver that is no longer there,
   the component can cancel and clean up, saving resources.

   :param func: The function to be called with an Operation.
                This function MUST accept ``**kwargs``
                or a parameter whose name is equal the value of ``Operation.ARG_NAME``
   :type func: Callable[..., Coroutine[Any, Any, T]]

   :returns: The return of the function
   :rtype: T