← Back to branch summary

~ubuntu-branches/ubuntu/quantal/enigmail/quantal-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: 2013-09-13 16:02:15 UTC
  • mfrom: (0.12.16)
  • Revision ID: package-import@ubuntu.com-20130913160215-u3g8nmwa0pdwagwc
Tags: 2:1.5.2-0ubuntu0.12.10.1
* New upstream release v1.5.2 for Thunderbird 24

* Build enigmail using a stripped down Thunderbird 17 build system, as it's
  now quite difficult to build the way we were doing previously, with the
  latest Firefox build system
* Add debian/patches/no_libxpcom.patch - Don't link against libxpcom, as it
  doesn't exist anymore (but exists in the build system)
* Add debian/patches/use_sdk.patch - Use the SDK version of xpt.py and
  friends
* Drop debian/patches/ipc-pipe_rename.diff (not needed anymore)
* Drop debian/patches/makefile_depth.diff (not needed anymore)

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`