Metadata-Version: 2.1
Name: ssh-ipykernel
Version: 1.1.1
Summary: A remote jupyter ipykernel via ssh
Home-page: https://github.com/bernhard-42/ssh_ipykernel
Author: Bernhard Walter
Author-email: b_walter@arcor.de
License: MIT license
Description: # SSH Kernel - an ipykernel over ssh
        
        A remote jupyterkernel via ssh
        
        * Free software: MIT license
        
        The ideas are heavily based on [remote_ikernel](https://bitbucket.org/tdaff/remote_ikernel), however `ssh_ipykernel`adds some important features
        
        * `jupyter_client`'s function `write_connection_file` is used on the remote server to get free ports
        * Local ports (obtained by jupyter also via `write_connection_file`) will be ssh forwarded to the remote ports
        * The ssh connection and the tunnel command will be retried in case of network or similar errors
        * introduced signal handling with python's `signal` module
        
        ## Installation
        
        ```bash
        
        pip install ssh_ipykernel
        jupyter labextension install interrupt-ipykernel-extension
        ```
        
        ## Usage
        
        * Usage of ssh_ipykernel
        
          ```text
          $ python -m ssh_ipykernel -h
          usage: __main__.py [--help] [--timeout TIMEOUT] [--env [ENV [ENV ...]]] [-s]
                            --file FILE --host HOST --python PYTHON
        
          optional arguments:
            --help, -h            show this help message and exit
            --timeout TIMEOUT, -t TIMEOUT
                                  timeout for remote commands
            --env [ENV [ENV ...]], -e [ENV [ENV ...]]
                                  environment variables for the remote kernel in the
                                  form: VAR1=value1 VAR2=value2
            -s                    sudo required to start kernel on the remote machine
        
          required arguments:
            --file FILE, -f FILE  jupyter kernel connection file
            --host HOST, -H HOST  remote host
            --python PYTHON, -p PYTHON
                                  remote python_path
          ```
        
        * Creation of kernel specification
        
          * from python
        
            ```python
            import ssh_ipykernel.manage
            ssh_ipykernel.manage.add_kernel(
                host="btest",
                display_name="SSH btest:demo(abc)",
                local_python_path="/opt/miniconda/envs/test36/bin/python",
                remote_python_path="/opt/anaconda/envs/python36",
                sudo=False,
                env="VAR1=demo VAR2=abc",
                timeout=10
            )
            ```
        
          * from terminal
        
            ```bash
            python -m ssh_ipykernel.manage --display-name "SSH btest:demo(abc) \
                                           --host btest \
                                           --python /opt/anaconda/envs/python36 \
                                           --env "VAR1=demo VAR2=abc"
            ```
        
            ```bash
            $ python -m ssh_ipykernel.manage --help
        
            usage: manage.py [--help] [--display-name DISPLAY_NAME] [--sudo]
                            [--timeout TIMEOUT] [--env [ENV [ENV ...]]] --host HOST
                            --python PYTHON
        
            optional arguments:
              --help, -h            show this help message and exit
              --display-name DISPLAY_NAME, -d DISPLAY_NAME
                                    kernel display name (default is host name)
              --sudo, -s            sudo required to start kernel on the remote machine
              --timeout TIMEOUT, -t TIMEOUT
                                    timeout for remote commands
              --env [ENV [ENV ...]], -e [ENV [ENV ...]]
                                    environment variables for the remote kernel in the
                                    form: VAR1=value1 VAR2=value2
        
            required arguments:
              --host HOST, -H HOST  remote host
              --python PYTHON, -p PYTHON
                                    remote python_path
            ```
        
        * Checking of kernel specification
        
          ```bash
          $ jupyter-kernelspec list
          Available kernels:
            ssh__ssh_btest_demo_abc_         /Users/bernhard/Library/Jupyter/kernels/ssh__ssh_btest_demo_abc_
          ```
        
          ```bash
          $ cat /Users/bernhard/Library/Jupyter/kernels/ssh__ssh_btest_demo_abc_/kernel.json
          {
            "argv": [
              "/opt/miniconda/envs/test36/bin/python",
              "-m",
              "ssh_ipykernel",
              "--host",
              "btest",
              "--python",
              "/opt/anaconda/envs/python36",
              "--timeout",
              "10",
              "--env",
              "VAR1=demo VAR2=abc",
              "-f",
              "{connection_file}"
            ],
            "display_name": "SSH btest:demo(abc)",
            "language": "python"
          }
          ```
        
        * Add an ssh config entry to `~/.ssh/config`for the remote host:
        
          ```text
          Host btest
              HostName btest.example.com
              User john
              Port 22
              IdentityFile ~/.ssh/id_rsa
              ServerAliveInterval 30
              ConnectTimeout 5
              ServerAliveCountMax 5760 
          ```
        
        ## Credits
        
        The ideas are heavily based on
        
        * [remote_ikernel](https://bitbucket.org/tdaff/remote_ikernel)
        
        
        # History
        
        ## 1.0.0 (2020-05-07)
        
        * Added an extension to send sigint to the reote kernel via ssh (needed for Windows)
        * Added Windows support (for OpoenSSH)
        * Added a call to a kernel_customize function for sub classes to inject customizations for the kernel
        
        ## 0.1.0 (2019-09-01)
        
        * First release on github
        
        ## 0.9.0 (2019-09-03)
        
        * Restructured pxssh calls
        * Rewrote keeping alive routine
        * Stabilized error detection (cluster not reachable, VPN cut, ipykernel missing)
        
        ## 0.9.2 (2019-09-20)
        
        * Added code to call ssh_ipykernel as a module to add a kernel
        * Added doc strings to all classes and methods
        
        ## 0.9.3 (2019-09-20)
        
        * Fixed argument error for env variables in ssh_ipykernel.manage
        
Keywords: ssh_ipykernel
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Provides-Extra: dev
