Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs
  • Loading branch information
Tomer Filiba committed May 9, 2012
1 parent 7ba51ed commit 0e72929
Show file tree
Hide file tree
Showing 8 changed files with 76 additions and 59 deletions.
2 changes: 2 additions & 0 deletions docs/cli.rst
@@ -1,3 +1,5 @@
.. _guide-cli:

Command-Line Interface (CLI)
============================

Expand Down
95 changes: 43 additions & 52 deletions docs/index.rst
Expand Up @@ -6,13 +6,17 @@ Say hello to *Plumbum Shell Combinators*. Plumbum (Latin for *lead*, which was u
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 *"You'll never have to write shell scripts again"*, and thus it
attempts to mimic the shell syntax where it makes sense, while keeping it all pythonic and
cross-platform.
cross-platform.
Apart from :ref:`shell-like syntax <guide-local-commands>` and :ref:`handy shortcuts <guide-utils>`,
the library provides local and :ref:`remote <guide-remote-machines>` command execution (over *SSH*),
local and remote file-system :ref:`paths <guide-paths>`, easy working-directory and
environment :ref:`manipulation <guide-local-machine>`, and a programmatic
:ref:`guide-cli` application toolkit. Let's see some code!

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.
Cheat Sheet
-----------

Let's see some code! ::
Basics ::

>>> from plumbum import local, FG, BG
>>> from plumbum.cmd import ls, grep, wc, cat, head
Expand All @@ -21,88 +25,74 @@ Let's see some code! ::
>>> ls()
u'build.py\ndist\ndocs\nLICENSE\nplumbum\nREADME.rst\nsetup.py\ntests\ntodo.txt\n'
# piping
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'

# cwd manipulation
Workign-directory manipulation ::
>>> local.cwd
<Workdir /home/tomer/workspace/plumbum>
>>> with local.cwd(local.cwd / "docs"):
... chain()
...
u'15\n'
# redirection
Output/Input 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'
# FG and BG
Foreground and Background Execution ::

>>> (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 backround
>>> (ls["-a"] | grep["\\.py"]) & BG # The process runs "in the background"
<Future ['/bin/grep', '\\.py'] (running)>

And you no longer have to stuggle with ``optparse``/``argparse`` to write CLI applications...
Plumbum makes it damn easy! ::

from plumbum import cli, local
from plumbum.utils import delete, copy
logger = ...
class FileCopier(cli.Application):
overwrite = cli.Flag("-o", help = "If given, overwrite existing files")
Command nesting ::
@cli.switch(["-l", "--log-to-file"], argtype = str)
def log_to_file(self, filename):
"""Logs all output to the given file"""
handler = logging.FileHandler(filename)
logger.addHandler(handler)
>>> 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) ::
@cli.switch(["--verbose"], requires=["--log-to-file"])
def set_debug(self):
"""Sets verbose mode"""
logger.setLevel(logging.DEBUG)
def main(self, src, dst):
if local.path(dst).exists():
if not self.overwrite:
logger.debug("Oh no! It's terrible")
raise ValueError("Destination already exists")
else:
delete(dst)
logger.debug("I'm going to copy %s to %s", src, dst)
copy(src, dst)
logger.debug("Great success")
if __name__ == "__main__":
FileCopier.run()
>>> from plumbum import SshMachine
>>> remote = SshMachine("your-host.com")
>>> 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'


Development
===========
The library is developed on `github <https://github.com/tomerfiliba/plumbum>`_, using
its lovely `issue tracker <https://github.com/tomerfiliba/plumbum/issues>`_; if you encounter
a problem with the library, please open an issue.
The library is developed on `github <https://github.com/tomerfiliba/plumbum>`_, and will happily
accept `pull requests <http://help.github.com/send-pull-requests/>`_ from users.
Please use the github's built-in `issue tracker <https://github.com/tomerfiliba/plumbum/issues>`_
to report any problem you encounter or to request features. The library is released under the
permissive `MIT license <https://github.com/tomerfiliba/plumbum/blob/master/LICENSE>`_.

You can **download** the library from `PyPI <http://pypi.python.org/pypi/plumbum>`_, or
``easy-install``/``pip install`` it directly.

The library is released under the `MIT license
<https://github.com/tomerfiliba/plumbum/blob/master/LICENSE>`_.
``easy-install`` / ``pip install`` it directly.

Guide
=====
User Guide
==========
.. toctree::
:maxdepth: 2

Expand All @@ -111,6 +101,7 @@ Guide
paths
remote_machine
cli
utils

API Reference
=============
Expand Down
2 changes: 2 additions & 0 deletions docs/local_commands.rst
@@ -1,3 +1,5 @@
.. _guide-local-commands:

Local Commands
==============
Plumbum exposes a special singleton object named ``local``, which represents your local machine
Expand Down
2 changes: 2 additions & 0 deletions docs/local_machine.rst
@@ -1,3 +1,5 @@
.. _guide-local-machine:

The Local Object
================
So far we've only seen running local commands, but there's more to the ``local`` object than
Expand Down
2 changes: 2 additions & 0 deletions docs/paths.rst
@@ -1,3 +1,5 @@
.. _guide-paths:

Local Paths
===========

Expand Down
2 changes: 2 additions & 0 deletions docs/remote_machine.rst
@@ -1,3 +1,5 @@
.. _guide-remote-machines:

Remote Machines
===============

Expand Down
7 changes: 7 additions & 0 deletions docs/utils.rst
@@ -0,0 +1,7 @@
.. _guide-utils:

Utilities
=========
copy
move
delete
23 changes: 16 additions & 7 deletions plumbum/commands.py
Expand Up @@ -79,8 +79,10 @@ def run_proc(proc, retcode):
:param proc: a running Popen-like object
:param retcode: the expected return (exit) code. 0 is the convention for success.
pass ``None`` in order to ignore the return code
:param retcode: the expected return (exit) code of the process. It defaults to 0 (the
convention for success). If ``None``, the return code is ignored.
It may also be a tuple (or any object that supports ``__contains__``)
of expected return codes.
:returns: A tuple of (return code, stdout, stderr)
"""
Expand All @@ -93,9 +95,14 @@ def run_proc(proc, retcode):
stdout = stdout.decode(proc.encoding, "ignore")
stderr = stderr.decode(proc.encoding, "ignore")

if retcode is not None and proc.returncode != retcode:
raise ProcessExecutionError(getattr(proc, "argv", None),
proc.returncode, stdout, stderr)
if retcode is not None:
if hasattr(retcode, "__contains__"):
if proc.returncode not in retcode:
raise ProcessExecutionError(getattr(proc, "argv", None),
proc.returncode, stdout, stderr)
elif proc.returncode != retcode:
raise ProcessExecutionError(getattr(proc, "argv", None),
proc.returncode, stdout, stderr)
return proc.returncode, stdout, stderr

#===================================================================================================
Expand Down Expand Up @@ -179,8 +186,10 @@ def run(self, args = (), **kwargs):
:param args: Any arguments to be passed to the process (a tuple)
:param retcode: The expected return code of this process (defaults to 0).
In order to disable exit-code validation, pass ``None``.
Note: this argument must be passed as a keyword argument.
In order to disable exit-code validation, pass ``None``. It may also
be a tuple (or any iterable) of expected exit codes.
.. note:: this argument must be passed as a keyword argument.
:param kwargs: Any keyword-arguments to be passed to the ``Popen`` constructor
Expand Down

0 comments on commit 0e72929

Please sign in to comment.