Ever wished the compactness of shell scripts be put into a real programming language?
Say hello to Plumbum Shell Combinators. Plumbum (Latin for lead, which was used to create
pipes back in the day) is a small yet feature-rich library for shell script-like programs in Python.
The motto of the library is “Never write shell scripts again”, and thus it attempts to mimic
the shell syntax (shell combinators) where it makes sense, while keeping it all Pythonic
and cross-platform.

2018.08.10: Version 1.6.7 released with several minor additions, mostly to CLI apps, and run_* modifiers added.

2018.02.12: Version 1.6.6 released with one more critical bugfix for a error message regression in 1.6.5.

2017.12.29: Version 1.6.5 released with mostly bugfixes, including a critical one that could break pip installs on some platforms. English cli apps now load as fast as before the localization update.

2017.11.27: Version 1.6.4 released with new CLI localization support. Several bugfixes and better pathlib compatibility, along with better separation between Plumbum’s internal packages.

2016.12.31: Version 1.6.3 released to provide Python 3.6 compatibility. Mostly bugfixes, several smaller improvements to paths, and a provisional config parser added.

2016.12.3: Version 1.6.2 is now available through conda-forge, as well.

2016.6.25: Version 1.6.2 released. This is mostly a bug fix release, but a few new features are included. Modifiers allow some new arguments, and Progress is improved. Better support for SunOS and other OS’s.

2015.12.18: Version 1.6.1 released. The release mostly contains smaller fixes for CLI, 2.6/3.5 support, and colors. PyTest is now used for tests, and Conda is supported.

2015.10.16: Version 1.6.0 released. Highlights include Python 3.5 compatibility, the plumbum.colors package, Path becoming a subclass of str and a host of bugfixes. Special thanks go to Henry for his efforts.

2015.07.17: Version 1.5.0 released. This release brings a host of bug fixes, code cleanups and some experimental new features (be sure to check the changelog). Also, say hi to Henry Schreiner, who has joined as a member of the project.

importloggingfromplumbumimportcliclassMyCompiler(cli.Application):verbose=cli.Flag(["-v","--verbose"],help="Enable verbose mode")include_dirs=cli.SwitchAttr("-I",list=True,help="Specify include directories")@cli.switch("-loglevel",int)defset_log_level(self,level):"""Sets the log-level of the logger"""logging.root.setLevel(level)defmain(self,*srcfiles):print"Verbose:",self.verboseprint"Include dirs:",self.include_dirsprint"Compiling:",srcfilesif__name__=="__main__":MyCompiler.run()

The library is developed on GitHub, and will happily
accept patches from users. Please use the GitHub’s
built-in issue tracker to report any problem
you encounter or to request features. The library is released under the permissive MIT license.

Plumbum supports Python 2.6-3.7 and PyPy and is continually
tested on Linux, Mac, and Windows machines through Travis CI
and Appveyor.
Any Unix-like machine should work fine out of the box,
but on Windows, you’ll probably want to install a decent coreutils
environment and add it to your PATH. I can recommend mingw (which comes
bundled with Git for Windows), but cygwin
should work too. If you only wish to use Plumbum as a Popen-replacement to run Windows programs,
then there’s no need for the Unix tools.

Note that for remote command execution, an openSSH-compatible client is required (also bundled
with Git for Windows), and a bash-compatible shell and a coreutils environment is also
expected on the host machine.

You can download the library from the Python Package Index
(in a variety of formats), or run pipinstallplumbum directly. If you use Anaconda, you can also get it from the conda-forge channel with condainstall-cconda-forgeplumbum.

The user guide covers most of the features of Plumbum, with lots of code-snippets to get you
swimming in no time. It introduces the concepts and “syntax” gradually, so it’s recommended
you read it in order. A quick reference guide is available.

The API reference (generated from the docstrings within the library) covers all of the
exposed APIs of the library. Note that some “advanced” features and some function parameters are
missing from the guide, so you might want to consult with the API reference in these cases.

The original purpose of Plumbum was to enable local and remote program execution with ease,
assuming nothing fancier than good-old SSH. On top of this, a file-system abstraction layer
was devised, so that working with local and remote files would be seamless.

I’ve toyed with this idea for some time now, but it wasn’t until I had to write build scripts
for a project I’ve been working on that I decided I’ve had it with shell scripts and it’s time
to make it happen. Plumbum was born from the scraps of the Path class, which I
wrote for the aforementioned build system, and the SshContext and SshTunnel classes
that I wrote for RPyC. When I combined the two with shell combinators
(because shell scripts do have an edge there) the magic happened and here we are.

The project has been inspired by PBS (now called sh)
of Andrew Moffat,
and has borrowed some of his ideas (namely treating programs like functions and the
nice trick for importing commands). However, I felt there was too much magic going on in PBS,
and that the syntax wasn’t what I had in mind when I came to write shell-like programs.
I contacted Andrew about these issues, but he wanted to keep PBS this way. Other than that,
the two libraries go in different directions, where Plumbum attempts to provide a more
wholesome approach.

Plumbum also pays tribute to Rotem Yaari who suggested a
library code-named pyplatform for that very purpose, but which had never materialized.