.. currentmodule:: event_collector

Data Structures
===============

**Source code:** `event_collector.data.py`

.. py:module:: event_collector.data

   This module contains definitions for basic data structures used in ``event_collector``.


Type Aliases
------------

The following are type aliases used in the ``event_collector`` codebase for
common data structures.

.. autotype:: event_collector.data.Record


Payload
-------

.. autoclass:: event_collector.data.Payload
   :members: set_delivery, set_priority
   :member-order: bysource

   .. autoattribute:: value

      ``value`` is the payload's initialized value. The type is ``Any`` and depends
      on what the caller passes as a parameter.

   .. autoattribute:: delivery

      ``delivery`` is the ``Delivery`` mode (``Delivery.BROADCAST``,
      ``Delivery.KEY``, or ``Delivery.TOPIC``).  Default is
      ``Delivery.BROADCAST``.

   .. autoattribute:: keys

      If ``delivery`` mode is ``Delivery.KEY``, ``keys`` should be a list of
      collector keys that the event payload should be routed to.

   .. autoattribute:: topics

      If ``delivery`` mode is ``Delivery.TOPIC``, ``topics`` should be a list of
      topics that the event payload should be routed to.

   .. autoattribute:: priority

      The priority level of the event if using a priority queue.


.. autoclass:: event_collector.data.Delivery

   This is an enum class used for specifying the delivery mode of a Payload.

   .. autoattribute:: BROADCAST

   .. autoattribute:: KEY

   .. autoattribute:: TOPIC


Context
-------

.. autoclass:: event_collector.data.Context(data: dict[str, Any] | None)
   :member-order: bysource

   The ``Context`` class implements an object that can store other
   objects or application-specific data. Stored values in the
   ``Context`` object are accessed like any attribute of an object:

   Example:

    .. code-block:: python
    
        ctx = Context()
        ctx.database_dsn = "postgresql://postgres:postgres@localhost:5432/mydb"
        ctx.repository = MyDBRepository(ctx.database_dsn)

   The ``Collector`` class automatically creates a ``Context`` object
   at initialization.

   Example usage:

   .. code-block:: python

       key = "demo-collector"
       ctx = Context()
       ctx.config_value = os.getenv("CONFIG_VALUE")

       collector = Collector(
           key,
           event_handler,
           lifecycle=lifecycle,
           ctx=ctx,
       )
     

Result
------

.. autotype:: Result

   A ``Result`` is either an ``Ok`` object or an ``Error``
   object. It's used to wrap a value or an error (depending on the
   output of a function). Using the ``Result`` object allows
   ``event_collector``'s asynchronous tasks to pass valid values or
   errors/exceptions up the function call stack in a clean, unified
   way without having to deal with complex exception and error
   handling semantics.

.. autoclass:: Ok(value)
   :members: error, ok, unwrap
   :member-order: bysource

   This is a class that defines a wrapper for an *OK*, successful result.


.. autoclass:: event_collector.data.Error
   :members: error, ok, unwrap
   :member-order: bysource

   This is a class that defines a wrapper for an *Error* result.



Result Example Usage
--------------------

``Ok`` indicates success and ``Error`` indicates failure or an
exception. The ``Ok`` and ``Error`` objects wrap a value. In the case
of ``Ok`` the value is the payload being returned. If the case of an
``Error``, the wrapped value should be an error message or an
``Exception``.

Example:

.. code-block:: python

    async def func(payload: Payload, ctx: Context) -> Result:
        """
        Return an Ok result if processing is successful. The
        Ok object will wrap the "payload" as a return value.
        """
        value = {
            "status": "successful",
        }
        return Ok(value)

    or:

    async def func(payload: Payload, ctx: Context) -> Result:
        """
        Return an Error result if processing encounters an error.
        The Error object will wrap an error message and the error
        will unwrap as a RuntimeError.
        """
        ...

        return Ok("event payload is missing required field")

        # or

        return Error(ValueError)


Example results::

    >>> from event_collector.data import Ok, Error, Result

    >>> result = Ok({"status": "successful"})
    >>> result.unwrap()
    {'status': 'successful'}

    >>> result = Error("payload is missing required field")
    >>> result.unwrap()
    Traceback (most recent call last):
      File "<python-input-4>", line 1, in <module>
        result.unwrap()
        ~~~~~~~~~~~~~--
      File ".../event-collector/src/event_collector/data.py", line 55, in unwrap
        raise RuntimeError(self.err)
    RuntimeError: payload is missing required field


ResultList
----------

.. autoclass:: ResultList
   :members: results, first, iter, size
   :member-order: bysource