jupyterlab-pioneer 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# JupyterLab Pioneer
|
|
1
|
+
# JupyterLab Pioneer
|
|
2
2
|
|
|
3
3
|
[](https://pypi.org/project/jupyterlab-pioneer)
|
|
4
4
|
[](https://www.npmjs.com/package/jupyterlab-pioneer)
|
|
@@ -8,12 +8,15 @@ A JupyterLab extension for generating and exporting JupyterLab event telemetry d
|
|
|
8
8
|
## Get started
|
|
9
9
|
|
|
10
10
|
### Run the extension with docker compose
|
|
11
|
+
|
|
11
12
|
```bash
|
|
12
13
|
# enter the configuration_examples directory and run
|
|
13
14
|
docker compose -p jupyterlab-pioneer up --build
|
|
14
15
|
```
|
|
15
|
-
|
|
16
|
-
|
|
16
|
+
A JupyterLab application with the extension installed and configured will run on localhost:8888.
|
|
17
|
+
|
|
18
|
+
(To play with different exporter configurations, edit [Dockerfile](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/Dockerfile#L28-L32) and run docker compose again)
|
|
19
|
+
|
|
17
20
|
### Or install the extension and configure it manually
|
|
18
21
|
|
|
19
22
|
To install the extension, execute:
|
|
@@ -21,15 +24,27 @@ To install the extension, execute:
|
|
|
21
24
|
```bash
|
|
22
25
|
pip install jupyterlab-pioneer
|
|
23
26
|
```
|
|
27
|
+
|
|
24
28
|
Before starting Jupyter Lab, users need to write their own configuration files (or use the provided configuration examples) and **place them in the correct directory**.
|
|
25
29
|
|
|
26
30
|
Examples of configurations are [here](#configurations).
|
|
27
31
|
|
|
28
32
|
## Configurations
|
|
33
|
+
|
|
29
34
|
### Overview
|
|
35
|
+
|
|
30
36
|
The configuration file controls the activated events and data exporters.
|
|
31
37
|
|
|
32
|
-
To add a data exporter, users should assign a callable function along with function arguments when configuring `exporters`.
|
|
38
|
+
To add a data exporter, users should assign a callable function along with function arguments when configuring `exporters`.
|
|
39
|
+
|
|
40
|
+
This extension provides 4 default exporters.
|
|
41
|
+
|
|
42
|
+
- [`console_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L10), which sends telemetry data to the browser console
|
|
43
|
+
- [`command_line_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L33), which sends telemetry data to the python console jupyter is running on
|
|
44
|
+
- [`file_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L55), which saves telemetry data to local file
|
|
45
|
+
- [`remote_exporter`](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/jupyterlab_pioneer/handlers.py#L81), which sends telemetry data to a remote http endpoint
|
|
46
|
+
|
|
47
|
+
Additionally, users can import default exporters or write customized exporters in the configuration file.
|
|
33
48
|
|
|
34
49
|
### Configuration file name & path
|
|
35
50
|
|
|
@@ -38,6 +53,7 @@ Jupyter Server expects the configuration file to be named after the extension’
|
|
|
38
53
|
Jupyter Server looks for an extension’s config file in a set of specific paths. **The configuration file should be saved into one of the config directories provided by `jupyter --path`.**
|
|
39
54
|
|
|
40
55
|
Check jupyter server [doc](https://jupyter-server.readthedocs.io/en/latest/operators/configuring-extensions.html) for more details.
|
|
56
|
+
|
|
41
57
|
### Syntax
|
|
42
58
|
|
|
43
59
|
`activateEvents`: An array of the ids of the events. Only valid events (1. has an id associated with the event class, and 2. the event id is included in `activatedEvents`) will be activated.
|
|
@@ -45,16 +61,22 @@ Check jupyter server [doc](https://jupyter-server.readthedocs.io/en/latest/opera
|
|
|
45
61
|
`logNotebookContentEvents`: An array of the ids of the events. The extension will export the entire notebook content only for valid events (1. has an id associated with the event class, and 2. the event id is included in `logNotebookContentEvents`).
|
|
46
62
|
|
|
47
63
|
`exporters`: An array of exporters. Each exporter should have the following structure:
|
|
64
|
+
|
|
48
65
|
```python
|
|
49
66
|
{
|
|
50
67
|
exporter: # a callable exporter function. Need to contain 'path' for file_exporter, 'url' for remote_exporter.
|
|
51
68
|
args: # arguments passed to the exporter function
|
|
52
69
|
}
|
|
53
70
|
```
|
|
54
|
-
**The configuration file should be saved into one of the config directories provided by `jupyter --path`.**
|
|
55
71
|
|
|
56
72
|
### Example
|
|
57
|
-
|
|
73
|
+
#### Default exporters
|
|
74
|
+
|
|
75
|
+
[all_exporters/jupyter_jupyterlab_pioneer_config.py](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/all_exporters/jupyter_jupyterlab_pioneer_config.py)
|
|
76
|
+
|
|
77
|
+
#### Customized exporter function
|
|
78
|
+
|
|
79
|
+
[custom_exporter/jupyter_jupyterlab_pioneer_config.py](https://github.com/educational-technology-collective/jupyterlab-pioneer/blob/main/configuration_examples/customized_exporter/jupyter_jupyterlab_pioneer_config.py)
|
|
58
80
|
|
|
59
81
|
## Uninstall
|
|
60
82
|
|