# deephaven_plugin_notebook
This is a Python plugin for Deephaven generated from a [deephaven-plugin](https://github.com/deephaven/deephaven-plugins) template.
This is an experimental plugin that can create and embed simple jupyter notebooks within deephaven.
It cannot show more complex resources like ipywidgets at this time.
## Plugin Structure
The `src` directory contains the Python and JavaScript code for the plugin.
Within the `src` directory, the deephaven_plugin_notebook directory contains the Python code, and the `js` directory contains the JavaScript code.
The Python files have the following structure:
`deephaven_plugin_notebook_object.py` defines a simple Python class that can wrap a notebook
`deephaven_plugin_notebook_type.py` defines the Python type for the plugin (which is used for registration) and a simple message stream.
`js_plugin.py` defines the Python class that will be used to setup the JavaScript side of the plugin.
`register.py` registers the plugin with Deephaven.
The JavaScript files have the following structure:
`DeephavenPluginNotebookPlugin.ts` registers the plugin with Deephaven.
`DeephavenPluginNotebookView.tsx` defines the plugin panel and loads the notebook.
Additionally, the `test` directory contains Python tests for the plugin. This demonstrates how the embedded Deephaven server can be used in tests.
It's recommended to use `tox` to run the tests, and the `tox.ini` file is included in the project.
## Building the Plugin
To build the plugin, you will need `npm` and `python` installed, as well as the `build` package for Python.
`nvm` is also strongly recommended, and an `.nvmrc` file is included in the project.
The python venv can be created and the recommended packages installed with the following commands:
```sh
cd deephaven_plugin_notebook
python -m venv .venv
source .venv/bin/activate
pip install --upgrade -r requirements.txt
```
Build the JavaScript plugin from the `src/js` directory:
```sh
cd src/js
nvm install
npm install
npm run build
```
Then, build the Python plugin from the top-level directory:
```sh
cd ../..
python -m build --wheel
```
The built wheel file will be located in the `dist` directory.
If you modify the JavaScript code, remove the `build` and `dist` directories before rebuilding the wheel:
```sh
rm -rf build dist
```
## Installing the Plugin
The plugin can be installed into a Deephaven instance with `pip install <wheel file>`.
The wheel file is stored in the `dist` directory after building the plugin.
Exactly how this is done will depend on how you are running Deephaven.
If using the venv created above, the plugin and server can be created with the following commands:
```sh
pip install deephaven-server
pip install dist/deephaven_plugin_notebook-0.0.1.dev0-py3-none-any.whl
deephaven server
```
See the [plug-in documentation](https://deephaven.io/core/docs/how-to-guides/use-plugins/) for more information.
After the initial setup, you can call
```sh
./rebuild.sh
```
which will reinstall and run the server.
## Using the Plugin
Once the Deephaven server is running, the plugin should be available to use.
```python
from deephaven_plugin_notebook import DeephavenPluginNotebookObject
obj = DeephavenPluginNotebookObject()
```
Here is a simple example that uses [dh.ui](https://pypi.org/project/deephaven-plugin-ui/) to make a simple notebook with input.
There are two cell types that reflect the two main jupyter cell types. Any `"code"` blocks are ran automatically, sequentially.
```python
from deephaven_plugin_notebook import DeephavenPluginNotebookObject
from ipywidgets import IntSlider
import deephaven.ui as ui
def render_notebook(text):
notebook = [
{
"type": "markdown",
"source": "Hello, World!"
},
{
"type": "code",
"source": f"print('{text}')"
}
]
return DeephavenPluginNotebookObject(notebook)
@ui.component
def demo():
text, set_text = ui.use_state("Hello, World!")
print_input = ui.text_field(value=text, on_change=set_text)
rendered_notebook = ui.use_memo(lambda: render_notebook(text), [text])
return ui.flex(print_input, rendered_notebook, direction="column", width="100%")
notebook_input = demo()
```
The function `render_notebook` could also be ran on it's own if not using `dh.ui`
## Distributing the Plugin
To distribute the plugin, you can upload the wheel file to a package repository, such as [PyPI](https://pypi.org/).
The version of the plugin can be updated in the `setup.cfg` file.
There is a separate instance of PyPI for testing purposes.
Start by creating an account at [TestPyPI](https://test.pypi.org/account/register/).
Then, get an API token from [account management](https://test.pypi.org/manage/account/#api-tokens), setting the “Scope” to “Entire account”.
To upload to the test instance, use the following commands:
```sh
python -m pip install --upgrade twine
python -m twine upload --repository testpypi dist/*
```
Now, you can install the plugin from the test instance. The extra index is needed to find dependencies:
```sh
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ deephaven_plugin_notebook
```
For a production release, create an account at [PyPI](https://pypi.org/account/register/).
Then, get an API token from [account management](https://pypi.org/manage/account/#api-tokens), setting the “Scope” to “Entire account”.
To upload to the production instance, use the following commands.
Note that `--repository` is the production instance by default, so it can be omitted:
```sh
python -m pip install --upgrade twine
python -m twine upload dist/*
```
Now, you can install the plugin from the production instance:
```sh
pip install deephaven_plugin_notebook
```
See the [Python packaging documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives) for more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "deephaven-plugin-notebook",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "deephaven, plugin, graph",
"author": "Joe Numainville",
"author_email": "josephnumainville@deephaven.io",
"download_url": null,
"platform": "any",
"description": "# deephaven_plugin_notebook\n\nThis is a Python plugin for Deephaven generated from a [deephaven-plugin](https://github.com/deephaven/deephaven-plugins) template.\n\nThis is an experimental plugin that can create and embed simple jupyter notebooks within deephaven.\nIt cannot show more complex resources like ipywidgets at this time.\n\n## Plugin Structure\n\nThe `src` directory contains the Python and JavaScript code for the plugin.\nWithin the `src` directory, the deephaven_plugin_notebook directory contains the Python code, and the `js` directory contains the JavaScript code.\n\nThe Python files have the following structure:\n`deephaven_plugin_notebook_object.py` defines a simple Python class that can wrap a notebook\n`deephaven_plugin_notebook_type.py` defines the Python type for the plugin (which is used for registration) and a simple message stream.\n`js_plugin.py` defines the Python class that will be used to setup the JavaScript side of the plugin.\n`register.py` registers the plugin with Deephaven.\n\nThe JavaScript files have the following structure:\n`DeephavenPluginNotebookPlugin.ts` registers the plugin with Deephaven.\n`DeephavenPluginNotebookView.tsx` defines the plugin panel and loads the notebook.\n\nAdditionally, the `test` directory contains Python tests for the plugin. This demonstrates how the embedded Deephaven server can be used in tests.\nIt's recommended to use `tox` to run the tests, and the `tox.ini` file is included in the project.\n\n## Building the Plugin\n\nTo build the plugin, you will need `npm` and `python` installed, as well as the `build` package for Python.\n`nvm` is also strongly recommended, and an `.nvmrc` file is included in the project.\nThe python venv can be created and the recommended packages installed with the following commands:\n```sh\ncd deephaven_plugin_notebook\npython -m venv .venv\nsource .venv/bin/activate\npip install --upgrade -r requirements.txt\n```\n\nBuild the JavaScript plugin from the `src/js` directory:\n\n```sh\ncd src/js\nnvm install\nnpm install\nnpm run build\n```\n\nThen, build the Python plugin from the top-level directory:\n\n```sh\ncd ../..\npython -m build --wheel\n```\n\nThe built wheel file will be located in the `dist` directory.\n\nIf you modify the JavaScript code, remove the `build` and `dist` directories before rebuilding the wheel:\n```sh\nrm -rf build dist\n```\n\n## Installing the Plugin\n\nThe plugin can be installed into a Deephaven instance with `pip install <wheel file>`.\nThe wheel file is stored in the `dist` directory after building the plugin.\nExactly how this is done will depend on how you are running Deephaven.\nIf using the venv created above, the plugin and server can be created with the following commands:\n```sh\npip install deephaven-server\npip install dist/deephaven_plugin_notebook-0.0.1.dev0-py3-none-any.whl\ndeephaven server\n```\nSee the [plug-in documentation](https://deephaven.io/core/docs/how-to-guides/use-plugins/) for more information.\n\nAfter the initial setup, you can call\n```sh\n./rebuild.sh\n```\nwhich will reinstall and run the server.\n\n## Using the Plugin\n\nOnce the Deephaven server is running, the plugin should be available to use.\n\n```python\nfrom deephaven_plugin_notebook import DeephavenPluginNotebookObject\n\nobj = DeephavenPluginNotebookObject()\n```\n\nHere is a simple example that uses [dh.ui](https://pypi.org/project/deephaven-plugin-ui/) to make a simple notebook with input. \nThere are two cell types that reflect the two main jupyter cell types. Any `\"code\"` blocks are ran automatically, sequentially.\n```python\nfrom deephaven_plugin_notebook import DeephavenPluginNotebookObject\nfrom ipywidgets import IntSlider\nimport deephaven.ui as ui\n\ndef render_notebook(text):\n notebook = [\n {\n \"type\": \"markdown\",\n \"source\": \"Hello, World!\"\n },\n {\n \"type\": \"code\",\n \"source\": f\"print('{text}')\"\n }\n ]\n\n return DeephavenPluginNotebookObject(notebook)\n\n@ui.component\ndef demo():\n text, set_text = ui.use_state(\"Hello, World!\")\n print_input = ui.text_field(value=text, on_change=set_text)\n rendered_notebook = ui.use_memo(lambda: render_notebook(text), [text])\n\n return ui.flex(print_input, rendered_notebook, direction=\"column\", width=\"100%\")\n\nnotebook_input = demo()\n```\nThe function `render_notebook` could also be ran on it's own if not using `dh.ui`\n\n## Distributing the Plugin\nTo distribute the plugin, you can upload the wheel file to a package repository, such as [PyPI](https://pypi.org/).\nThe version of the plugin can be updated in the `setup.cfg` file.\n\nThere is a separate instance of PyPI for testing purposes.\nStart by creating an account at [TestPyPI](https://test.pypi.org/account/register/).\nThen, get an API token from [account management](https://test.pypi.org/manage/account/#api-tokens), setting the \u201cScope\u201d to \u201cEntire account\u201d.\n\nTo upload to the test instance, use the following commands:\n```sh\npython -m pip install --upgrade twine\npython -m twine upload --repository testpypi dist/*\n```\n\nNow, you can install the plugin from the test instance. The extra index is needed to find dependencies:\n```sh\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ deephaven_plugin_notebook\n```\n\nFor a production release, create an account at [PyPI](https://pypi.org/account/register/).\nThen, get an API token from [account management](https://pypi.org/manage/account/#api-tokens), setting the \u201cScope\u201d to \u201cEntire account\u201d.\n\nTo upload to the production instance, use the following commands. \nNote that `--repository` is the production instance by default, so it can be omitted:\n```sh\npython -m pip install --upgrade twine\npython -m twine upload dist/*\n```\n\nNow, you can install the plugin from the production instance:\n```sh\npip install deephaven_plugin_notebook\n```\n\nSee the [Python packaging documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives) for more information.\n",
"bugtrack_url": null,
"license": null,
"summary": "plugin for deephaven",
"version": "0.0.1",
"project_urls": null,
"split_keywords": [
"deephaven",
" plugin",
" graph"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6efd9a926678abf5c76dba77e1b960199dca103a31eb68a45d95e0426ac3994b",
"md5": "8d7fb8359b71e0b17e4f2664279eb5c2",
"sha256": "c21bff45b87c2a0bebb13045e9ed5d2dd601cc86f750c2aa1c58b188aa08d6e6"
},
"downloads": -1,
"filename": "deephaven_plugin_notebook-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d7fb8359b71e0b17e4f2664279eb5c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14312,
"upload_time": "2024-08-05T20:48:01",
"upload_time_iso_8601": "2024-08-05T20:48:01.635970Z",
"url": "https://files.pythonhosted.org/packages/6e/fd/9a926678abf5c76dba77e1b960199dca103a31eb68a45d95e0426ac3994b/deephaven_plugin_notebook-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-05 20:48:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "deephaven-plugin-notebook"
}
JSON