open-notebook

A python cli program to open jupyter notebooks from a central server.

Overview

I typically run a single jupyter notebook server, and want to launch notebooks from several locations in the file system. This can be done from the tree view of jupyter notebook, but I want to quickly open notebooks from the command line using the central server. open-notebook will open notebooks from anywhere relative to a central server.

Features

• Can specify options like host, and port from the command line
• Defaults can be configured using the configuration file(s) .open-notebook.toml.
• Open both jupyter notebooks, and directories (in tree view).

Status

This package is actively used by the author. Please feel free to create a pull request for wanted features and suggestions!

Quick start

Use one of the following

pip install open-notebook

or

conda install -c wpk-nist open-notebook

Example usage

Options

The main command-line program is open-notebook with the following options:

$ open-notebook --help
usage: open-notebook [-h] [--host HOST] [-p PORT] [-r ROOT] [--dir-prefix DIR_PREFIX]
                     [--file-prefix FILE_PREFIX] [--reset] [-c CONFIG] [--create-config]
                     [--overwrite] [--version] [-v] [--dry]
                     [paths ...]

Program to open jupyter notebooks from central notebook server.

positional arguments:
  paths                 file or paths to open

options:
  -h, --help            show this help message and exit
  --host HOST           Host name (default='localhost')
  -p PORT, --port PORT  Port (default='8888')
  -r ROOT, --root ROOT  Directory servers was started in. Defaults to current working
                        directory.
  --dir-prefix DIR_PREFIX
                        Directory prefix (default='tree')
  --file-prefix FILE_PREFIX
                        File prefix (default='notebooks')
  --reset
  -c CONFIG, --config CONFIG
                        Config style to use. This is the name of a header in one of the
                        config files.
  --create-config       If passed, create .open-notebook.ini
  --overwrite           Pass to overwrite `~/.open-notebook.toml` if it exists with
                        `--create-config`
  --version             Print out program version
  -v, --verbose         Set verbosity level. Can pass multiple times.
  --dry                 Dry run.

You can set options with the configuration files ".open-notebook.toml". Configuration
files are found in the current directory, git root (if in a git tracked tree), and the
home directory. Note that all these files are considered, in order. That is, you could
override a single value in the current directory, and the rest would be inherited from,
in order, git root and then the home directory.

Equivalently, you can use the short name nopen, or use python -m open_notebook.

Basic usage

To open directory tree view:

open-notebook .

To open a jupyter notebook (here using the short name nopen):

nopen path/to/notebook.ipynb

To specify where the central server is running, use the -r/--root option. For example, if the server is started in the directory "~/test", then you'd pass --root ~/test. For example:

# start server
cd ~/test
jupyter notebook


# cd to some other directory under where notebook was started
cd ~/test/a/different/directory
open-notebook -r ~/test example.ipynb

Configuration file

If you always start a notebook in the same place, you can configure open-notebook as follows:

# ~/.open-notebook.toml
root = "~/test"
port = "8888"

Options name in the configuration file .open-notebook.toml are the same as the command-line options above (replacing dashes with underscores, so, e.g., instead of --dir-prefix value, you'd sed dir_prefix = "value" in the configuration file).

If you use more than one server, you can have multiple notebook configurations. For example, you can specify that the configuration alt uses port 8889 and is run in the home directory using:

# ~/.open-notebook.toml
root = "~/test"
port = "8888"

[alt]
root = "~/"
port = "8889"

The default behavior is the same as above. To use the alt config, then use:

# will use root="~/" and port="8889".  Other options inherited.
open-notebook -c alt ...

Multiple configuration files

open-notebook searches for configuration files .open-notebook.toml in the current directory, the root of a git repo (if you're currently in a git repo), and finally in the home directory. Options are read, in order, from command-line options, current directory config, git root config, and home directory config file. This means that you can specify common configurations at the home level, and then override single options at higher levels. For example, if we have:

# ~/.open-notebook.toml
root = "~/"
host = "8889"

# ~/a/b/.open-notebook.toml
host = "9999"

cd a/b
# this will open notebook with root="~/" and host="9999"
open-notebook example.ipynb

Documentation

See the documentation for further details.

License

This is free software. See LICENSE.

Contact

The author can be reached at wpk@nist.gov.

Credits

This package was created using Cookiecutter with the usnistgov/cookiecutter-nist-python template.

Changelog

Changelog for open-notebook

Unreleased

See the fragment files in changelog.d

This software was developed by employees of the National Institute of Standards and Technology (NIST), an agency of the Federal Government. Pursuant to title 17 United States Code Section 105, works of NIST employees are not subject to copyright protection in the United States and are considered to be in the public domain. Permission to freely use, copy, modify, and distribute this software and its documentation without fee is hereby granted, provided that this notice and disclaimer of warranty appears in all copies.

THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE DOCUMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE SOFTWARE WILL BE ERROR FREE. IN NO EVENT SHALL NIST BE LIABLE FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY, CONTRACT, TORT, OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SERVICES PROVIDED HEREUNDER.

Distributions of NIST software should also include copyright and licensing statements of any third-party software that are legally bundled with the code in compliance with the conditions of those licenses.