Add Listeners API

docs/demo/demo-notebook.ipynb

@@ -26,7 +26,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 26,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -44,7 +44,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 2,
    "metadata": {},
    "outputs": [
     {
@@ -94,7 +94,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -115,27 +115,27 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "{\"__timestamp__\": \"2022-08-11T05:06:20.339412Z\", \"__schema__\": \"myapplication.org/example-event\", \"__schema_version__\": 1, \"__metadata_version__\": 1, \"name\": \"My Event\"}\n"
+      "{\"__timestamp__\": \"2022-08-11T22:46:22.248281Z\", \"__schema__\": \"myapplication.org/example-event\", \"__schema_version__\": 1, \"__metadata_version__\": 1, \"name\": \"My Event\"}\n"
      ]
     },
     {
      "data": {
       "text/plain": [
-       "{'__timestamp__': '2022-08-11T05:06:20.339412Z',\n",
+       "{'__timestamp__': '2022-08-11T22:46:22.248281Z',\n",
        " '__schema__': 'myapplication.org/example-event',\n",
        " '__schema_version__': 1,\n",
        " '__metadata_version__': 1,\n",
        " 'name': 'My Event'}"
       ]
      },
-     "execution_count": 29,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -149,6 +149,80 @@
     ")\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, let's demo adding a listener to the already registered event."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def my_listener(data):\n",
+    "    print(\"hello, from my_listener!\")\n",
+    "    print(data)\n",
+    "\n",
+    "logger.add_listener(schema_id=\"myapplication.org/example-event\", version=1, listener=my_listener)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we emit the event again, you'll see our listener \"sees\" the event and executes some code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "{\"__timestamp__\": \"2022-08-11T22:46:28.947996Z\", \"__schema__\": \"myapplication.org/example-event\", \"__schema_version__\": 1, \"__metadata_version__\": 1, \"name\": \"My Event\"}\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "hello world\n",
+      "EventListenerData(event_logger=<jupyter_events.logger.EventLogger object at 0x7fd07085dfd0>, schema_id='myapplication.org/example-event', version=1, data={'name': 'My Event'})\n",
+      "hello world\n",
+      "EventListenerData(event_logger=<jupyter_events.logger.EventLogger object at 0x7fd07085dfd0>, schema_id='myapplication.org/example-event', version=1, data={'name': 'My Event'})\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "{'__timestamp__': '2022-08-11T22:46:28.947996Z',\n",
+       " '__schema__': 'myapplication.org/example-event',\n",
+       " '__schema_version__': 1,\n",
+       " '__metadata_version__': 1,\n",
+       " 'name': 'My Event'}"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "logger.emit(\n",
+    "    schema_id=\"myapplication.org/example-event\",\n",
+    "    version=1,\n",
+    "    data={\n",
+    "        \"name\": \"My Event\"\n",
+    "    }\n",
+    ")\n"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

docs/user_guide/index.md

@@ -10,4 +10,5 @@ defining-schema
 configure
 application
 modifiers
+listeners
 ```

docs/user_guide/listeners.md

@@ -0,0 +1,24 @@
+# Adding event listeners
+
+Event listeners are callback functions/methods that are executed when an event is emitted.
+
+Listeners can be used by extension authors to trigger custom logic every time an event occurs.
+
+## Basic usage
+
+Define a listener function:
+
+```python
+from jupyter_events.logger import EventLogger
+
+def my_listener(logger: EventLogger, schema_id: str, data: dict) -> None:
+    print("hello, from my listener")
+```
+
+Hook this listener to a specific event type:
+
+```python
+event_logger.add_listener("http://event.jupyter.org/my-event", listener=my_listener)
+```
+
+Now, every time a `"http://event.jupyter.org/test"` event is emitted from the EventLogger, this listener will be called.