From 675d68254debe94524e40d2d9fa5ab5bbee87447 Mon Sep 17 00:00:00 2001 From: Tim Savannah Date: Mon, 21 Mar 2016 11:24:17 -0400 Subject: [PATCH] Update documentation and fix version number specified in module --- ChangeLog | 3 +++ README.md | 8 ++++++++ README.rst | 7 +++++++ doc/func_timeout.dafunc.html | 19 ++++++++++++++++++- doc/func_timeout.html | 20 +++++++++++++++++--- func_timeout/__init__.py | 4 ++-- func_timeout/dafunc.py | 14 ++++++++++++++ setup.py | 2 +- 8 files changed, 70 insertions(+), 7 deletions(-) diff --git a/ChangeLog b/ChangeLog index 18fd87c..ec1fa43 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,6 @@ +* 3.0.1 - Mar 21 2016 +- Update documentation + * 3.0.0 - Mar 18 2016 - Change implementation to not leave lingering threads after a timeout occurs - Split module into several parts diff --git a/README.md b/README.md index b02a080..4ef248d 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,14 @@ So, for esxample, if you have a function "doit('arg1', 'arg2')" that you want to # Handle any exceptions that doit might raise here +How it works +------------ + +func\_timeout will run the specified function in a thread with the specified arguments until it returns, raises an exception, or the timeout is exceeded. +If there is a return or an exception raised, it will be returned/raised as normal. + +If the timeout has exceeded, the "FunctionTimedOut" exception will be raised in the context of the function being called, as well as from the context of "func\_timeout". You should have your function catch the "FunctionTimedOut" exception and exit cleanly if possible. Every 2 seconds until your function is terminated, it will continue to raise FunctionTimedOut. The terminating of the timed-out function happens in the context of the thread and will not block main execution. + Support ------- diff --git a/README.rst b/README.rst index 80c0b43..cf66145 100644 --- a/README.rst +++ b/README.rst @@ -66,6 +66,13 @@ So, for esxample, if you have a function "doit('arg1', 'arg2')" that you want to # Handle any exceptions that doit might raise here +How it works +------------ + +func_timeout will run the specified function in a thread with the specified arguments until it returns, raises an exception, or the timeout is exceeded. +If there is a return or an exception raised, it will be returned/raised as normal. + +If the timeout has exceeded, the "FunctionTimedOut" exception will be raised in the context of the function being called, as well as from the context of "func_timeout". You should have your function catch the "FunctionTimedOut" exception and exit cleanly if possible. Every 2 seconds until your function is terminated, it will continue to raise FunctionTimedOut. The terminating of the timed-out function happens in the context of the thread and will not block main execution. Support diff --git a/doc/func_timeout.dafunc.html b/doc/func_timeout.dafunc.html index 12c86a1..a7ef7ea 100644 --- a/doc/func_timeout.dafunc.html +++ b/doc/func_timeout.dafunc.html @@ -9,7 +9,10 @@  
func_timeout.dafuncindex -

+

Copyright (c) 2016 Tim Savannah All Rights Reserved.
+ 
+Licensed under the Lesser GNU Public License Version 3, LGPLv3. You should have recieved a copy of this with the source distribution as
+LICENSE, otherwise it is available at https://github.com/kata198/func_timeout/LICENSE

@@ -37,6 +40,20 @@ Raises any exceptions #func# would raise, returns&  
@raises - FunctionTimedOut if #timeout# is exceeded, otherwise anything #func# could raise will be raised
 
+If the timeout is exceeded, FunctionTimedOut will be raised within the context of the called function every two seconds until it terminates,
+but will not block the calling thread (a new thread will be created to perform the join). If possible, you should try/except FunctionTimedOut
+to return cleanly, but in most cases it will 'just work'.
+ 
+Be careful of code like:
+def myfunc():
+    while True:
+        try:
+            dosomething()
+        except Exception:
+            continue
+ 
+because it will never terminate.
+ 
@return - The return value that #func# gives
diff --git a/doc/func_timeout.html b/doc/func_timeout.html index 9b74a9e..51e64c2 100644 --- a/doc/func_timeout.html +++ b/doc/func_timeout.html @@ -6,7 +6,7 @@  
func_timeout (version 3.0.1)
 
- 
func_timeout (version 2.0.0)		index

Copyright (c) 2016 Tim Savannah All Rights Reserved.
@@ -45,7 +45,7 @@ LICENSE, otherwise it is available at https://gith class FunctionTimedOut(builtins.BaseException)     -Common base class for all exceptions
  +FunctionTimedOut - Exception raised when a function times out
   

Method resolution order:
FunctionTimedOut
@@ -114,6 +114,20 @@ Raises any exceptions #func# would raise, returns&  
@raises - FunctionTimedOut if #timeout# is exceeded, otherwise anything #func# could raise will be raised
 
+If the timeout is exceeded, FunctionTimedOut will be raised within the context of the called function every two seconds until it terminates,
+but will not block the calling thread (a new thread will be created to perform the join). If possible, you should try/except FunctionTimedOut
+to return cleanly, but in most cases it will 'just work'.
+ 
+Be careful of code like:
+def myfunc():
+    while True:
+        try:
+            dosomething()
+        except Exception:
+            continue
+ 
+because it will never terminate.
+ 
@return - The return value that #func# gives

@@ -123,5 +137,5 @@ Raises any exceptions #func# would raise, returns&
        __all__ = ('func_timeout', 'FunctionTimedOut')
-__version_tuple__ = (2, 0, 0)
+__version_tuple__ = (3, 0, 1) diff --git a/func_timeout/__init__.py b/func_timeout/__init__.py index 61ca80c..f72e743 100644 --- a/func_timeout/__init__.py +++ b/func_timeout/__init__.py @@ -6,8 +6,8 @@ ''' -__version__ = '2.0.0' -__version_tuple__ = (2, 0, 0) +__version__ = '3.0.1' +__version_tuple__ = (3, 0, 1) __all__ = ('func_timeout', 'FunctionTimedOut') diff --git a/func_timeout/dafunc.py b/func_timeout/dafunc.py index 8ac7373..a8ce943 100644 --- a/func_timeout/dafunc.py +++ b/func_timeout/dafunc.py @@ -23,6 +23,20 @@ def func_timeout(timeout, func, args=(), kwargs=None): @raises - FunctionTimedOut if #timeout# is exceeded, otherwise anything #func# could raise will be raised + If the timeout is exceeded, FunctionTimedOut will be raised within the context of the called function every two seconds until it terminates, + but will not block the calling thread (a new thread will be created to perform the join). If possible, you should try/except FunctionTimedOut + to return cleanly, but in most cases it will 'just work'. + + Be careful of code like: + def myfunc(): + while True: + try: + dosomething() + except Exception: + continue + + because it will never terminate. + @return - The return value that #func# gives ''' diff --git a/setup.py b/setup.py index 7d40491..b17dba5 100755 --- a/setup.py +++ b/setup.py @@ -30,7 +30,7 @@ if __name__ == '__main__': log_description = summary setup(name='func_timeout', - version='3.0.0', + version='3.0.1', packages=['func_timeout'], author='Tim Savannah', author_email='kata198@gmail.com',