Merge lp:~mbp/python-fixtures/timeout into lp:~python-fixtures/python-fixtures/trunk

[Martin Pool]

This adds a new TestTimeout based on https://code.launchpad.net/~mbp/bzr/test-timeout/+merge/83559

There are two modes, because I suspect people will have different preferences for being relatively sure things will stop vs getting a clean error.

[Robert Collins (lifeless)]

We discussed on IRC.

Could you please
rename to 'Timeout', and change from talking about use in tests (e.g. 1 per test) to use in general (can only use one of these at a time because it builds on SIGALARM).

[lp:~mbp/python-fixtures/timeout]

44. By Martin Pool on 2011-11-29

Rename to just 'Timeout'; other review cleanups

45. By Martin Pool on 2011-11-29

Rename to just TimeoutException, and remove more connections to Timeout only being used in tests

[Robert Collins (lifeless)]

I've merged this. I noted some race conditions while doing so, you may want to apply them to bzrlib's version (or start using fixtures :P).

=== modified file 'NEWS'
--- NEWS	2011-11-22 09:26:54 +0000
+++ NEWS	2011-11-29 02:25:26 +0000
@@ -11,6 +11,8 @@
 * EnvironmentVariableFixture now upcalls via super().
   (Jonathan Lange, #881120)
 
+* New Timeout fixture.  (Martin Pool)
+
 0.3.7
 ~~~~~
 
 
=== modified file 'README'
--- README	2011-11-22 10:07:24 +0000
+++ README	2011-11-29 02:25:26 +0000
@@ -335,3 +335,21 @@
 
 The created directory is stored in the ``path`` attribute of the fixture after
 setUp.
+
+Timeout
++++++++
+
+Aborts if the covered code takes more than a specified number of whole wall-clock
+seconds.
+
+There are two possibilities, controlled by the 'gentle' argument: when gentle,
+an exception will be raised and the test (or other covered code) will fail.
+When not gentle, the entire process will be terminated, which is less clean,
+but more likely to break hangs where no Python code is running.  
+
+*Caution:* Only one timeout can be active at any time across all threads in a
+single process.  Using more than one has undefined results.  (This could be
+improved by chaining alarms.)
+
+*Note:* Currently supported only on Unix because it relies on the ``alarm``
+system call.
 
=== modified file 'lib/fixtures/__init__.py'
--- lib/fixtures/__init__.py	2011-11-22 08:58:38 +0000
+++ lib/fixtures/__init__.py	2011-11-29 02:25:26 +0000
@@ -51,6 +51,8 @@
     'PythonPathEntry',
     'TempDir',
     'TestWithFixtures',
+    'Timeout',
+    'TimeoutException',
     ]
 
 
@@ -64,6 +66,8 @@
     PythonPackage,
     PythonPathEntry,
     TempDir,
+    Timeout,
+    TimeoutException,
     )
 from fixtures.testcase import TestWithFixtures
 
 
=== modified file 'lib/fixtures/_fixtures/__init__.py'
--- lib/fixtures/_fixtures/__init__.py	2011-10-26 15:10:31 +0000
+++ lib/fixtures/_fixtures/__init__.py	2011-11-29 02:25:26 +0000
@@ -25,6 +25,8 @@
     'PythonPackage',
     'PythonPathEntry',
     'TempDir',
+    'Timeout',
+    'TimeoutException',
     ]
 
 
@@ -36,3 +38,7 @@
 from fixtures._fixtures.pythonpackage import PythonPackage
 from fixtures._fixtures.pythonpath import PythonPathEntry
 from fixtures._fixtures.tempdir import TempDir
+from fixtures._fixtures.timeout import (
+    Timeout,
+    TimeoutException,
+    )
 
