Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Remove Sphinx-related reference definitions.

Did confuse Sphinx and RST.
  • Loading branch information...
commit 467fcd2e809c5e5f1fc33ebfc8be9b5a7f172189 1 parent abd5594
@nvie authored
Showing with 27 additions and 27 deletions.
  1. +27 −27 README.rst
View
54 README.rst
@@ -2,7 +2,7 @@
drainers - Event-based draining of process output
===================================================
-drainers is an abstraction around :class:`subprocess.Popen` to read and control
+drainers is an abstraction around `subprocess.Popen` to read and control
process output event-wise. It also allows you to abort running processes
either gracefully or forcefully without having to directly interact with the
processes or threads themself.
@@ -12,10 +12,10 @@ Overview
Defining a process
------------------
-A :class:`Drainer` is a factory and controller wrapper around
-:class:`subprocess.Popen` and therefore takes all of the (optional) parameters
-that :class:`subprocess.Popen`'s initializer takes. For example, the minimal
-:class:`Drainer` takes a command array::
+A `Drainer` is a factory and controller wrapper around
+`subprocess.Popen` and therefore takes all of the (optional) parameters
+that `subprocess.Popen`'s initializer takes. For example, the minimal
+`Drainer` takes a command array::
from drainers import Drainer
@@ -29,14 +29,14 @@ But, extra arguments are allowed, too::
my_drainer = Drainer(['echo', '$JAVA_HOME'], shell=True, bufsize=64,
read_event_cb=ignore_event)
-The only two arguments to :class:`Drainer` that are reserved are
-`stdout` and `stderr`. :class:`Drainer` requires them to be
-:const:`subprocess.PIPE` explicitly, and sets them for you accordingly.
+The only two arguments to `Drainer` that are reserved are
+`stdout` and `stderr`. `Drainer` requires them to be
+`subprocess.PIPE` explicitly, and sets them for you accordingly.
Defining a callback
-------------------
-:class:`Drainer`'s strength lies in the fact that each line that is read from
-the process' standard output or standard error streams leads to a callback
+`Drainer`'s strength lies in the fact that each line that is read from the
+process' standard output or standard error streams leads to a callback
function being invoked. This allows you to process virtually any process'
output, as long as it's line-based.
@@ -47,10 +47,10 @@ function specified needs to have a specific signature::
def my_callback(line, is_err):
...
-It should take two parameters: `line` (a string) and `is_err` (a boolean). The
-latter indicates that the line is read from the standard error stream. There
-is nothing more to it. It does not need to return anything: it's return value
-will be ignored. Your callback may be a class method, too, like in the
+It should take two parameters: `line` (a string) and `is_err` (a boolean).
+The latter indicates that the line is read from the standard error stream.
+There is nothing more to it. It does not need to return anything: it's return
+value will be ignored. Your callback may be a class method, too, like in the
following example. Notice that in those cases, you pass `foo.my_method` as
the value for the `read_event_cb` parameter::
@@ -63,23 +63,23 @@ the value for the `read_event_cb` parameter::
my_drainer = Drainer(['ls'], read_event_cb=foo.my_method)
The granularity currently is a single line. If you want to read predefined
-chunks of data, please fork this repo and implement a :class:`Drainer` subclass
+chunks of data, please fork this repo and implement a `Drainer` subclass
yourself. If you want a callback that isn't invoked after each line read, but
after an arbitrary time or amount of lines, you have to implement this
-yourself. (It shouldn't be too hard, though. See the :file:`examples`
-directory for inspiration.)
+yourself. (It shouldn't be too hard, though. See the `examples` directory
+for inspiration.)
Aborting processes
------------------
-:class:`Drainer` allows you to abort a running process in the middle of
-execution, forcefully sending the process a :meth:`terminate()` message (Python
-equivalent of a Unix `SIGTERM` message) when a certain condition arises. By
-default, the process will never be terminated abnormally. To specify
-termination criteria, implement a callback function that takes no parameters
-and returns `True` if abortion is desired and `False` otherwise. For
-example, for a long running process you might want to terminate it if the disk
-is getting (almost) full. But checking how much space is free can be a
-lengthy operation, so you might want to do it only sparingly::
+`Drainer` allows you to abort a running process in the middle of execution,
+forcefully sending the process a `terminate()` message (Python equivalent of a
+Unix `SIGTERM` message) when a certain condition arises. By default, the
+process will never be terminated abnormally. To specify termination criteria,
+implement a callback function that takes no parameters and returns `True` if
+abortion is desired and `False` otherwise. For example, for a long running
+process you might want to terminate it if the disk is getting (almost) full.
+But checking how much space is free can be a lengthy operation, so you might
+want to do it only sparingly::
def out_of_diskspace():
left = handytools.check_disk_free()
@@ -101,4 +101,4 @@ result of the process.
More examples
=============
-See the :file:`examples` directory for more detailed examples.
+See the `examples` directory for more detailed examples.
Please sign in to comment.
Something went wrong with that request. Please try again.