StaSh - Shell Like an Expert in Pythonista

Inspired by shellista and its variants, StaSh is a serious attempt to implement a Bash-like shell for Pythonista.

Since its initial release, valuable contributions and advices have been received constantly from the Pythonista community. The two most popular utilities are pip (authored by @briarfox) and git (authored by @jsbain). Remarkable contributions are also made by @dgelessus, @pudquick, @oefe, @cclauss, @georg.viehoever, @BBOOXX, @bennr01, @glider-gun, @steljas, @zrzka, @seanld, @zed, @sdushantha and @ywang-bom.

StaSh stands for Pythonista Shell. While Sta may not be the best abbreviation for Pythonista, it forms a concise and meaningful word with the following Sh part. So the name StaSh was chosen to indicate it is a confined environment and great treasures may be found within.

Installation

StaSh can be easily installed via one line of python command (courtesy of @whitone).

import requests as r; exec(r.get('https://bit.ly/get-stash').content)

Simply copy the above line, paste into Pythonista interactive prompt and execute. It installs StaSh as a Python module under the site-packages folder (~/Documents/site-packages/stash) and copies a launching script, ~/Documents/launch_stash.py for easy access.

StaSh works with both Pythonista 2 and 3, though not all commands support python3.

If you have previous versions of StaSh installed (e.g. v0.4.x), You may need to restart Pythonista BEFORE the installation.

If you have a GitHub tool available in Pythonista, such as gitview or gitrepo, you can choose to directly clone or download the repository.

StaSh requires Pythonista v2.0 or Pythonista3 as the new ObjC feature is heavily used. For older Pythonista 1.5 compatible version, please refer to the v0.4 branch.

Starting with 0.7.4, StaSh supports being run on a PC using the tkinter module. This is intended for development purposes and may not offer you the best user experience. To install StaSh on your PC, either use the line above or clone this repository and run setup.py.

Upgrade

Once StaSh is installed, it can be easily updated by running the selfupdate command from within the shell.

• selfupdate defaults to the master branch. To update from a different branch, e.g. dev, use selfupdate dev.
• By default, selfupdate compares local and remote versions and only performs update if newer version is found. You can however force the update without version checking via selfupdate -f.
• To check for newer version without actually install it, use selfupdate -n.
• selfupdate manages StaSh installation folder and may delete files in the process. It is therefore recommended to not place your own scripts under $STASH_ROOT/bin. Instead, save your own scripts in~/Documents/bin or customise the locations with the BIN_PATH environment variable.
• You may need to restart Pythonista after the update for changes to take full effects.

selfupdate cannot be used for version 0.4.x and under. A fresh installation is needed. Version 0.7.0 requires a forced update. Please run selfupdate -f.

Notable Features

StaSh has a pile of features that are expected from a real shell. These features are what really set the difference from shellista.

• Panel UI program that is completely event driven

  • No blocking thread, builtin interactive prompt is accessible at all time
  • Consistent look and feel as a proper PC terminal
  • Almost all scripts can be called from within StaSh, including programs using UI and Scene packages.
  • Attributed text (color and style) support
  • Multiple sessions are possible by opening additional Panel tabs
  • Being a pure UI program, it is possible to launch and forget. The program stays active indefinitely. Non-UI scripts can only run for 10 minutes in background. But StaSh can stay up forever (till memory runs out due to other Apps). You can just launch StaSh to run a few commands and leave it. It will still be there for you when you return later.

• Comprehensive command line parsing and handling using pyparsing

  • Environmental variables, e.g echo $HOME, NAME=value
  • Aliases, e.g. alias l1='ls -1'
  • Single and double quotes behave like Bash, e.g. "*" means literal *, "$HOME" expands while '$HOME' does not.
  • Backslash escaping, e.g. ls My\ Script.py
  • Glob, e.g. ls ~/*.py
  • Backtick quotes for subprocess, e.g. touch `ls *.py`
  • Pipes to chain commands, e.g. find . -name "*.txt" | grep interesting
  • IO redirect (actually just Output redirect), e.g. ls *.py > py_files.txt. Input redirect can be achieved by using pipes.
    • It is possible to redirect to the Pythonista builtin console, e.g. ls > &3
  • Bang(!) to search command history, e.g. ls -1, !l. Bang commands like !! and !-1 also works.

• Smart auto-completion just as expected

  • One UI button, Tab, is provided to enable command line auto-completion.
  • It is smart to complete either commands or files based on the cursor position
  • It also completes environment variables and aliases.
  • It also features a sub-command auto-completion system. For an example, type git sta and press Tab. It will auto-completes to git status . You can easily add your own sub-commands completion via JSON files.

• Thread management allows multiple commands running in parallel

  • One foreground jobs and unlimited number of background jobs can run simultaneously.
  • A foreground job can be stopped by pressing the CC button or Ctrl-C on an external keyboard.
  • A background job is issued by appending an ampersand character (&) at the end of a normal command, e.g. httpserver &. It can be terminated by the kill command using its job ID.
  • A few utilities are provided for thread management.
    • jobs to list current running background jobs.
    • kill to kill a running job.
    • fg to bring background jobs to foreground
    • CZ button (Ctrl-Z) to send a foreground job to background

• Command line history management. Three UI buttons are provided to navigate through the history.

• On-screen virtual keys - an extra row of keys on top of the on-screen keyboard to provide control functions and easier access to symbols

  • Virtual keys for control functions including:
    • Tab - command line auto-completion
    • CC (Ctrl-C) - terminate the running job
    • CD (Ctrl-D) - end of Input
    • CU (Ctrl-U) - kill line
    • CZ (Ctrl-Z) - Send current running foreground job to background
    • KB - show/hide keyboard
    • H - display a popup window to show command history
    • Up - recall the previous command in history
    • Dn - recall the next command in history
  • Customisable virtual keys for commonly used symbols, e.g. ~/.-*|>.
    • The Symbols can be customized via the VK_SYMBOLS option in stash config file (default is .stash_config).

• Swipe on the virtual key row to position cursor (similar to what Pythonista builtin editor offers)

• External keyboard support

  • Tab key for auto-completion
  • Up (↑) / Down (↓) for navigating through command history
  • Ctrl-A and Ctrl-E to jump to the beginning and end of the input line, respectively
  • Ctrl-U to erase the input line
  • Ctrl-W to erase one word before cursor
  • Ctrl-L to clear the screen

• You can run (almost) any regular python scripts from within StaSh

  • There is no need to customize them for the shell. If it can be executed by a python interpreter via python your_script.py, you can just call it from within StaSh by just typing your_script
  • The shell object is made available to scripts being called. This enables a range of complex interactions between the shell and called scripts. For an example, the running script can use the shell object to execute more commands, e.g. _stash('pwd').

• You can give it a resource file, similar to .bashrc, to customize its behaviour. Like the Bash resource file, aliases, environment variables can be set here. The default resource file is .stashrc under StaSh installation root (i.e. ~/Documents/site-packages/stash).

  • The prompt is customizable with the PROMPT environment variable.
    • \w - current working directory with HOME folder abbreviated as ~
    • \W - last path component of current working directory
    • All other strings are displayed literally
    • The default setting is PROMPT='[\W]$ '

• Easy self update to keep update with the development by running a single selfupdate command from within the shell.

• The UI can be c