nbrshell
=============================
| Jupyter Notebook *"cell magic"* functions for remote executing shell script typed in a notebook cell.
| Shell output is streaming back to the notebook.
| Each *"cell magic"* has a non-magic equivalent function with name ending with *"_fn"*
|
| This package requires paramiko library, which is distributed under GNU Lesser General Public License v2.1

Package functions 
=============================

+------------------------------+--------------------------------------------------------------------------------------------+
|``pbrun_as_oracle``           | Connects via paramiko ssh client with a password (no prior ssh keys setup is needed),      |
|(``pbrun_as_oracle_fn``)      | then executes pbrun to switch to oracle account,                                           |
|                              | then sets oracle environment according to provided "oracle_sid",                           |
|                              | then runs provided shell commands.                                                         |
+------------------------------+--------------------------------------------------------------------------------------------+
|``pbrun_as``                  | Connects via paramiko ssh client with password (no prior ssh keys setup is needed),        |
|(``pbrun_as_fn``)             | 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, then runs provided shell commands.                     |
|(``exec_shell_script_fn``)    | If password is provided, then connects with password and no prior ssh keys setup is needed.|
|                              | If password is not provided, then attempts to connect with ssh keys.                       |
+------------------------------+--------------------------------------------------------------------------------------------+
|``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.                                            |
+------------------------------+--------------------------------------------------------------------------------------------+
|``nbrshell_common``           | Common functions and variables.                                                            |
|``set_psw``                   | Sets password in a package memory variable for use in subsequent executions.               |
+------------------------------+--------------------------------------------------------------------------------------------+

Usage examples
==============================

1. To run shell commands on a remote server:
--------------------------------------------
.. code-block:: python

    from nbrshell import exec_shell_script
    jupyter_var="This is a string defined in Jupyter"


.. code-block:: shell

	%%exec_shell_script user@host 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'


Above produces streaming output in Jupyter cell :

.. code-block:: text

	Running ping:
	--------------
	PING www.oracle.com: 56 data bytes
	64 bytes from a104-99-86-191.deploy.static.akamaitechnologies.com (104.99.86.191): icmp_seq=0. time=12.871 ms
	64 bytes from a104-99-86-191.deploy.static.akamaitechnologies.com (104.99.86.191): icmp_seq=1. time=12.706 ms
	64 bytes from a104-99-86-191.deploy.static.akamaitechnologies.com (104.99.86.191): icmp_seq=2. time=12.794 ms
	
	----www.oracle.com PING Statistics----
	3 packets transmitted, 3 packets received, 0% packet loss
	round-trip (ms)  min/avg/max/stddev = 12.706/12.790/12.871/0.083
	Running loop:
	--------------
	1
	2
	3
	4
	5
	Here document:
	--------------
		This is multiline 
		here document
	Jupyter variable substitution:
	---------------------------
	This is a string defined in Jupyter
	escaping curly braces :
	---------------------------
	{Curly braces} need to be escaped to prevent Jupyter variable substitution


2. To run SQLPLUS commands for ORACLE_SID=ORCL on a remote server:
------------------------------------------------------------------
Here password is set with `set_psw()` to let you run multiple cells without specifying the password on every cell.
Password can also be prompted and masked using `getpass` or `stdiomask`.

.. code-block:: python

	from nbrshell import pbrun_as_oracle, set_psw
	set_psw('password')

.. code-block:: shell

	%%pbrun_as_oracle user@host oracle_sid='ORCL'
	
	echo "select sysdate from dual;" | sqlplus -s / as sysdba
	
	sqlplus / as sysdba @/dev/stdin <<-EOF
		set echo on
		select 'aaa' from v\$instance;
	EOF


Above produces this streaming output in Jupyter cell :

.. code-block:: 

	SYSDATE
	---------
	01-JUN-21
	
	
	SQL*Plus: Release 19.0.0.0.0 - Production on Tue Jun 1 22:40:54 2021
	Version 19.10.0.0.0
	
	Copyright (c) 1982, 2020, Oracle.  All rights reserved.
	
	
	Connected to:
	Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production
	Version 19.10.0.0.0
	
	SQL> 	 select 'aaa' from v$instance;
	
	'AA
	---
	aaa
	
	SQL> Disconnected from Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production
	Version 19.10.0.0.0

