Metadata-Version: 2.1
Name: jupyter-o2
Version: 1.0.5
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

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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you see a two-factor authentication prompt when SSH'ing into O2, you will need to tell Jupyter-O2
to request Duo pushes using the arguments ``--2fa --2fa-code 1``.

Requirements and compatibility
------------------------------
* python 3.6+
* pexpect 4.5+
* POSIX: Jupyter-O2 has not been tested on Windows, but it may work with Cygwin.
* pinentry (suggested)

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

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.

**Improvements:**

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

**Fixes:**

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

**Updates:**

- Updated packaging system for PEP 517
- Raised minimum dnspython version to 2.0

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

**New:**

- Added option to change SLURM partition

**Fixes:**

- #3 Improved handling of hostname decode error

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

**New:**

- #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
~~~~~~~~~~~~~~~~~~~~~~~~

**Enhancements:**

- #4 Improved README

**Fixes:**

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


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

**Fixes:**

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

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

**New:**

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


