jupyter-o2 1.1.4
Run Jupyter on Orchestra 2
License: MIT
Requires Python: >=3.6
Keywords: jupyter,remote,ssh,slurm,pexpect,orchestra,o2

===========
Jupyter-O2
===========

|PyPI version| |PyPI pyversions| |PyPI license|

.. |PyPI version| image:: https://img.shields.io/pypi/v/jupyter-o2.svg
   :target: https://pypi.python.org/pypi/jupyter-o2/

.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/jupyter-o2.svg
   :target: https://pypi.python.org/pypi/jupyter-o2/

.. |PyPI license| image:: https://img.shields.io/pypi/l/jupyter-o2.svg
   :target: https://pypi.python.org/pypi/jupyter-o2/

Jupyter-O2 is a command-line tool that remotely runs Jupyter on
Orchestra 2 (O2), an HPC cluster managed by the HMS Research Computing group.

Installation
============
First, follow the `O2 wiki's procedure <https://wiki.rc.hms.harvard.edu/display/O2/Jupyter+on+O2>`_
to set up Jupyter for your account on O2.
(If you have already installed Jupyter on O2, you can skip this step.)

Next, on your local machine:

Install Jupyter-O2.

.. code-block:: bash

    pip install jupyter-o2

Then, generate the config file.

.. code-block:: bash

    jupyter-o2 --generate-config

Follow the printed path to ``jupyter-o2.cfg`` and edit according to its instructions, particularly the
``DEFAULT_USER`` and ``INIT_JUPYTER_COMMANDS`` fields.
You may copy this file to any of the locations listed by ``jupyter-o2 --paths`` for easier access.

Make sure you have X11 forwarding active (install `XQuartz <https://www.xquartz.org/>`_ if on a Mac).

For more info on setting up Jupyter and troubleshooting Jupyter-O2, see the `jupyter-o2 tips`_.

.. _jupyter-o2 tips: https://github.com/aaronkollasch/jupyter-o2/blob/master/jupyter_o2_tips.rst

Requirements and compatibility
------------------------------
* python 3.6+
* pexpect 4.5+
* POSIX: Jupyter-O2 requires a POSIX environment such as macOS or Linux.
  If you have a Windows machine, you can try using `WSL2`_

.. _WSL2: https://github.com/aaronkollasch/jupyter-o2/blob/master/jupyter_o2_tips.rst#run-on-windows-using-wsl2

Usage
=====
Jupyter-O2 should be run locally using the following command format:

.. code-block:: bash

    jupyter-o2 [subcommand]

Examples: ``jupyter-o2 notebook`` or ``jupyter-o2 lab``
(try `JupyterLab <https://github.com/jupyterlab/jupyterlab>`__!)

This will automate the "Opening a Notebook" procedure
on the `O2 wiki <https://wiki.rc.hms.harvard.edu/display/O2/Jupyter+on+O2>`_.

Note that if Jupyter is installed on your machine, Jupyter-O2 can also be run as a Jupyter subcommand:

.. code-block:: bash

    jupyter o2 lab

For info on the Jupyter-O2 command-line options, use ``jupyter-o2 --help``.

Two-factor authentication
-------------------------
Jupyter-O2 detects the Duo two-factor authentication prompt and
requests a Duo push by default (code 1).
To send a pre-generated code, use the argument ``--2fa-code <code>``,
replacing ``<code>`` with your code.

*Experimental: use* ``--2fa-code interact`` *to interactively respond to the Duo prompt.
This allows you to request a phone or text push and enter the code you receive.*

Changelog for Jupyter-O2
========================

1.1.4 - 2022-06-13
------------------

Fixed
^^^^^
- Increased login timeout from 10 seconds to 60 seconds
  to reduce timeout errors

1.1.3 - 2022-03-06
------------------

Added
^^^^^
- Option to use SSH public key authentication #14
- Better warning messages for X11 DISPLAY error #15

1.1.2 - 2021-11-26
------------------

Added
^^^^^
- Check for available updates #13

1.1.1 - 2021-11-24
------------------

Added
^^^^^
- Fix segmentation fault on ``import Quartz``
- Fix ``try_quit_xquartz()`` in recent versions of macOS (Use the config option ``KEEP_XQUARTZ`` if quitting XQuartz is not desired.)
- Remove check for root prompt at ``login()``

1.1.0 - 2021-10-25
------------------

Jupyter-O2 detects and responds to Duo two-factor authentication
prompts automatically, requesting a Duo push by default.
This means that the arguments ``--2fa --2fa-code 1`` are no longer
required to use two-factor authentication; ``--2fa`` now has no effect.

Added
^^^^^
- Automatic detection and handling of 2FA prompts #10
- More error messages in case of job submission errors #11
- Interactive mode for responding to 2FA prompt #2

1.0.6 - 2021-06-17
------------------

Added
^^^^^

- Better error message if two-factor authentication fails
- Warning if two-factor authentication is set incorrectly
  for the computer's network location

1.0.5 - 2021-06-06
------------------

Removed
^^^^^^^

- This version removes compatibility with Python 2.7,
  which has not been supported since version 1.0.2.

Added
^^^^^

- Warning message for a common error if two-factor
  authentication is not used

Fixed
^^^^^

- Fixed moving to a new jupyter port if the original port was occupied

Updated
^^^^^^^

- Packaging system now supports PEP 517
- Raised minimum dnspython version to 2.0

1.0.4 - 2021-02-02
------------------

Added
^^^^^

- Option to change SLURM partition

Fixed
^^^^^

- #3 Improved handling of hostname decode error

1.0.2 - 2020-08-24
------------------

Added
^^^^^

- #6 Jupyter-O2 now requires only a single ssh session.
  The second ssh session is now disabled by default and can be
  re-enabled in the config file.

For information about older versions, see their `release notes`__.

__ https://github.com/aaronkollasch/jupyter-o2/releases