[IPython-dev] pysh is in CVS

[Fernando Perez]

Hi all,

I've put all of pysh's functionality (including @rehashx for Windows, based on 
the $pathext environment variable) into CVS.  Testers and feedback would be 
most welcome.  In a few days if all looks OK I'll make tarballs for those 
unwilling to play with raw CVS.

Rather than retype stuff, I'll paste below the pysh help docstring so you can 
get a feel for the functionality available.  Other than bugfixing, I don't 
plan on adding any significant features.

Don't even ask for job control, builting piping, etc.

To start pysh, simply type 'ipython -p pysh' (you may need to update your 
.ipython directory).

The ipythonrc-pysh profile is very compact, and the associated pysh.py file is 
also now very lightweight to speedup loading.  The bulk of the code has been 
put into InterpreterExec, an internal IPython extension (in IPython/Extensions).

Regards,

f.

========================================================================
     """Pysh is a set of modules and extensions to IPython which make shell-like
     usage with Python syntax more convenient.  Keep in mind that pysh is NOT a
     full-blown shell, so don't try to make it your /etc/passwd entry!

     In particular, it has no job control, so if you type Ctrl-Z (under Unix),
     you'll suspend pysh itself, not the process you just started.

     Since pysh is really nothing but a customized IPython, you should
     familiarize yourself with IPython's features.  This brief help mainly
     documents areas in which pysh differs from the normal IPython.

     ALIASES
     -------
     All of your $PATH has been loaded as IPython aliases, so you should be
     able to type any normal system command and have it executed.  See @alias?
     and @unalias? for details on the alias facilities.

     SPECIAL SYNTAX
     --------------
     Any lines which begin with '~', '/' and '.' will be executed as shell
     commands instead of as Python code. The special escapes below are also
     recognized.  !cmd is valid in single or multi-line input, all others are
     only valid in single-line input:

     !cmd      - pass 'cmd' directly to the shell
     !!cmd     - execute 'cmd' and return output as a list (split on '\\n')
     $var=cmd  - capture output of cmd into var, as a string
     $$var=cmd - capture output of cmd into var, as a list (split on '\\n')

     The $/$$ syntaxes make Python variables from system output, which you can
     later use for further scripting.  The converse is also possible: when
     executing an alias or calling to the system via !/!!, you can expand any
     python variable or expression by prepending it with $.  Full details of
     the allowed syntax can be found in Python's PEP 215.

     A few brief examples will illustrate these:

         fperez[~/test]|3> !ls *s.py
         scopes.py  strings.py

     ls is an internal alias, so there's no need to use !:
         fperez[~/test]|4> ls *s.py
         scopes.py*  strings.py

     !!ls will return the output into a Python variable:
         fperez[~/test]|5> !!ls *s.py
                       <5> ['scopes.py', 'strings.py']
         fperez[~/test]|6> print _5
         ['scopes.py', 'strings.py']

     $ and $$ allow direct capture to named variables:
         fperez[~/test]|7> $astr = ls *s.py
         fperez[~/test]|8> astr
                       <8> 'scopes.py\\nstrings.py'

         fperez[~/test]|9> $$alist = ls *s.py
         fperez[~/test]|10> alist
                       <10> ['scopes.py', 'strings.py']

     alist is now a normal python list you can loop over.  Using $ will expand
     back the python values when alias calls are made:
         fperez[~/test]|11> for f in alist:
                       |..>     print 'file',f,
                       |..>     wc -l $f
                       |..>
         file scopes.py     13 scopes.py
         file strings.py      4 strings.py

     IPython's input history handling is still active, which allows you to
     rerun a single block of multi-line input by simply using exec:
         fperez[~/test]|12> $$alist = ls *.eps
         fperez[~/test]|13> exec _i11
         file image2.eps    921 image2.eps
         file image.eps    921 image.eps

     While these are new special-case syntaxes, they are designed to allow very
     efficient use of the shell with minimal typing.  At an interactive shell
     prompt, conciseness of expression wins over readability.

     USEFUL FUNCTIONS AND MODULES
     ----------------------------
     The os, sys and shutil modules from the Python standard library are
     automatically loaded.  Some additional functions, useful for shell usage,
     are listed below.  You can request more help about them with '?'.

     shell   - execute a command in the underlying system shell
     system  - like shell(), but return the exit status of the command
     sout    - capture the output of a command as a string
     lout    - capture the output of a command as a list (split on '\\n')
     getoutputerror - capture (output,error) of a shell command

     sout/lout are the functional equivalents of $/$$.  They are provided to
     allow you to capture system output in the middle of true python code,
     function definitions, etc (where $ and $$ are invalid).

     DIRECTORY MANAGEMENT
     --------------------
     Since each command passed by pysh to the underlying system is executed in
     a shell which exits immediately, you can NOT use !cd to navigate the
     filesystem.

     Pysh provides its own builtin '@cd' magic command to move in the
     filesystem (the @ is not required with automagic on).  It also maintains a
     list of visited directories (use @dhist to see it) and allows direct
     switching to any of them.  Type 'cd?' for more details.

     @pushd, @popd and @dirs are provided for directory stack handling.