Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add redactionPolicies field to Jupyter Event schemas #2

Merged
merged 22 commits into from
Aug 11, 2022
Merged
Show file tree
Hide file tree
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/python-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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> -->
77 changes: 4 additions & 73 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Binary file added docs/_static/jupyter_logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 34 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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",
},
],
}
32 changes: 32 additions & 0 deletions docs/demo/demo-notebook.ipynb
Original file line number Diff line number Diff line change
@@ -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
}
10 changes: 10 additions & 0 deletions docs/demo/index.md
Original file line number Diff line number Diff line change
@@ -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
---
```
35 changes: 35 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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`
51 changes: 0 additions & 51 deletions docs/index.rst

This file was deleted.

52 changes: 0 additions & 52 deletions docs/pages/application.rst

This file was deleted.

Loading