# Using `psh` magics
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
`pshnb` adds `%bash` and `%%bash` functions to Jupyter and IPython,
which execute expressions in a persistent shell.
## Installation
Install pshnb with:
pip install pshnb
Once that’s complete, you can install the magics to all IPython and
Jupyter sessions automatically by running in your terminal:
pshnb_install
If you don’t want to install the automatic magic, you can instead run in
notebooks where you want to use it:
%load_ext pshnb
## What’s the point?
In jupyter and ipython, you can run a shell command using the `!`
prefix:
``` python
!pwd
```
/Users/jhoward/aai-ws/pshnb
However, each time you run this command, a new shell is created and then
removed, so for instance, `cd` doesn’t actually do anything if you run
another command afterwards:
``` python
!cd ..
!pwd
```
/Users/jhoward/aai-ws/pshnb
As you see from the `!pwd` output, the directory hasn’t actually
changed!
`%bash`, on the other hand, creates a *persistent* shell, which solves
this problem:
``` python
%load_ext pshnb
```
``` python
%bash pwd
```
/Users/jhoward/aai-ws/pshnb
``` python
%bash cd ..
%bash pwd
```
/Users/jhoward/aai-ws
With `%bash`, you can implement, and document in notebooks, multi-step
stateful shell interactions, including setting environment variables,
sourcing scripts, and changing directories.
## Features
### Cell magic
You can use the `%%bash` cell magic to run multi-line shell commands,
such as here-docs. For instance:
``` bash
%%bash
cat > tmp << EOF
hi
there
EOF
```
This creates a file called `tmp` containing two lines. Let’s check it
worked, and then remove it – as you see, you can also use the cell magic
to run multiple commands:
``` bash
%%bash
cat tmp
rm tmp
```
hi
there
### Variable expansion
You can pipe commands together just like in a regular shell, and use
standard unix utilities like `head` to process the output. For instance,
here we show just the first 3 lines of the directory listing:
``` python
%bash ls | head -3
```
_nbs
_proc
addnew.py
You can use Python variables in your shell commands by prefixing them
with `@{}`. For instance, here we create a variable `n` and then display
it using `echo`:
``` python
n = 2
```
``` python
%bash echo @{n}
```
2
Here we use `n` to show just the first two entries from the directory
listing:
``` python
%bash ls | head -@{n}
```
_nbs
_proc
### Background tasks
You can run commands in the background in the shell by adding `&` at the
end of a command. The parentheses `(...)` group commands together to run
as one unit. In this example, we first print “starting”, and then create
a background process that will wait for 1 second (using `sleep 1`) and
then print “finished”. The shell immediately shows us “starting” and
tells us it created background process number 1 (with a process ID):
``` bash
%%bash
echo starting
(sleep 1; echo finished) &
```
starting
[1] 18618
For this demonstration, we wait for 1.1 seconds (slightly longer than
the background process needs). During this time, the background process
will complete in the background. But we won’t see any output from it
yet.
``` python
from time import sleep
sleep(1.1)
```
The next time we run *any* `psh` magic we will also see any output that
has occurred in our persistent shell since the last command. Run `%bash`
by itself to *only* see those updates, e.g here we see that “finished”
was printed, and the shell tells us that background job 1 completed
successfully.
``` python
%bash
```
finished
[1]+ Done ( sleep 1; echo finished )
### Flags
You can get help on the `%bash` magic’s options using `-h`.
``` python
%bash -h
```
::
%bash [-h] [-r [RESET]] [-o] [-x] [-X] [-s] [-S] [-t TIMEOUT]
[command ...]
Run line or cell in persistent shell
positional arguments:
command The command to run
options:
-h, --help Show this help
-r <[RESET]>, --reset <[RESET]>
Reset the shell interpreter (optionally choose shell)
-o, --obj Return this magic object
-x, --expand Enable variable expansion
-X, --no-expand Disable variable expansion
-s, --sudo Enable sudo
-S, --no-sudo Disable sudo
-t TIMEOUT, --timeout TIMEOUT
Set timeout in seconds
You can reset the shell to its initial state using the `-r` flag. Let’s
first check our current directory:
``` python
%bash pwd
```
/Users/jhoward/aai-ws
Now let’s reset the shell:
``` python
%bash -r
```
As you can see, after resetting we’re back in our starting directory:
``` python
%bash pwd
```
/Users/jhoward/aai-ws/pshnb
The `-s` flag enables `sudo` mode, which runs commands as the root user,
and `-S` disables it. For instance, here we first enable `sudo` mode:
``` python
%bash -s
```
Then we can check which user we’re running as:
``` python
%bash whoami
```
root
As you can see, we’re now running as `root`. We can disable `sudo` mode:
``` python
%bash -S
```
And when we check again, we’re back to our regular user:
``` python
%bash whoami
```
jhoward
You can set a timeout (in seconds) using the `-t` flag, which will raise
a `TIMEOUT` exception if a command takes too long. For instance, here we
set a 1-second timeout:
``` python
%bash -t 1
```
Then we try to run a command that sleeps for 2 seconds – since this is
longer than our timeout, we’ll get a timeout error:
``` python
from pexpect import TIMEOUT
```
``` python
try: get_ipython().run_line_magic('bash', 'sleep 2')
except TIMEOUT: print("timed out")
```
timed out
Raw data
{
"_id": null,
"home_page": "https://github.com/answerdotai/pshnb",
"name": "pshnb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python bash",
"author": "Jeremy Howard",
"author_email": "info@answer.ai",
"download_url": "https://files.pythonhosted.org/packages/b5/4e/b1fc47076d91a053c2784c9f9a82d0e781195256f1aad422b0185d9ebc8d/pshnb-0.0.3.tar.gz",
"platform": null,
"description": "# Using `psh` magics\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n`pshnb` adds `%bash` and `%%bash` functions to Jupyter and IPython,\nwhich execute expressions in a persistent shell.\n\n## Installation\n\nInstall pshnb with:\n\n pip install pshnb\n\nOnce that\u2019s complete, you can install the magics to all IPython and\nJupyter sessions automatically by running in your terminal:\n\n pshnb_install\n\nIf you don\u2019t want to install the automatic magic, you can instead run in\nnotebooks where you want to use it:\n\n %load_ext pshnb\n\n## What\u2019s the point?\n\nIn jupyter and ipython, you can run a shell command using the `!`\nprefix:\n\n``` python\n!pwd\n```\n\n /Users/jhoward/aai-ws/pshnb\n\nHowever, each time you run this command, a new shell is created and then\nremoved, so for instance, `cd` doesn\u2019t actually do anything if you run\nanother command afterwards:\n\n``` python\n!cd ..\n!pwd\n```\n\n /Users/jhoward/aai-ws/pshnb\n\nAs you see from the `!pwd` output, the directory hasn\u2019t actually\nchanged!\n\n`%bash`, on the other hand, creates a *persistent* shell, which solves\nthis problem:\n\n``` python\n%load_ext pshnb\n```\n\n``` python\n%bash pwd\n```\n\n /Users/jhoward/aai-ws/pshnb\n\n``` python\n%bash cd ..\n%bash pwd\n```\n\n /Users/jhoward/aai-ws\n\nWith `%bash`, you can implement, and document in notebooks, multi-step\nstateful shell interactions, including setting environment variables,\nsourcing scripts, and changing directories.\n\n## Features\n\n### Cell magic\n\nYou can use the `%%bash` cell magic to run multi-line shell commands,\nsuch as here-docs. For instance:\n\n``` bash\n%%bash\ncat > tmp << EOF\nhi\nthere\nEOF\n```\n\nThis creates a file called `tmp` containing two lines. Let\u2019s check it\nworked, and then remove it \u2013 as you see, you can also use the cell magic\nto run multiple commands:\n\n``` bash\n%%bash\ncat tmp\nrm tmp\n```\n\n hi\n there\n\n### Variable expansion\n\nYou can pipe commands together just like in a regular shell, and use\nstandard unix utilities like `head` to process the output. For instance,\nhere we show just the first 3 lines of the directory listing:\n\n``` python\n%bash ls | head -3\n```\n\n _nbs\n _proc\n addnew.py\n\nYou can use Python variables in your shell commands by prefixing them\nwith `@{}`. For instance, here we create a variable `n` and then display\nit using `echo`:\n\n``` python\nn = 2\n```\n\n``` python\n%bash echo @{n}\n```\n\n 2\n\nHere we use `n` to show just the first two entries from the directory\nlisting:\n\n``` python\n%bash ls | head -@{n}\n```\n\n _nbs\n _proc\n\n### Background tasks\n\nYou can run commands in the background in the shell by adding `&` at the\nend of a command. The parentheses `(...)` group commands together to run\nas one unit. In this example, we first print \u201cstarting\u201d, and then create\na background process that will wait for 1 second (using `sleep 1`) and\nthen print \u201cfinished\u201d. The shell immediately shows us \u201cstarting\u201d and\ntells us it created background process number 1 (with a process ID):\n\n``` bash\n%%bash\necho starting\n(sleep 1; echo finished) &\n```\n\n starting\n [1] 18618\n\nFor this demonstration, we wait for 1.1 seconds (slightly longer than\nthe background process needs). During this time, the background process\nwill complete in the background. But we won\u2019t see any output from it\nyet.\n\n``` python\nfrom time import sleep\nsleep(1.1)\n```\n\nThe next time we run *any* `psh` magic we will also see any output that\nhas occurred in our persistent shell since the last command. Run `%bash`\nby itself to *only* see those updates, e.g here we see that \u201cfinished\u201d\nwas printed, and the shell tells us that background job 1 completed\nsuccessfully.\n\n``` python\n%bash\n```\n\n finished\n\n [1]+ Done ( sleep 1; echo finished )\n\n### Flags\n\nYou can get help on the `%bash` magic\u2019s options using `-h`.\n\n``` python\n%bash -h\n```\n\n ::\n\n %bash [-h] [-r [RESET]] [-o] [-x] [-X] [-s] [-S] [-t TIMEOUT]\n [command ...]\n\n Run line or cell in persistent shell\n\n positional arguments:\n command The command to run\n\n options:\n -h, --help Show this help\n -r <[RESET]>, --reset <[RESET]>\n Reset the shell interpreter (optionally choose shell)\n -o, --obj Return this magic object\n -x, --expand Enable variable expansion\n -X, --no-expand Disable variable expansion\n -s, --sudo Enable sudo\n -S, --no-sudo Disable sudo\n -t TIMEOUT, --timeout TIMEOUT\n Set timeout in seconds\n\nYou can reset the shell to its initial state using the `-r` flag. Let\u2019s\nfirst check our current directory:\n\n``` python\n%bash pwd\n```\n\n /Users/jhoward/aai-ws\n\nNow let\u2019s reset the shell:\n\n``` python\n%bash -r\n```\n\nAs you can see, after resetting we\u2019re back in our starting directory:\n\n``` python\n%bash pwd\n```\n\n /Users/jhoward/aai-ws/pshnb\n\nThe `-s` flag enables `sudo` mode, which runs commands as the root user,\nand `-S` disables it. For instance, here we first enable `sudo` mode:\n\n``` python\n%bash -s\n```\n\nThen we can check which user we\u2019re running as:\n\n``` python\n%bash whoami\n```\n\n root\n\nAs you can see, we\u2019re now running as `root`. We can disable `sudo` mode:\n\n``` python\n%bash -S\n```\n\nAnd when we check again, we\u2019re back to our regular user:\n\n``` python\n%bash whoami\n```\n\n jhoward\n\nYou can set a timeout (in seconds) using the `-t` flag, which will raise\na `TIMEOUT` exception if a command takes too long. For instance, here we\nset a 1-second timeout:\n\n``` python\n%bash -t 1\n```\n\nThen we try to run a command that sleeps for 2 seconds \u2013 since this is\nlonger than our timeout, we\u2019ll get a timeout error:\n\n``` python\nfrom pexpect import TIMEOUT\n```\n\n``` python\ntry: get_ipython().run_line_magic('bash', 'sleep 2')\nexcept TIMEOUT: print(\"timed out\")\n```\n\n timed out\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "AI magic",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/answerdotai/pshnb"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python",
"bash"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9228a927d576cd75c0d0833bf21041b962f233b8b5237c8a718eaba8e358a146",
"md5": "1c8e9bef892abc98fd02b9994ab86e19",
"sha256": "aeda66ecf42d3efad5f3db3aad406a4e4b6b0b20eabce7480d6932e5b972cba1"
},
"downloads": -1,
"filename": "pshnb-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c8e9bef892abc98fd02b9994ab86e19",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11068,
"upload_time": "2025-07-21T05:07:51",
"upload_time_iso_8601": "2025-07-21T05:07:51.590968Z",
"url": "https://files.pythonhosted.org/packages/92/28/a927d576cd75c0d0833bf21041b962f233b8b5237c8a718eaba8e358a146/pshnb-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b54eb1fc47076d91a053c2784c9f9a82d0e781195256f1aad422b0185d9ebc8d",
"md5": "40a983b3504e38f57649c3c298725073",
"sha256": "b88cee1284c8595434dc8a7e8d35851586f8c5c1e4ced5bd8e81c1fbc64c9377"
},
"downloads": -1,
"filename": "pshnb-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "40a983b3504e38f57649c3c298725073",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12440,
"upload_time": "2025-07-21T05:07:52",
"upload_time_iso_8601": "2025-07-21T05:07:52.850128Z",
"url": "https://files.pythonhosted.org/packages/b5/4e/b1fc47076d91a053c2784c9f9a82d0e781195256f1aad422b0185d9ebc8d/pshnb-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 05:07:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "answerdotai",
"github_project": "pshnb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pshnb"
}
JSON
