From 34dc236126d272a16df0915b010dca0e2e38f0d4 Mon Sep 17 00:00:00 2001 From: Thom Nichols Date: Mon, 7 Jun 2010 14:41:42 -0400 Subject: added documentation for transition_ctx and removed some superfluous comment lines --- sleekxmpp/xmlstream/statemachine.py | 26 ++++++++++++++++++++++++++ tests/test_statemachine.py | 5 ----- 2 files changed, 26 insertions(+), 5 deletions(-) diff --git a/sleekxmpp/xmlstream/statemachine.py b/sleekxmpp/xmlstream/statemachine.py index 704cabdb..c6e0ea41 100644 --- a/sleekxmpp/xmlstream/statemachine.py +++ b/sleekxmpp/xmlstream/statemachine.py @@ -105,6 +105,32 @@ class StateMachine(object): def transition_ctx(self, from_state, to_state, wait=0.0): + ''' + Use the state machine as a context manager. The transition occurs on /exit/ from + the `with` context, so long as no exception is thrown. For example: + + :: + + with state_machine.transition_ctx('one','two', wait=5) as locked: + if locked: + # the state machine is currently locked in state 'one', and will + # transition to 'two' when the 'with' statement ends, so long as + # no exception is thrown. + print 'Currently locked in state one: %s' % state_machine['one'] + + else: + # The 'wait' timed out, and no lock has been acquired + print 'Timed out before entering state "one"' + + print 'Since no exception was thrown, we are now in state "two": %s' % state_machine['two'] + + + The other main difference between this method and `transition()` is that the + state machine is locked for the duration of the `with` statement (normally, + after a `transition() occurs, the state machine is immediately unlocked and + available to another thread to call `transition()` again. + ''' + if not from_state in self.__states: raise ValueError( "StateMachine does not contain from_state %s." % state ) if not to_state in self.__states: diff --git a/tests/test_statemachine.py b/tests/test_statemachine.py index 00e4d3a3..e44b8e48 100644 --- a/tests/test_statemachine.py +++ b/tests/test_statemachine.py @@ -15,9 +15,7 @@ class testStateMachine(unittest.TestCase): def testDefaults(self): "Test ensure transitions occur correctly in a single thread" s = sm.StateMachine(('one','two','three')) -# self.assertTrue(s.one) self.assertTrue(s['one']) -# self.failIf(s.two) self.failIf(s['two']) try: s['booga'] @@ -31,12 +29,9 @@ class testStateMachine(unittest.TestCase): def testTransitions(self): "Test ensure transitions occur correctly in a single thread" s = sm.StateMachine(('one','two','three')) -# self.assertTrue(s.one) self.assertTrue( s.transition('one', 'two') ) -# self.assertTrue( s.two ) self.assertTrue( s['two'] ) -# self.failIf( s.one ) self.failIf( s['one'] ) self.assertTrue( s.transition('two', 'three') ) -- cgit v1.2.3