Vinay Sajip avatar Vinay Sajip committed 303a305 Draft

Routine update.

Comments (0)

Files changed (1)

docs/tutorial.rst

   which would depend on how many bytes the Capture reads at a time. You can
   also pass a ``buffer_size=-1`` to indicate that you want to use line-
   buffering, i.e. read a line at a time from the child process. (This may only
-  work if the child process flushes its outbut buffers after every line.)
+  work as expected if the child process flushes its outbut buffers after every
+  line.)
 * We make a ``flush`` call in the ``receiver`` script, to ensure that the pipe
   is flushed to the capture queue. You could avoid the  ``flush`` call in the
   above example if you used ``python -u receiver`` as the command (which runs
    The ``expect`` method was added.
 
 To illustrate usage of :meth:`Capture.expect`, consider the program
-``lister.py`` (which is provided as part of the source distribution). This
-prints ``line 1``, ``line 2`` etc. indefinitely with a configurable delay,
-flushing its output stream after each line. We can capture the output from a
-run of ``lister.py``, ensuring that we use line-buffering::
+``lister.py`` (which is provided as part of the source distribution, as it's
+used in the tests). This prints ``line 1``, ``line 2`` etc. indefinitely with
+a configurable delay, flushing its output stream after each line. We can
+capture the output from a run of ``lister.py``, ensuring that we use
+line-buffering in the parent process::
 
     >>> from sarge import Capture, run
-    >>> c = Capture(buffer_size=-1)
+    >>> c = Capture(buffer_size=-1)     # line-buffering
     >>> p = run('python lister.py -d 0.01', async=True, stdout=c)
     >>> m = c.expect('^line 1$')
     >>> m.span()
 such cases, you can't work with these programs using ``sarge``; you need to use
 a pseudo-terminal approach, such as is provided by (for example)
 `pexpect <http://noah.org/wiki/pexpect>`_. ``Sarge`` works within the limits
-of the
-:mod:`subprocess` module, which means sticking to ``stdin``, ``stdout`` and
-``stderr`` as ordinary streams or pipes (but not pseudo-terminals).
+of the :mod:`subprocess` module, which means sticking to ``stdin``, ``stdout``
+and ``stderr`` as ordinary streams or pipes (but not pseudo-terminals).
 
 Examples of programs which work directly through their controlling terminal
 are ``ftp`` and ``ssh`` - the password prompts for these programs are
 and you may see dire warnings on the Internet about mixing threads, processes
 and ``fork()``. It *is* a heady mix, to be sure: you need to understand what's
 going on in order to avoid nasty surprises. If you run into any such, it may be
-hard to get help because others can't reproduce the problems. However, that's no
-reason to shy away from providing the functionality altogether. Such issues
-do not occur on Windows, for example: because Windows doesn't have a ``fork()
-`` system call, child processes are created in a different way which doesn't
-give rise to the issues which sometimes crop up in a Posix environment.
+hard to get help because others can't reproduce the problems. However, that's
+no reason to shy away from providing the functionality altogether. Such issues
+do not occur on Windows, for example: because Windows doesn't have a
+``fork()`` system call, child processes are created in a different way which
+doesn't give rise to the issues which sometimes crop up in a Posix environment.
 
 For an exposition of the sort of things which might bite you if you are using
 locks, threading and ``fork()`` on Posix, see `this post
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.