← Back to branch summary

~ubuntu-branches/ubuntu/precise/enigmail/precise-security

« back to all changes in this revision

Viewing changes to testing/mozbase/mozprocess/README.md

  • Committer: Package Import Robot
  • Author(s): Chris Coulson
  • Date: 2012-11-12 16:36:01 UTC
  • mfrom: (0.12.15)
  • Revision ID: package-import@ubuntu.com-20121112163601-t8e8skdfi3ni9iqp
Tags: 2:1.4.6-0ubuntu0.12.04.1
https://launchpad.net/bugs/1080212
* New upstream release v1.4.6
  - see LP: #1080212 for USN information
* Drop unneeded patches
  - remove debian/patches/correct-version-number.diff
  - remove debian/patches/dont_register_cids_multiple_times.diff
  - update debian/patches/series
* Support building in an objdir
  - update debian/rules

Show diffs side-by-side

added added

removed removed

Lines of Context:
testing/mozbase/mozprocess/README.md
 
1
[mozprocess](https://github.com/mozilla/mozbase/tree/master/mozprocess)
 
2
provides python process management via an operating system
 
3
and platform transparent interface to Mozilla platforms of interest.
 
4
Mozprocess aims to provide the ability
 
5
to robustly terminate a process (by timeout or otherwise), along with
 
6
any child processes, on Windows, OS X, and Linux. Mozprocess utilizes
 
7
and extends `subprocess.Popen` to these ends.
 
8
 
 
9
 
 
10
# API
 
11
 
 
12
[mozprocess.processhandler:ProcessHandler](https://github.com/mozilla/mozbase/blob/master/mozprocess/mozprocess/processhandler.py)
 
13
is the central exposed API for mozprocess.  `ProcessHandler` utilizes
 
14
a contained subclass of [subprocess.Popen](http://docs.python.org/library/subprocess.html),
 
15
`Process`, which does the brunt of the process management.
 
16
 
 
17
Basic usage:
 
18
 
 
19
    process = ProcessHandler(['command', '-line', 'arguments'],
 
20
                             cwd=None, # working directory for cmd; defaults to None
 
21
                             env={},   # environment to use for the process; defaults to os.environ
 
22
                             )
 
23
    exit_code = process.waitForFinish(timeout=60) # seconds
 
24
 
 
25
`ProcessHandler` offers several other properties and methods as part of its API:
 
26
 
 
27
    @property
 
28
    def timedOut(self):
 
29
        """True if the process has timed out."""
 
30
 
 
31
    def run(self):
 
32
        """
 
33
        Starts the process. waitForFinish must be called to allow the
 
34
        process to complete.
 
35
        """
 
36
 
 
37
    def kill(self):
 
38
        """
 
39
        Kills the managed process and if you created the process with
 
40
        'ignore_children=False' (the default) then it will also
 
41
        also kill all child processes spawned by it.
 
42
        If you specified 'ignore_children=True' when creating the process,
 
43
        only the root process will be killed.
 
44
 
 
45
        Note that this does not manage any state, save any output etc,
 
46
        it immediately kills the process.
 
47
        """
 
48
 
 
49
    def readWithTimeout(self, f, timeout):
 
50
        """
 
51
        Try to read a line of output from the file object |f|.
 
52
        |f| must be a pipe, like the |stdout| member of a subprocess.Popen
 
53
        object created with stdout=PIPE. If no output
 
54
        is received within |timeout| seconds, return a blank line.
 
55
        Returns a tuple (line, did_timeout), where |did_timeout| is True
 
56
        if the read timed out, and False otherwise.
 
57
 
 
58
        Calls a private member because this is a different function based on
 
59
        the OS
 
60
        """
 
61
 
 
62
    def processOutputLine(self, line):
 
63
        """Called for each line of output that a process sends to stdout/stderr."""
 
64
        for handler in self.processOutputLineHandlers:
 
65
            handler(line)
 
66
 
 
67
    def onTimeout(self):
 
68
        """Called when a process times out."""
 
69
        for handler in self.onTimeoutHandlers:
 
70
            handler()
 
71
 
 
72
    def onFinish(self):
 
73
        """Called when a process finishes without a timeout."""
 
74
        for handler in self.onFinishHandlers:
 
75
            handler()
 
76
 
 
77
    def waitForFinish(self, timeout=None, outputTimeout=None):
 
78
        """
 
79
        Handle process output until the process terminates or times out.
 
80
 
 
81
        If timeout is not None, the process will be allowed to continue for
 
82
        that number of seconds before being killed.
 
83
 
 
84
        If outputTimeout is not None, the process will be allowed to continue
 
85
        for that number of seconds without producing any output before
 
86
        being killed.
 
87
        """
 
88
 
 
89
See https://github.com/mozilla/mozbase/blob/master/mozprocess/mozprocess/processhandler.py
 
90
for the python implementation.
 
91
 
 
92
`ProcessHandler` extends `ProcessHandlerMixin` which by default prints the
 
93
output, logs to a file (if specified), and stores the output (if specified, by
 
94
default `True`).  `ProcessHandlerMixin`, by default, does none of these things
 
95
and has no handlers for `onTimeout`, `processOutput`, or `onFinish`.
 
96
 
 
97
`ProcessHandler` may be subclassed to handle process timeouts (by overriding
 
98
the `onTimeout()` method), process completion (by overriding
 
99
`onFinish()`), and to process the command output (by overriding
 
100
`processOutputLine()`).
 
101
 
 
102
# TODO
 
103
 
 
104
- Document improvements over `subprocess.Popen.kill`
 
105
- Introduce test the show improvements over `subprocess.Popen.kill`