Metadata-Version: 2.1
Name: jupyter-o2
Version: 1.1.0
Summary: Run Jupyter on Orchestra 2
Home-page: https://github.com/aaronkollasch/jupyter-o2
Author: Aaron Kollasch
Author-email: aaron@kollasch.dev
License: MIT
Keywords: jupyter,remote,ssh,slurm,pexpect,orchestra,o2
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Science/Research
Classifier: Environment :: Console
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/x-rst; charset=UTF-8
Provides-Extra: test
License-File: LICENSE

===========
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`` if you wish.

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.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.

1.0.1 - 2020-07-14
------------------

Added
^^^^^

- #4 Improved README

Fixed
^^^^^

- #3 Made hostname decode error more readable
- #5 Disabled timeout when starting interactive session


1.0.0 - 2019-05-30
------------------

Fixed
^^^^^

- #3 Improve exception handling
- Fix handling of alternate ports

0.2.9 - 2018-12-04
------------------

Added
^^^^^

- #1 Initial implementation of Duo 2FA handler to address new O2 login procedures

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

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


