Merge pull request #99 from Dyalog/notebook-v7

Dyalog jupyter kernel v.2.0.0

Author: xpqz

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.gitignore

@@ -0,0 +1,94 @@
+# Mac stuff
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+# Usually these files are written by a python script from a template
+# before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pyright
+.pyrightcache/
+
+# VSCode
+.vscode/

DEVELOPMENT.md

@@ -0,0 +1,77 @@
+## Developing and publishing the Dyalog Jupyter kernel
+
+We release from the master branch, and use semantic versioning. Releases are defined by the tag name. Find the current tag by
+
+```
+git describe --tags `git rev-list --tags --max-count=1`
+```
+
+For patch releases, add 1 to the last component of the current tag. 
+
+Update the `__version__` string in `dyalog_kernel/__main__.py` accordingly, and the `version` key in `setup.py`.
+
+The patch level should reset if we're changing major or minor version components, following semver.
+
+Build release assets with
+
+```sh
+python setup.py sdist bdist_wheel
+```
+
+Built assets will end up in `dist/`, and you can instruct `pip` to install from file for testing:
+
+```sh
+pip install dist/dyalog-jupyter-kernel-x.y.z.tar.gz
+```
+
+Now tag the master branch with the new version (prefixed by `v.`):
+
+```
+git tag -a v2.0.1 -m "Release version 2.0.1"
+git push origin v2.0.1
+```
+
+Upload release assets using [twine](https://twine.readthedocs.io/en/stable/). Install `twine` with 
+
+```sh
+pip install twine
+```
+
+Pick up the API token, and set up your `$HOME/.pypirc` file like this:
+
+```
+[distutils]
+index-servers =
+  pypi
+  testpypi
+
+[pypi]
+username = __token__
+password = pypi-A...Z  # Replace with your actual PyPI API token
+
+[testpypi]
+username = __token__
+password = pypi-A...Z  # Replace with your actual TestPyPI API token
+```
+
+Use the API key(s) as password, including the `pypi-` prefix.
+
+Upload the release to the test index first, and test that:
+
+```sh
+twine upload --repository testpypi dist/*
+```
+
+To install the module from the test index, use
+
+```sh
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple dyalog-jupyter-kernel[==2.0.1]
+python -m 'dyalog_kernel' install
+```
+The `--extra-index-url` argument is there so that `pip` can pick up any dependencies from the main index.
+
+Upload the release to the main index, and test that:
+
+```sh
+twine upload --repository pypi dist/*
+```

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include dyalog_kernel/kernelspec *

README.md

@@ -1,9 +1,50 @@
-# [Jupyter](http://jupyter.org/) kernel for [Dyalog APL](https://www.dyalog.com/)
+# Jupyter kernel for Dyalog APL
 
-## What is this and how do I use it?
+This is a [Jupyter](http://jupyter.org/) kernel for [Dyalog APL](https://www.dyalog.com/). The [wiki](https://github.com/Dyalog/dyalog-jupyter-kernel/wiki) has more details. 
 
-Please see [our wiki](https://github.com/Dyalog/dyalog-jupyter-kernel/wiki).
+For complete installation instructions from scratch on Windows, see [WINDOWS.md](WINDOWS.md) in this repository.
 
-## Do you have any premade notebook documents?
+If you're a kernel developer, see [DEVELOPMENT.md](DEVELOPMENT.md) in this repository.
+
+## Do you have any pre-made notebook documents?
 
 A collection of ready-made notebooks is available [here](https://github.com/Dyalog/dyalog-jupyter-notebooks).
+
+## Installation
+
+### Pre-requisites:
+
+- Python version 3.8 or later. Python can be installed in several ways. We recommend the standard download from https://www.python.org/downloads/. 
+- Jupyter: see the [official documentation](https://jupyter.readthedocs.io/en/latest/install.html) for installation instructions.
+
+### Installing the Dyalog kernel
+
+This kernel is installable via Python's package installer, [pip](https://pip.pypa.io/en/stable/). It comes bundled with Python, but does occasionally need updating. 
+
+In your terminal, run the follwing command:
+
+```sh
+pip install dyalog-jupyter-kernel[==2.0.1]
+```
+
+After successfully installing the kernel module itself, you need to register it with your Jupyter installation, using the following terminal command:
+
+```sh
+python -m 'dyalog_kernel' install
+```
+
+You should now be able to see the `dyalog_apl` kernel listed:
+```sh
+jupyter kernelspec list
+
+Available kernels:
+  python3       C:\Users\stefa\work\Jupyter\py312\share\jupyter\kernels\python3
+  dyalog_apl    C:\Users\stefa\AppData\Roaming\jupyter\kernels\dyalog_apl
+```
+
+Start Jupyter:
+
+```sh
+jupyter lab # or jupyter notebook
+```
+and you should now see Dyalog APL amongst your kernels. Click on the Dyalog APL icon.

WINDOWS.md

@@ -0,0 +1,50 @@
+# A full installation, from scratch, on Windows
+
+Installing, operating and maintaining a Python installation can be a bit of a chore, especially if you're not a Python developer. If you're coming to this wanting only to use Jupyter for Dyalog APL, here are some step by step instructions for how to set up the whole tool chain (on Windows) from scratch. 
+
+If you're a Python developer, or if you're already using a "canned" Python distribution, like [conda](https://docs.conda.io/en/latest/), you probably know what you're doing and can skip this document.
+
+The below instructions install Jupyter and the Dyalog kernel inside a Python "virtual environment". This means that you can keep your Jupyter work separate from any other Python work, current or future. This is usually a good idea when working with Python.
+
+1. Download and install the [Dyalog interpreter](https://www.dyalog.com/download-zone.htm). 
+2. Download, and run the official [Python installer](https://www.python.org/downloads/). Ensure you select `Use admin privileges to install Python`, `Add python.exe to PATH`, and `Disable PATH limit`.
+3. Open a PowerShell terminal. Type the following steps into the terminal window.
+4. Create a virtual Python environment with a name of your choosing, for example
+    ```
+    python -m venv jupy312
+    ```
+5. Activate the virtual environment -- this is important:
+    ```
+    jupy312\Scripts\activate
+    ```
+    Your terminal prompt should change to have a `(jupy312)` prefix.
+6. Upgrade `pip` to the latest version:
+    ```
+    python.exe -m pip installl --upgrade pip
+    ```
+7. Install `jupyterlab`:
+    ```
+    pip install jupyterlab
+    ```
+8. Install the Dyalog kernel Python module:
+    ```
+    pip install dyalog-jupyter-kernel
+    ```
+9. Register the kernel with Jupyter:
+    ```
+    python -m 'dyalog_kernel' install
+    ```
+10. Start jupyterlab:
+    ```
+    jupyter lab
+    ```
+
+A browser window should open up with the Jupyter Lab application. Click the "Dyalog APL" symbol to open a new notebook document with the Dyalog kernel.
+
+Once you're done working with Jupyter Lab, deactivate the Python environment:
+
+```
+deactivate
+```
+
+To start up Jupyter Lab again, you need to run `jupy312\Scripts\activate` and `jupyter lab` again. 

dyalog_kernel/__init__.py

@@ -1,5 +1,5 @@
 """Dyalog APL Jupyter kernel"""
 
-__version__ = '0.911'
+__version__ = '2.0.1'
 
 from .kernel import DyalogKernel

dyalog_kernel/__main__.py

@@ -1,4 +1,13 @@
+import sys
 from ipykernel.kernelapp import IPKernelApp
 from . import DyalogKernel
+from .install import install_kernel_spec
 
-IPKernelApp.launch_instance(kernel_class=DyalogKernel)
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] == 'install':
+        install_kernel_spec()
+    else:
+        IPKernelApp.launch_instance(kernel_class=DyalogKernel)
+
+if __name__ == '__main__':
+    main()

dyalog-kernel/kernel.js renamed to dyalog_kernel/dyalog_apl/kernel.js

@@ -0,0 +1,7 @@
+import os
+import subprocess
+import sys
+
+def install_kernel_spec():
+    kernel_spec_path = os.path.join(os.path.dirname(__file__), 'dyalog_apl')
+    subprocess.run([sys.executable, '-m', 'jupyter', 'kernelspec', 'install', kernel_spec_path, '--user'], check=True)

dyalog-kernel/kernel.json renamed to dyalog_kernel/dyalog_apl/kernel.json

@@ -12,7 +12,6 @@
 
 from ipykernel.kernelbase import Kernel
 from dyalog_kernel import __version__
-from notebook.services.config import ConfigManager
 
 if sys.platform.lower().startswith('win'):
     from winreg import *
@@ -254,12 +253,6 @@ def __init__(self, **kwargs):
                 self.dyalog_subprocess = subprocess.Popen([dyalog, '+s', '-q', os.path.dirname(os.path.abspath(
                     __file__)) + '/init.dws'], stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, env=dyalog_env)
 
-        # disable auto closing of brackets/quotation marks. Not very useful in APL
-        # Pass None instead of False to restore auto-closing feature
-        c = ConfigManager()
-        c.update('notebook', {'CodeCell': {
-                 'cm_config': {'autoCloseBrackets': False}}})
-
         Kernel.__init__(self, **kwargs)
 
         self.dyalog_ride_connect()