# nbrshell - Notebook Remote Shell
v1.0.14 Mar 2024
Set of Jupyter Notebook "cell magic" functions to execute remote shell script typed in a notebook cell,
with shell script output streaming back to the notebook.
This makes it possible to write a notebook with freeform text in markdown cells and shell constructs in code cells,
producing shell script output in output cells. This makes this a good solution for documentation purposes, prototyping,
teaching, demoing and explaining working with unix shell, as well as templating solution for repetitive script executions.
Each "cell magic" has a non-magic equivalent function with name ending with "_fn".
Similarly, there is also Oracle database-specific "cell magic" allowing to run sqlplus commands in a remote sqlplus.
This package uses paramiko library, which is distributed under GNU Lesser General Public License v2.1
## Package structure :
├── pbrun_as_oracle │──> connects via paramiko ssh client with a password (no prior ssh
├── pbrun_as_oracle_fn │ keys setup is needed), then executes pbrun to switch to oracle account,
│ then sets oracle environment according to provided "oracle_sid"
│ and runs provided shell commands as oracle user.
├── pbrun_as │──> connects via paramiko ssh client with password (no prior ssh
├── pbrun_as_fn │ keys setup is needed), then executes pbrun to switch to another user,
│ provided as a parameter. Then runs provided shell commands.
├── exec_shell_script │──> connects using paramiko ssh client. If password is provided, then
├── exec_shell_script_fn │ connects with password and no prior ssh keys setup is needed.
│ If password is not provided, then attempts to connect with ssh keys.
│ Then runs provided shell commands.
├── exec_shell_script_ssh │──> connects using local ssh client with previously setup ssh keys.
├── exec_shell_script_ssh_fn │ Useful in cases when paramiko will not connect.
└── pbrun_sqlplus │──> runs cell content via sqlplus on a remote host, after connecting
│ to the remote host with ssh, becoming oracle with pbrun and
│ setting some common Oracle environment variables.
└── nbrshell_common │──> common functions and variables.
└── set_psw └──> sets password in memory for use in subsequent cell executions.
└── set_nbrshell_env └──> saves nbr environment parameters for use in subsequent executions.
## Usage examples:
1. ### To run shell commands on a remote server:
First load remote execution package:
```python
import nbrshell as nbr
# define jupyter python variable:
jupyter_var="This is a string defined in Jupyter"
```
Then execute shell script on a remote server:
```shell
%%exec_shell_script user@host ssh_psw='password'
echo "Running ping :"
echo "--------------"
ping -s www.oracle.com 56 3
echo "Running loop :"
echo "--------------"
for i in 1 2 3 4 5; do
echo $i
done
echo "Here document :"
echo "--------------"
cat <<-EOF
This is multiline
here document
EOF
echo "Jupyter variable substitution :"
echo "---------------------------"
echo {jupyter_var}
echo "escaping curly braces :"
echo "---------------------------"
echo '\{Curly braces\} need to be escaped to prevent Jupyter variable substitution'
```
This will stream following shell output in Jupyter output cell :
<div style="width: 100%;">
<img src="https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/exec_shell_script_output.svg" style="width: 100%;" alt="Click to see the source">
</div>
The ssh connection parameters can also be set once using `nbr.set_nbrshell_env()` function, in which case it will not be necessary
to include them in subsequent cell magic commands, thus allowing for less cluttered notebook.
2. ### To run Oracle sqlplus on a remote server
- #### One option is to give all connection parameters on cell command line:
First load remote execution function:
```python
import nbrshell as nbr
```
Then run remote sqlplus commands with full command line options:
```python
%%pbrun_sqlplus username@hostname ssh_psw='password1' oracle_sid='ORCL1' oracle_conn='/ as sysdba'
select sysdate from dual;
show user
show parameters sga_target
```
which produces below output cell:
<div style="width: 100%;">
<img src="https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/pbrun_sqlplus_output_1.svg" style="width: 100%;" alt="Click to see the source">
</div>
- #### Another option is to set connection parameters once with `nbr.set_nbrshell_env()`,
and then run remote sqlplus commands in multiple cells without command line parameters.
Password can be hidden with `getpass` or `stdiomask` module if needed:
```python
# set nbr environment :
nbr.set_nbrshell_env(
ssh_conn='username@hostname',
ssh_psw='password1',
pbrun_user='oracle',
oracle_sid='ORCL1',
oracle_conn='/ as sysdba'
)
```
```python
%%pbrun_sqlplus
select sysdate from dual;
show user
```
<div style="width: 100%;">
<img src="https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/pbrun_sqlplus_output_2.svg" style="width: 100%;" alt="Click to see the source">
</div>
```python
%%pbrun_sqlplus
select 'aaa' from v$instance;
show parameters sga_target
```
<div style="width: 100%;">
<img src="https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/pbrun_sqlplus_output_3.svg" style="width: 100%;" alt="Click to see the source">
</div>
## Installation:
From PyPi:
```python
python -m pip install nbrshell
```
or from Github URL:
```python
python -m pip install nbrshell@git+https://github.com/abalbekov/nbrshell
```
Raw data
{
"_id": null,
"home_page": "https://github.com/abalbekov/nbrshell",
"name": "nbrshell",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "remote shell script execution, remote shell, shell, sqlplus",
"author": "A.Balbekov",
"author_email": "albert.y.balbekov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0b/7d/fd4093804f862d0c693dadac0f7e3fd4684504e0b14ec026890dad1eeab8/nbrshell-1.0.14.tar.gz",
"platform": null,
"description": "# nbrshell - Notebook Remote Shell\r\nv1.0.14 Mar 2024\r\n\r\nSet of Jupyter Notebook \"cell magic\" functions to execute remote shell script typed in a notebook cell, \r\nwith shell script output streaming back to the notebook.\r\n\r\nThis makes it possible to write a notebook with freeform text in markdown cells and shell constructs in code cells, \r\nproducing shell script output in output cells. This makes this a good solution for documentation purposes, prototyping, \r\nteaching, demoing and explaining working with unix shell, as well as templating solution for repetitive script executions.\r\n\r\nEach \"cell magic\" has a non-magic equivalent function with name ending with \"_fn\".\r\n\r\nSimilarly, there is also Oracle database-specific \"cell magic\" allowing to run sqlplus commands in a remote sqlplus. \r\n\r\nThis package uses paramiko library, which is distributed under GNU Lesser General Public License v2.1\r\n\r\n\r\n## Package structure :\r\n\r\n \u251c\u2500\u2500 pbrun_as_oracle \u2502\u2500\u2500> connects via paramiko ssh client with a password (no prior ssh \r\n \u251c\u2500\u2500 pbrun_as_oracle_fn \u2502 keys setup is needed), then executes pbrun to switch to oracle account,\r\n \u2502 then sets oracle environment according to provided \"oracle_sid\"\r\n \u2502 and runs provided shell commands as oracle user.\r\n\r\n \u251c\u2500\u2500 pbrun_as \u2502\u2500\u2500> connects via paramiko ssh client with password (no prior ssh \r\n \u251c\u2500\u2500 pbrun_as_fn \u2502 keys setup is needed), then executes pbrun to switch to another user,\r\n \u2502 provided as a parameter. Then runs provided shell commands.\r\n \r\n \u251c\u2500\u2500 exec_shell_script \u2502\u2500\u2500> connects using paramiko ssh client. If password is provided, then \r\n \u251c\u2500\u2500 exec_shell_script_fn \u2502 connects with password and no prior ssh keys setup is needed.\r\n \u2502 If password is not provided, then attempts to connect with ssh keys.\r\n \u2502 Then runs provided shell commands.\r\n\r\n \u251c\u2500\u2500 exec_shell_script_ssh \u2502\u2500\u2500> connects using local ssh client with previously setup ssh keys.\r\n \u251c\u2500\u2500 exec_shell_script_ssh_fn \u2502 Useful in cases when paramiko will not connect.\r\n\r\n \u2514\u2500\u2500 pbrun_sqlplus \u2502\u2500\u2500> runs cell content via sqlplus on a remote host, after connecting \r\n \u2502 to the remote host with ssh, becoming oracle with pbrun and \r\n \u2502 setting some common Oracle environment variables.\r\n \r\n \u2514\u2500\u2500 nbrshell_common \u2502\u2500\u2500> common functions and variables.\r\n \u2514\u2500\u2500 set_psw \u2514\u2500\u2500> sets password in memory for use in subsequent cell executions.\r\n \u2514\u2500\u2500 set_nbrshell_env \u2514\u2500\u2500> saves nbr environment parameters for use in subsequent executions.\r\n\r\n\r\n## Usage examples:\r\n\r\n1. ### To run shell commands on a remote server:\r\n\r\n\tFirst load remote execution package:\r\n\t\r\n\t```python\r\n\timport nbrshell as nbr\r\n\t\r\n\t# define jupyter python variable:\r\n\tjupyter_var=\"This is a string defined in Jupyter\"\r\n\t```\r\n\tThen execute shell script on a remote server:\r\n\t\r\n\t```shell\r\n\t%%exec_shell_script user@host ssh_psw='password'\r\n\t\r\n\techo \"Running ping :\"\r\n\techo \"--------------\"\r\n\tping -s www.oracle.com 56 3\r\n\t\r\n\techo \"Running loop :\"\r\n\techo \"--------------\"\r\n\tfor i in 1 2 3 4 5; do\r\n\t\techo $i\r\n\tdone\r\n\t\r\n\techo \"Here document :\"\r\n\techo \"--------------\"\r\n\tcat <<-EOF\r\n\t\tThis is multiline \r\n\t\there document\r\n\tEOF\r\n\t\r\n\techo \"Jupyter variable substitution :\"\r\n\techo \"---------------------------\"\r\n\techo {jupyter_var}\r\n\t\r\n\techo \"escaping curly braces :\"\r\n\techo \"---------------------------\"\r\n\techo '\\{Curly braces\\} need to be escaped to prevent Jupyter variable substitution'\r\n\t```\r\n\t\r\n\tThis will stream following shell output in Jupyter output cell :\r\n\t\r\n\t<div style=\"width: 100%;\">\r\n\t\t<img src=\"https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/exec_shell_script_output.svg\" style=\"width: 100%;\" alt=\"Click to see the source\">\r\n\t</div>\r\n\t\r\n\tThe ssh connection parameters can also be set once using `nbr.set_nbrshell_env()` function, in which case it will not be necessary \r\n\tto include them in subsequent cell magic commands, thus allowing for less cluttered notebook.\r\n\r\n\r\n2. ### To run Oracle sqlplus on a remote server\r\n - #### One option is to give all connection parameters on cell command line:\r\n\r\n First load remote execution function:\r\n \r\n ```python\r\n import nbrshell as nbr\r\n ```\r\n \r\n Then run remote sqlplus commands with full command line options:\r\n \r\n ```python\r\n %%pbrun_sqlplus username@hostname ssh_psw='password1' oracle_sid='ORCL1' oracle_conn='/ as sysdba'\r\n \r\n select sysdate from dual;\r\n show user\r\n show parameters sga_target\r\n ```\r\n \r\n which produces below output cell:\r\n \r\n <div style=\"width: 100%;\">\r\n <img src=\"https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/pbrun_sqlplus_output_1.svg\" style=\"width: 100%;\" alt=\"Click to see the source\">\r\n </div>\r\n\r\n\r\n - #### Another option is to set connection parameters once with `nbr.set_nbrshell_env()`,\r\n and then run remote sqlplus commands in multiple cells without command line parameters.\r\n Password can be hidden with `getpass` or `stdiomask` module if needed:\r\n\r\n ```python\r\n # set nbr environment :\r\n nbr.set_nbrshell_env(\r\n ssh_conn='username@hostname',\r\n ssh_psw='password1',\r\n pbrun_user='oracle',\r\n oracle_sid='ORCL1',\r\n oracle_conn='/ as sysdba'\r\n )\r\n ```\r\n \r\n ```python\r\n %%pbrun_sqlplus\r\n \r\n select sysdate from dual;\r\n show user\r\n ```\r\n\r\n <div style=\"width: 100%;\">\r\n <img src=\"https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/pbrun_sqlplus_output_2.svg\" style=\"width: 100%;\" alt=\"Click to see the source\">\r\n </div>\r\n\r\n ```python\r\n %%pbrun_sqlplus\r\n \r\n select 'aaa' from v$instance;\r\n show parameters sga_target\r\n ```\r\n\r\n <div style=\"width: 100%;\">\r\n <img src=\"https://raw.githubusercontent.com/abalbekov/nbrshell/main/nbrshell/readme_svg/pbrun_sqlplus_output_3.svg\" style=\"width: 100%;\" alt=\"Click to see the source\">\r\n </div>\r\n\r\n## Installation:\r\n\r\nFrom PyPi:\r\n```python\r\npython -m pip install nbrshell\r\n```\r\n\r\nor from Github URL:\r\n```python\r\npython -m pip install nbrshell@git+https://github.com/abalbekov/nbrshell\r\n```\r\n\r\n\r\n\t\r\n\t\r\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "Jupyter Notebook \"cell magic\" functions to remotely execute shell script typed in a notebook cell.",
"version": "1.0.14",
"project_urls": {
"Homepage": "https://github.com/abalbekov/nbrshell"
},
"split_keywords": [
"remote shell script execution",
" remote shell",
" shell",
" sqlplus"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c4c9eea8ff393c01fed8a74ef182260e279c67da425ba1127ed1721de8c581ea",
"md5": "7d5fef0e4ff3334f1c03e7c9378aa25a",
"sha256": "0577abab6691b4aea9e76c80c0f19b4502b30bf453e698fea3c9f94d0b3084f3"
},
"downloads": -1,
"filename": "nbrshell-1.0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d5fef0e4ff3334f1c03e7c9378aa25a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20084,
"upload_time": "2024-03-29T04:39:47",
"upload_time_iso_8601": "2024-03-29T04:39:47.023460Z",
"url": "https://files.pythonhosted.org/packages/c4/c9/eea8ff393c01fed8a74ef182260e279c67da425ba1127ed1721de8c581ea/nbrshell-1.0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0b7dfd4093804f862d0c693dadac0f7e3fd4684504e0b14ec026890dad1eeab8",
"md5": "020bb8d3b102f6dad3c7d9fafece4d1d",
"sha256": "711fc8097061dd88d7d3d9a88bcbfc889a10f7084ea491671dddb5de00606fdb"
},
"downloads": -1,
"filename": "nbrshell-1.0.14.tar.gz",
"has_sig": false,
"md5_digest": "020bb8d3b102f6dad3c7d9fafece4d1d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14695,
"upload_time": "2024-03-29T04:39:48",
"upload_time_iso_8601": "2024-03-29T04:39:48.671061Z",
"url": "https://files.pythonhosted.org/packages/0b/7d/fd4093804f862d0c693dadac0f7e3fd4684504e0b14ec026890dad1eeab8/nbrshell-1.0.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 04:39:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abalbekov",
"github_project": "nbrshell",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nbrshell"
}
JSON
