Skip to main content

Plumbum: Shell Combinators

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.

Apart from shell-like syntax and handy shortcuts, the library provides local and remote command execution (over SSH), local and remote file-system paths, easy working-directory and environment manipulation, and a programmatic Command-Line Interface (CLI) application toolkit. Now let’s see some code!

This is only a teaser; the full documentation can be found at Read the Docs

Cheat Sheet

Basics

>>> from plumbum import local
>>> ls = local["ls"]
>>> ls
LocalCommand(<LocalPath /bin/ls>)
>>> ls()
u'build.py\ndist\ndocs\nLICENSE\nplumbum\nREADME.rst\nsetup.py\ntests\ntodo.txt\n'
>>> notepad = local["c:\\windows\\notepad.exe"]
>>> notepad()                                   # Notepad window pops up
u''                                             # Notepad window is closed by user, command returns

Instead of writing xxx = local["xxx"] for every program you wish to use, you can also import commands:

>>> from plumbum.cmd import grep, wc, cat, head
>>> grep
LocalCommand(<LocalPath /bin/grep>)

Piping

>>> chain = ls["-a"] | grep["-v", "\\.py"] | wc["-l"]
>>> print chain
/bin/ls -a | /bin/grep -v '\.py' | /usr/bin/wc -l
>>> chain()
u'13\n'

Redirection

>>> ((cat < "setup.py") | head["-n", 4])()
u'#!/usr/bin/env python\nimport os\n\ntry:\n'
>>> (ls["-a"] > "file.list")()
u''
>>> (cat["file.list"] | wc["-l"])()
u'17\n'

Working-directory manipulation

>>> local.cwd
<Workdir /home/tomer/workspace/plumbum>
>>> with local.cwd(local.cwd / "docs"):
...     chain()
...
u'15\n'

Foreground and background execution

>>> from plumbum import FG, BG
>>> (ls["-a"] | grep["\\.py"]) & FG         # The output is printed to stdout directly
build.py
.pydevproject
setup.py
>>> (ls["-a"] | grep["\\.py"]) & BG         # The process runs "in the background"
<Future ['/bin/grep', '\\.py'] (running)>

Command nesting

>>> from plumbum.cmd import sudo
>>> print sudo[ifconfig["-a"]]
/usr/bin/sudo /sbin/ifconfig -a
>>> (sudo[ifconfig["-a"]] | grep["-i", "loop"]) & FG
lo        Link encap:Local Loopback
          UP LOOPBACK RUNNING  MTU:16436  Metric:1

Remote commands (over SSH)

Supports openSSH-compatible clients, PuTTY (on Windows) and Paramiko (a pure-Python implementation of SSH2)

>>> from plumbum import SshMachine
>>> remote = SshMachine("somehost", user = "john", keyfile = "/path/to/idrsa")
>>> r_ls = remote["ls"]
>>> with remote.cwd("/lib"):
...     (r_ls | grep["0.so.0"])()
...
u'libusb-1.0.so.0\nlibusb-1.0.so.0.0.0\n'

CLI applications

import logging
from plumbum import cli

class MyCompiler(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)
    def set_log_level(self, level):
        """Sets the log-level of the logger"""
        logging.root.setLevel(level)

    def main(self, *srcfiles):
        print "Verbose:", self.verbose
        print "Include dirs:", self.include_dirs
        print "Compiling:", srcfiles


if __name__ == "__main__":
    MyCompiler.run()

Sample output:

$ python simple_cli.py -v -I foo/bar -Ispam/eggs x.cpp y.cpp z.cpp
Verbose: True
Include dirs: ['foo/bar', 'spam/eggs']
Compiling: ('x.cpp', 'y.cpp', 'z.cpp')

Metadata

Release files for plumbum 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distributions (sdists)

Source distribution for plumbum 1.4.0
File Size Uploaded Provenance Actions
plumbum-1.4.0.zip 66.8 kB Without provenance Details for plumbum-1.4.0.zip
plumbum-1.4.0.tar.gz 50.8 kB Without provenance Details for plumbum-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for plumbum 1.4.0
File Interpreter ABI Platform Actions
plumbum-1.4.0.win32.exe Details for plumbum-1.4.0.win32.exe

Total release size: 378.8 kB

Release files / plumbum-1.4.0.zip

Download URL plumbum-1.4.0.zip
Size 66.8 kB
Tags Source
SHA-256 checksum
How to use checksums
371208157a9ed40c36ec7228a06c334c4c2603b3de1cfb511fd695dd1a03210a
BLAKE2b-256 checksum
How to use checksums
91afdc53132f208a9c934807dc0abc05dd2924d2aeaa3f23e9ba1a7b8f2f9247
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / plumbum-1.4.0.tar.gz

Download URL plumbum-1.4.0.tar.gz
Size 50.8 kB
Tags Source
SHA-256 checksum
How to use checksums
d3f71815e37099b23306bc5c5008ea2800cdec5b0495dc4336c60cbdcf9b22ee
BLAKE2b-256 checksum
How to use checksums
61f503c6e5a3306444133d2984c3541f129255ed71f6994fb6e5f65dd5d527a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / plumbum-1.4.0.win32.exe

Download URL plumbum-1.4.0.win32.exe
Size 261.2 kB
Tags Source
SHA-256 checksum
How to use checksums
463f5672c32309efce2ee2a95619347ae258c1b28782daacf0bcb363e421cc34
BLAKE2b-256 checksum
How to use checksums
7f14e1735f8b18ed9f8b316818964ce5c6a1ba7aaaf858125fa475ce87eb0aa9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for plumbum 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.4.0 This release

3 release files No provenance

0.1.0

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page