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.
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').text)
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.
Once StaSh is installed, it can be easily updated by running the selfupdate
command from within the shell.
selfupdate
defaults to themaster
branch. To update from a different branch, e.g.dev
, useselfupdate 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 viaselfupdate -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 theBIN_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
.
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
- It is possible to redirect to the Pythonista builtin console,
e.g.
- Bang(!) to search command history, e.g.
ls -1
,!l
. Bang commands like!!
and!-1
also works.
- Environmental variables, e.g
-
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 pressTab
. It will auto-completes togit status
. You can easily add your own sub-commands completion via JSON files.
- One UI button,
-
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 thekill
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 foregroundCZ
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
).
- The Symbols can be customized via the
- Virtual keys for control functions including:
-
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 typingyour_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')
.
- There is no need to customize them for the shell. If it can be executed by
a python interpreter via
-
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]$ '
- The prompt is customizable with the
-
Easy self update to keep update with the development by running a single
selfupdate
command from within the shell. -
The UI can be configured via configuration file to customize its font size and color. The default config file is
.stash_config
orstash.cfg
under StaSh installation root.
The usage of StaSh is in principle similar to Bash. A few things to note are:
-
The search paths for executable scripts is set via an environment variable called
BIN_PATH
asPATH
is used by the system. The defaultBIN_PATH
is~/Documents/bin:~/Documents/stash_extensions/bin:$STASH_ROOT/bin
. -
The executable files are either Python scripts or StaSh scripts. The type of script is determined by looking at the file extensions ".py" and ".sh". A file without extension is considered as a shell script.
- When invoking a script, you can omit the extension, StaSh will try find the file
with one of the extensions. For an example, StaSh interprets the command
selfupdate
and find the fileselfupdate.py
to execute. - Files without extension won't show up as an auto-completion possibility.
- When invoking a script, you can omit the extension, StaSh will try find the file
with one of the extensions. For an example, StaSh interprets the command
-
Commands can only be written in a single line. No line continuation is possible. However, multiple commands can be written in a single line by separating them with semicolons, e.g.
ls -1 > file_list; cat file_list
. -
There are many Python scripts provided along with StaSh. These scripts range from performing regular shell tasks to advanced utilities like
ssh
andgit
. Note the scripts are by no means complete when compared to a real Linux shell. The collection will be gradually expanded should the need arise. It is also expected and appreciated that the community would come up with more scripts. Thepip
command may also install new commands.alias.py
- Define or print aliasescat.py
- Print contents of filecd.py
- Change current directoryclear.py
- Clear consolecowsay.py
- configurable speaking cowcp.py
- Copy filecrypt.py
- File encryption using AES in CBC modecurl.py
- Transfer from an URLcut.py
- Cut out selection portions of each line of a filedropbox_setup.py
- Configure dropbox accounts for other commandsdu.py
- Summarize disk usage of the set of FILEs, recursively for directorieseasy_config.py
- UI for configuring stashecho.py
- Output text to consoleedit.py
- Open any text type files in Pythonista editorfind.py
- Powerful file searching toolfg.py
- Bring a background job to foregroundftpserver.py
- A simple FTP servergci.py
- Interface to Python's built-in garbage collectorgh.py
- GitHub interfacegit.py
- Git client ported from shellistagrep.py
- search contents of file(s)head.py
- Display first lines of a filehttpserver.py
- A simple HTTP server with upload function (ripped from https://gist.github.com/UniIsland/3346170)jobs.py
- List all jobs that are currently runningkill.py
- Terminate a running joblatte.py
- package managerls.py
- List filesmail.py
- Send emails with optional file attachmentman.py
- Show help message (docstring) of a given commandmc.py
- Easily work with multiple filesystems (e.g. local and FTP) synchronously.md5sum.py
- Print or check MD5 checksumsmkdir.py
- Create directorymonkeylord.py
- Manage monkey patches with the goal to make Pythonista more viablemore.py
- Display output one screen page at a timemount.py
- Mount filesystemsmv.py
- Move fileopenin.py
- Show the open in dialog to open a file in external apps.pbcopy.py
- Copy to iOS clipboardpbpaste.py
- Paste from iOS clipboardping.py
- Ping remote hostspip.py
- Search, download, install, update and uninstall pure Python packages from PyPI.printenv.py
- List environment variablesprinthex.py
- Print hexadecimal dump of the given filepwd.py
- Print current directorypython.py
- Run python scripts or modulespython3.py
- Run python3 scripts or modulesquicklook.py
- iOS quick look for files of known typesrm.py
- delete (remove) filermdir.py
- delete (remove) directoriesscp.py
- Copy files from/to remote servers.selfupdate.py
- Update StaSh from its GitHub reposha1sum.py
- Print of check SHA1 checksumssha256sum.py
- Print of check SHA256 checksumssort.py
- Sort a list, also see uniquesource.py
- Evaluate a script in the current environmentssh.py
- SSH client to either execute a command or spawn an interactive session on remote servers. pyte is used for terminal emulation and gives the command the feel of a full-fledged SSH client.ssh-keygen.py
- Generate RSA/DSA SSH Keys.stashconf.py
- Change StaSh configuration on the flytail.py
- Print last lines of a FILE.tar.py
- Manipulate archive filestouch.py
- Update timestamp of the given file or create it if not existtotd.py
- Print a random tipumount.py
- Unmount filesystemsuniq.py
- Remove duplicates from list, also see sortunzip.py
- Unzip file, also see zipversion.py
- Show StaSh installation and version informationwc.py
- Line, word, character countingwebviewer.py
- Open a url in the webbrowserwget.py
- get data from the netwhatis.py
- Show a description for some of the commandswhich.py
- Find the exact path to a command scriptwol.py
- Wake on LAN using MAC address for launching a sleeping systemxargs.py
- Command constructing and executing utilityzip.py
- Zip file, also see unzip
- Pythonista is a wonderful piece of software.
- StaSh is inspired by shellista and its variants, including ShellistaExt and ShellistaUI.
- The UI part of StaSh has its root from ShellistaUI.
- Many of the command scripts, e.g.
ls.py
,cp.py
,mv.py
, are taken from ShellistaExt with some modifications.
- Pickled objects are not restored correctly and generate
AttributeError
as if the class definition cannot be found. - Some commands may still not fully support python3.
- Check any open issues or open a new issue to start discussions about your ideas of features and/or bugs
- Fork the repository, make changes, and send pull requests
- Please send pull requests to the dev branch instead of master