From 7847e3b5601213b2f71593d69d54526ba7dee53a Mon Sep 17 00:00:00 2001
From: Ilan Steemers <koed00@gmail.com>
Date: Sat, 26 Sep 2015 10:27:35 +0200
Subject: [PATCH] docs: adds shell command example

---
 docs/examples.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/docs/examples.rst b/docs/examples.rst
index e785e2c..968b94c 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,5 +1,6 @@
 Examples
 --------
+.. py:currentmodule:: django_q
 
 Emails
 ======
@@ -178,6 +179,54 @@ here's an example of how you can have Django Q take care of your indexes in real
 Now every time a Document is saved, your indexes will be updated without causing a delay in your save action.
 You could expand this to dealing with deletes, by adding a ``post_delete`` signal and calling ``index.remove_object`` in the async function.
 
+Shell
+=====
+You can execute or schedule shell commands using Pythons :mod:`subprocess` module:
+
+.. code-block:: python
+
+    from django_q.tasks import async, result
+
+    # make a backup copy of setup.py
+    async('subprocess.call', ['cp', 'setup.py', 'setup.py.bak'])
+
+    # call ls -l and dump the output
+    task_id=async('subprocess.check_output', ['ls', '-l'])
+
+    # get the result
+    dir_list = result(task_id)
+
+In Python 3.5 the subprocess module has changed quite a bit and returns a :class:`subprocess.CompletedProcess` object instead:
+
+.. code-block:: python
+
+    from django_q.tasks import async, result
+
+    # make a backup copy of setup.py
+    tid = async('subprocess.run', ['cp', 'setup.py', 'setup.py.bak'])
+
+    # get the result
+    r=result(tid, 500)
+    # we can now look at the original arguments
+    >>> r.args
+    ['cp', 'setup.py', 'setup.py.bak']
+    # and the returncode
+    >>> r.returncode
+    0
+
+    # to capture the output we'll need a pipe
+    from subprocess import PIPE
+
+    # call ls -l and pipe the output
+    tid = async('subprocess.run', ['ls', '-l'], stdout=PIPE)
+    # get the result
+    res = result(tid, 500)
+    # print the output
+    print(res.stdout)
+
+
+Instead of :func:`async` you can of course also use :func:`schedule` to schedule commands.
+
 Groups
 ======
 A group example with Kernel density estimation for probability density functions using the Parzen-window technique.