Merge pull request #4 from Zsailer/refactor-api

Add new EventSchema and SchemaRegistry API

.github/workflows/check-release.yml

@@ -24,6 +24,3 @@ jobs:
         uses: jupyter-server/jupyter_releaser/.github/actions/check-release@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Run Link Check
-        if: ${{ matrix.group == 'link_check' }}
-        uses: jupyter-server/jupyter_releaser/.github/actions/check-links@v1

.github/workflows/python-tests.yml

@@ -30,6 +30,7 @@ jobs:
       - name: Install the Python dependencies
         run: |
           pip install -e ".[test]" codecov
+          pip list
       - name: Run the tests
         if: ${{ !startsWith(matrix.python-version, 'pypy') && !startsWith(matrix.os, 'windows') }}
         run: |

.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
     hooks:
       - id: mypy
         exclude: examples/simple/setup.py
-        additional_dependencies: [types-requests]
+        additional_dependencies: [types-requests, types-PyYAML]
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.6.2

CHANGELOG.md

@@ -4,6 +4,6 @@ All notable changes to this project will be documented in this file.
 
 <!-- <START NEW CHANGELOG ENTRY> -->
 
-## 0.0.0
+## 0.1.0
 
 <!-- <END NEW CHANGELOG ENTRY> -->

README.md

@@ -2,87 +2,18 @@
 
 _An event system for Jupyter Applications and extensions._
 
-Jupyter Events enables Jupyter Applications (e.g. Jupyter Server, Jupyter Notebook, JupyterLab, JupyterHub, etc.) to emit **events**—i.e. actions by application users—to remote (or local) destinations as **structured** data. It works with Python's standard `logging` library to handle the transmission of events allowing users to send events to local files, over the web, etc.
+Jupyter Events enables Jupyter Python Applications (e.g. Jupyter Server, JupyterLab Server, JupyterHub, etc.) to emit **events**—structured data describing things happening inside the application. Other software (e.g. client applications like JupyterLab) can _listen_ and respond to these events.
 
 ## Install
 
-The Jupyter Events library can be installed from PyPI.
+Install Jupyter Events directly from PyPI:
 
 ```
 pip install jupyter_events
 ```
 
-## Basic Usage
+or conda-forge:
 
-Jupyter Events provides a configurable traitlets object, `EventLogger`, for emitting structured event data in Python. It leverages Python's standard `logging` library for filtering, routing, and emitting events. All events are validated (using [jsonschema](https://pypi.org/project/jsonschema/)) against registered [JSON schemas](https://json-schema.org/).
-
-Let's look at a basic example of an `EventLogger`.
-
-```python
-import logging
-from jupyter_events import EventLogger
-
-
-logger = EventLogger(
-    # Use logging handlers to route where events
-    # should be record.
-    handlers=[
-        logging.FileHandler('events.log')
-    ],
-    # List schemas of events that should be recorded.
-    allowed_schemas=[
-        'uri.to.event.schema'
-    ]
-)
-```
-
-EventLogger has two configurable traits:
-
-- `handlers`: a list of Python's `logging` handlers.
-- `allowed_schemas`: a list of event schemas to record.
-
-Event schemas must be registered with the `EventLogger` for events to be recorded. An event schema looks something like:
-
-```json
-{
-  "$id": "url.to.event.schema",
-  "title": "My Event",
-  "description": "All events must have a name property.",
-  "type": "object",
-  "properties": {
-    "name": {
-      "title": "Name",
-      "description": "Name of event",
-      "type": "string"
-    }
-  },
-  "required": ["name"],
-  "version": 1
-}
 ```
-
-2 fields are required:
-
-- `$id`: a valid URI to identify the schema (and possibly fetch it from a remote address).
-- `version`: the version of the schema.
-
-The other fields follow standard JSON schema structure.
-
-Schemas can be registered from a Python `dict` object, a file, or a URL. This example loads the above example schema from file.
-
-```python
-# Register the schema.
-logger.register_schema_file('schema.json')
-```
-
-Events are recorded using the `record_event` method. This method validates the event data and routes the JSON string to the Python `logging` handlers listed in the `EventLogger`.
-
-```python
-# Record an example event.
-event = {'name': 'example event'}
-logger.record_event(
-    schema_id='url.to.event.schema',
-    version=1,
-    event=event
-)
+conda install -c conda-forge jupyter_events
 ```

docs/conf.py

@@ -29,11 +29,14 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions: List = []
+extensions: List = ["myst_parser", "jupyterlite_sphinx"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+source_suffix = [".rst", ".md"]
+
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -45,10 +48,39 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_logo = "_static/jupyter_logo.png"
+
 master_doc = "index"
+
+# Configure jupyterlite to import jupyter_events package
+jupyterlite_contents = ["demo/demo-notebook.ipynb"]
+
+html_theme_options = {
+    "logo": {
+        "text": "Jupyter Events",
+    },
+    "icon_links": [
+        {
+            # Label for this link
+            "name": "GitHub",
+            # URL where the link will redirect
+            "url": "https://github.com/jupyter/jupyter_events",  # required
+            # Icon class (if "type": "fontawesome"), or path to local image (if "type": "local")
+            "icon": "fab fa-github-square",
+            # The type of image to be used (see below for details)
+            "type": "fontawesome",
+        },
+        {
+            "name": "jupyter.org",
+            "url": "https://jupyter.org",
+            "icon": "_static/jupyter_logo.png",
+            "type": "local",
+        },
+    ],
+}

docs/demo/demo-notebook.ipynb

@@ -0,0 +1,32 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import piplite\n",
+    "\n",
+    "piplite.install(\"jupyter_events\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from jupyter_events.logger import EventLogger\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/demo/index.md

@@ -0,0 +1,10 @@
+# Try it out
+
+Try out the Jupyter Events Library in the example notebook below (powered by JupyterLite):
+
+```{retrolite} demo-notebook.ipynb
+---
+width: 100%
+height: 1200px
+---
+```

docs/index.md

@@ -0,0 +1,35 @@
+# Jupyter Events
+
+_An event system for Jupyter Applications and extensions._
+
+Jupyter Events enables Jupyter Python Applications (e.g. Jupyter Server, JupyterLab Server, JupyterHub, etc.) to emit **events**—structured data describing things happening inside the application. Other software (e.g. client applications like JupyterLab) can _listen_ and respond to these events.
+
+## Install
+
+Install Jupyter Events directly from PyPI:
+
+```
+pip install jupyter_events
+```
+
+or conda-forge:
+
+```
+conda install -c conda-forge jupyter_events
+```
+
+## Contents
+
+```{toctree}
+---
+maxdepth: 2
+---
+user_guide/index
+demo/index
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`