=== added file 'lib/fixtures/_fixtures/timeout.py'
--- lib/fixtures/_fixtures/timeout.py	1970-01-01 00:00:00 +0000
+++ lib/fixtures/_fixtures/timeout.py	2011-11-29 02:25:26 +0000
@@ -0,0 +1,64 @@
+#  fixtures: Fixtures with cleanups for testing and convenience.
+#
+# Copyright (C) 2011, Martin Pool <[e-mail]>
+#
+# Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
+# license at the users choice. A copy of both licenses are available in the
+# project source as Apache-2.0 and BSD. You may not use this file except in
+# compliance with one of these two licences.
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# license you chose for the specific language governing permissions and
+# limitations under that license.
+
+
+"""Timeout fixture."""
+
+
+import signal
+
+import fixtures
+
+__all__ = [
+    'Timeout',
+    'TimeoutException',
+    ]
+
+
+class TimeoutException(Exception):
+    """Timeout expired"""
+
+
+class Timeout(fixtures.Fixture):
+    """Fixture that aborts the contained code after a number of seconds.
+
+    The interrupt can be either gentle, in which case TimeoutException is
+    raised, or not gentle, in which case the process will typically be aborted
+    by SIGALRM.
+
+    Cautions:
+     * This has no effect on Windows.
+     * Only one Timeout can be used at any time per process.
+    """
+
+    def __init__(self, timeout_secs, gentle):
+        self.timeout_secs = timeout_secs
+        self.alarm_fn = getattr(signal, 'alarm', None)
+        self.gentle = gentle
+
+    def signal_handler(self, signum, frame):
+        raise TimeoutException()
+
+    def setUp(self):
+        super(Timeout, self).setUp()
+        if self.alarm_fn is None:
+            return  # Can't run on Windows
+        self.alarm_fn(self.timeout_secs)
+        self.addCleanup(lambda: self.alarm_fn(0))
+        if self.gentle:
+            saved_handler = signal.signal(signal.SIGALRM, self.signal_handler)
+            self.addCleanup(lambda: signal.signal(
+                signal.SIGALRM, saved_handler))
+            # Otherwise, the SIGALRM will probably kill the process.
 
=== modified file 'lib/fixtures/tests/_fixtures/__init__.py'
--- lib/fixtures/tests/_fixtures/__init__.py	2011-10-27 11:58:24 +0000
+++ lib/fixtures/tests/_fixtures/__init__.py	2011-11-29 02:25:26 +0000
@@ -23,6 +23,7 @@
         'pythonpackage',
         'pythonpath',
         'tempdir',
+        'timeout',
         ]
     prefix = "fixtures.tests._fixtures.test_"
     test_mod_names = [prefix + test_module for test_module in test_modules]
 
=== added file 'lib/fixtures/tests/_fixtures/test_timeout.py'
--- lib/fixtures/tests/_fixtures/test_timeout.py	1970-01-01 00:00:00 +0000
+++ lib/fixtures/tests/_fixtures/test_timeout.py	2011-11-29 02:25:26 +0000
@@ -0,0 +1,67 @@
+#  fixtures: Fixtures with cleanups for testing and convenience.
+#
+# Copyright (C) 2011, Martin Pool <[e-mail]>
+# 
+# Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
+# license at the users choice. A copy of both licenses are available in the
+# project source as Apache-2.0 and BSD. You may not use this file except in
+# compliance with one of these two licences.
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# license you chose for the specific language governing permissions and
+# limitations under that license.
+
+import os
+import signal
+import time
+
+import testtools
+from testtools.testcase import (
+    TestSkipped,
+    )
+
+import fixtures
+
+
+def sample_timeout_passes():
+    with fixtures.Timeout(100, gentle=True):
+        pass  # Timeout shouldn't fire
+
+def sample_long_delay_with_gentle_timeout():
+    with fixtures.Timeout(1, gentle=True):
+        time.sleep(100)  # Expected to be killed here.
+
+def sample_long_delay_with_harsh_timeout():
+    with fixtures.Timeout(1, gentle=False):
+        time.sleep(100)  # Expected to be killed here.
+
+
+class TestTimeout(testtools.TestCase, fixtures.TestWithFixtures):
+
+    def requireUnix(self):
+        if getattr(signal, 'alarm', None) is None:
+            raise TestSkipped("no alarm() function")
+
+    def test_timeout_passes(self):
+        # This can pass even on Windows - the test is skipped.
+        sample_timeout_passes()
+
+    def test_timeout_gentle(self):
+        self.requireUnix()
+        self.assertRaises(
+            fixtures.TimeoutException,
+            sample_long_delay_with_gentle_timeout)
+
+    def test_timeout_harsh(self):
+        self.requireUnix()
+        # This will normally kill the whole process, which would be
+        # inconvenient.  Let's hook the alarm here so we can observe it.
+        self.got_alarm = False
+        def sigalrm_handler(signum, frame):
+            self.got_alarm = True
+        old_handler = signal.signal(signal.SIGALRM, sigalrm_handler)
+        self.addCleanup(signal.signal, signal.SIGALRM, old_handler)
+        sample_long_delay_with_harsh_timeout()
+        self.assertTrue(self.got_alarm)