Skip to content

xonsh/xontrib-jupyter

Repository files navigation

Xonsh kernel for Jupyter Notebook and Jupyter Lab allows to execute xonsh shell commands in a notebook cell.

If you like the idea click ⭐ on the repo and tweet.

Installation

To install use xpip:

xpip install xontrib-jupyter
# or: xpip install -U git+https://github.com/xonsh/xontrib-jupyter

xontrib load jupyter
xonfig jupyter-kernel --help  # Options for installing.
xonfig jupyter-kernel --user  # Install kernel spec in user config directory.

Check the installation:

jupyter kernelspec list
# Available kernels:
#  python3    /opt/homebrew/lib/python3.11/site-packages/ipykernel/resources
#  xonsh      /PATH_TO_ENV_PREFIX/share/jupyter/kernels/xonsh

xontrib load jupyter
xonfig jupyter-kernel
# Installing Jupyter kernel spec:
#  root: None
#  prefix: /PATH_TO_ENV_PREFIX/
#  as user: False

xonfig info
#| jupyter          | True
#| jupyter kernel   | /PATH_TO_ENV_PREFIX/share/jupyter/kernels/xonsh

Usage

Jupyter

Just run Jupyter Notebook or JupyterLab and choose xonsh:

jupyter notebook
# or
jupyter lab

Euporie

Euporie is a terminal based interactive computing environment.

euporie-notebook --kernel-name xonsh  # or change the kernel in UI
# or
euporie-console --kernel-name xonsh  # or change the kernel in UI

Testing

  • install the project with its dependencies
poetry install
poetry install --only-root
  • now start the xonsh shell
xonsh --no-rc
  • inside the xonsh shell, you can load the jupyter xontrib and install the kernel
xontrib load jupyter

# this will install the kernel
xonfig jupyter-kernel --user

# now start a notebook and choose xonsh kernel
jupyter notebook

Releasing your package

  1. Bump the version of the package poetry version patch (or minor/major)

  2. Push the changes to the repo and publish with

    poe release
  3. The release notes are automatically generated as a draft release after each PR.

  4. Create a GitHub release from the draft release against the newly pushed tag

Known issues

Uncaptured output

In some cases you need to enable capturing first:

$XONSH_CAPTURE_ALWAYS = True
$XONSH_SUBPROC_CAPTURED_PRINT_STDERR = True

Uncaptured output because of pager

Some tools like AWS CLI using the uncapturable less pager to show the output by default. In these cases you need to find the way to disable the pager e.g. set $AWS_PAGER = 'cat' for AWS CLI.

Credits