Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/takluyver/bash_kernel

A bash kernel for IPython
https://github.com/takluyver/bash_kernel

Last synced: 7 days ago
JSON representation

A bash kernel for IPython

Awesome Lists containing this project

README 

        
.. image:: https://mybinder.org/badge_logo.svg

 :target: https://mybinder.org/v2/gh/takluyver/bash_kernel/master



=========================

A Jupyter kernel for bash

=========================



Installation

------------

This requires IPython 3.



.. code:: shell



    pip install bash_kernel

    python -m bash_kernel.install



To use it, run one of:



.. code:: shell



    jupyter notebook

    # In the notebook interface, select Bash from the 'New' menu

    jupyter qtconsole --kernel bash

    jupyter console --kernel bash



`pipx` and "externally managed" environments

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



A recent-ish `PEP 668 `_ recommends that users install Python applications with `pipx` rather than global installs with `pip`. This is strongly suggested/enforced in current Linux distros. Because `bash_kernel` needs an extra step to actually work after installing with `pip` or `pipx`, this causes some inconvenience.



First, one must install the Jupyter ecosystem with pipx, and then inject bash_kernel (and any other bits of the jupyter ecosystem you use, like papermill) into the same pipx venv.



.. code:: shell



    pipx install --include-deps jupyter

    pipx inject --include-apps --include-deps jupyter bash_kernel



One then must manually find the corresponding venv, activate it, and run `python -m bash_kernel.install` *within* that virtual env. If done outside it, this won't work as bash_kernel is not installed in the global environment.



.. code:: shell



    cd ~/.local/pipx/venvs/jupyter/

    source bin/activate

    python -m bash_kernel.install

    deactivate



Of course, one can also install bash_kernel to the global environement thusly:



.. code:: shell



    pip install --break-system-packages juptyer bash_kernel

    python -m bash_kernel.install



Requirements of Bash

~~~~~~~~~~~~~~~~~~~~



Bash kernel directly interacts with bash, and therefore requires a functioning interactive build of bash. In nearly all cases this will be the default, however some distributions remove GNU readline or other interactivity features of bash. Almost always, these features are provided in a separate, more complete bash package, which should be installed. See for example https://github.com/takluyver/bash_kernel/issues/142.



Displaying Rich Content

-----------------------



To use specialized content (images, html, etc) this file defines (in `build_cmds()`) bash functions

that take the contents as standard input. Currently, `display` (images), `displayHTML` (html)

and `displayJS` (javascript) are supported.



Example:



.. code:: shell



    cat dog.png | display

    echo "Dog, not a cat." | displayHTML

    echo "alert('Hello from bash_kernel\!');" | displayJS



Updating Rich Content Cells

---------------------------



If one is doing something that requires dynamic updates, one can specify a unique display_id,

which should be a string name. On each update, the contents will be replaced by the new value. Example:



.. code:: shell



    display_id="id_${RANDOM}"

    ((ii=0))

    while ((ii < 10)) ; do

        echo "
${ii}
" | displayHTML $display_id

        ((ii = ii+1))

        sleep 1

    done



The same works for images and javascript content.



**Remember to create always a new id** each time the cell is executed, otherwise it will try to display

on an HTML element that no longer exists (they are erased each time a cell is re-run).



Programmatically Generating Rich Content

----------------------------------------



Alternatively one can simply generate the rich content to a file in /tmp (or $TMPDIR)

and then output the corresponding (to the mimetype) context prefix ``"_TEXT_SAVED_*"``

constant. So one can write programs (C++, Go, Rust, etc.) that generates rich content

appropriately, when within a notebook.



The environment variable "NOTEBOOK_BASH_KERNEL_CAPABILITIES" will be set with a comma

separated list of the supported types (currently "image,html,javascript") that a program

can check for.



To output to a particular "display_id", to allow update of content (e.g: dynamically

updating/generating a plot from a command line program), prefix the filename

with "()". E.g: a line to display the contents of /tmp/myHTML.html to

a display id "id_12345" would look like:



    bash_kernel: saved html data to: (id_12345) /tmp/myHTML.html



More Information

----------------



For details of how this works, see the Jupyter docs on `wrapper kernels

`_, and

Pexpect's docs on the `replwrap module

`_.