diff --git a/README.md b/README.md new file mode 100644 index 0000000..baa5e58 --- /dev/null +++ b/README.md @@ -0,0 +1,117 @@ +#### Install + +``` +% pip install bg-helper +``` + +#### Usage + +Use `bg_helper.call_func` when you need to call a function (with arbitrary +`*args` and `**kwargs`) and log any uncaught exceptions. A dict is returned with + +- `func_name` +- `args` +- `kwargs` +- `status` (ok/error) + +If the function call was successful, there will also be a `value` key. If there +was an uncaught exception, the following additional keys will be provided in the +return dict + +- `error_type` +- `error_value` +- `fqdn` +- `func_doc` +- `func_module` +- `time_epoch` +- `time_string` +- `traceback_string` + +Use `bg_helper.SimpleBackgroundTask` when you need to start a long-running +Python function, or system command (like `vlc` media player) in the background. + +``` +% ipython +... + +In [1]: import bg_helper as bh + +In [2]: def lame(): + ...: return 1/0 + +In [3]: def blah(*args, **kwargs): + ...: return locals() + +In [4]: bh.call_func(blah) +Out[4]: +{'args': '()', + 'func_name': 'blah', + 'kwargs': '{}', + 'status': 'ok', + 'value': {'args': (), 'kwargs': {}}} + +In [5]: bh.call_func(blah, 'cats', 'dogs') +Out[5]: +{'args': "('cats', 'dogs')", + 'func_name': 'blah', + 'kwargs': '{}', + 'status': 'ok', + 'value': {'args': ('cats', 'dogs'), 'kwargs': {}}} + +In [6]: bh.call_func(blah, 'cats', 'dogs', meh=[1, 2, 3, 4, 5]) +Out[6]: +{'args': "('cats', 'dogs')", + 'func_name': 'blah', + 'kwargs': "{'meh': [1, 2, 3, 4, 5]}", + 'status': 'ok', + 'value': {'args': ('cats', 'dogs'), 'kwargs': {'meh': [1, 2, 3, 4, 5]}}} + +In [7]: bh.call_func(lame) +====================================================================== +2017-04-01 12:32:35,107: func=lame args=() kwargs={} +Traceback (most recent call last): + File "/tmp/here/venv/lib/python3.5/site-packages/bg_helper/__init__.py", line 70, in call_func + value = func(*args, **kwargs) + File "", line 2, in lame + return 1/0 +ZeroDivisionError: division by zero + +Out[7]: +{'args': '()', + 'error_type': "", + 'error_value': "ZeroDivisionError('division by zero',)", + 'fqdn': 'x200-purple', + 'func_doc': None, + 'func_module': '__main__', + 'func_name': 'lame', + 'kwargs': '{}', + 'status': 'error', + 'time_epoch': 1491067955.1004958, + 'time_string': '2017_0401-Sat-123235', + 'traceback_string': 'Traceback (most recent call last):\n File "/tmp/here/venv/lib/python3.5/site-packages/bg_helper/__init__.py", line 70, in call_func\n value = func(*args, **kwargs)\n File "", line 2, in lame\n return 1/0\nZeroDivisionError: division by zero\n'} + +In [8]: cat log--bg-helper.log +2017-04-01 12:32:35,107 - ERROR - call_func: func=lame args=() kwargs={} +Traceback (most recent call last): + File "/tmp/here/venv/lib/python3.5/site-packages/bg_helper/__init__.py", line 70, in call_func + value = func(*args, **kwargs) + File "", line 2, in lame + return 1/0 +ZeroDivisionError: division by zero + +In [9]: bh.SimpleBackgroundTask('echo "hello from console" > /tmp/blahblah.txt') +Out[9]: + +In [10]: ls /tmp/blahblah.txt +/tmp/blahblah.txt + +In [11]: cat /tmp/blahblah.txt +hello from console + +In [12]: bh.SimpleBackgroundTask('echo "$(date)" >> /tmp/blahblah.txt') +Out[12]: + +In [13]: cat /tmp/blahblah.txt +hello from console +Sat Apr 1 12:33:23 CDT 2017 +``` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..e1299e3 --- /dev/null +++ b/README.rst @@ -0,0 +1,121 @@ +Install +^^^^^^^ + +:: + + % pip install bg-helper + +Usage +^^^^^ + +Use ``bg_helper.call_func`` when you need to call a function (with +arbitrary ``*args`` and ``**kwargs``) and log any uncaught exceptions. A +dict is returned with + +- ``func_name`` +- ``args`` +- ``kwargs`` +- ``status`` (ok/error) + +If the function call was successful, there will also be a ``value`` key. +If there was an uncaught exception, the following additional keys will +be provided in the return dict + +- ``error_type`` +- ``error_value`` +- ``fqdn`` +- ``func_doc`` +- ``func_module`` +- ``time_epoch`` +- ``time_string`` +- ``traceback_string`` + +Use ``bg_helper.SimpleBackgroundTask`` when you need to start a +long-running Python function, or system command (like ``vlc`` media +player) in the background. + +:: + + % ipython + ... + + In [1]: import bg_helper as bh + + In [2]: def lame(): + ...: return 1/0 + + In [3]: def blah(*args, **kwargs): + ...: return locals() + + In [4]: bh.call_func(blah) + Out[4]: + {'args': '()', + 'func_name': 'blah', + 'kwargs': '{}', + 'status': 'ok', + 'value': {'args': (), 'kwargs': {}}} + + In [5]: bh.call_func(blah, 'cats', 'dogs') + Out[5]: + {'args': "('cats', 'dogs')", + 'func_name': 'blah', + 'kwargs': '{}', + 'status': 'ok', + 'value': {'args': ('cats', 'dogs'), 'kwargs': {}}} + + In [6]: bh.call_func(blah, 'cats', 'dogs', meh=[1, 2, 3, 4, 5]) + Out[6]: + {'args': "('cats', 'dogs')", + 'func_name': 'blah', + 'kwargs': "{'meh': [1, 2, 3, 4, 5]}", + 'status': 'ok', + 'value': {'args': ('cats', 'dogs'), 'kwargs': {'meh': [1, 2, 3, 4, 5]}}} + + In [7]: bh.call_func(lame) + ====================================================================== + 2017-04-01 12:32:35,107: func=lame args=() kwargs={} + Traceback (most recent call last): + File "/tmp/here/venv/lib/python3.5/site-packages/bg_helper/__init__.py", line 70, in call_func + value = func(*args, **kwargs) + File "", line 2, in lame + return 1/0 + ZeroDivisionError: division by zero + + Out[7]: + {'args': '()', + 'error_type': "", + 'error_value': "ZeroDivisionError('division by zero',)", + 'fqdn': 'x200-purple', + 'func_doc': None, + 'func_module': '__main__', + 'func_name': 'lame', + 'kwargs': '{}', + 'status': 'error', + 'time_epoch': 1491067955.1004958, + 'time_string': '2017_0401-Sat-123235', + 'traceback_string': 'Traceback (most recent call last):\n File "/tmp/here/venv/lib/python3.5/site-packages/bg_helper/__init__.py", line 70, in call_func\n value = func(*args, **kwargs)\n File "", line 2, in lame\n return 1/0\nZeroDivisionError: division by zero\n'} + + In [8]: cat log--bg-helper.log + 2017-04-01 12:32:35,107 - ERROR - call_func: func=lame args=() kwargs={} + Traceback (most recent call last): + File "/tmp/here/venv/lib/python3.5/site-packages/bg_helper/__init__.py", line 70, in call_func + value = func(*args, **kwargs) + File "", line 2, in lame + return 1/0 + ZeroDivisionError: division by zero + + In [9]: bh.SimpleBackgroundTask('echo "hello from console" > /tmp/blahblah.txt') + Out[9]: + + In [10]: ls /tmp/blahblah.txt + /tmp/blahblah.txt + + In [11]: cat /tmp/blahblah.txt + hello from console + + In [12]: bh.SimpleBackgroundTask('echo "$(date)" >> /tmp/blahblah.txt') + Out[12]: + + In [13]: cat /tmp/blahblah.txt + hello from console + Sat Apr 1 12:33:23 CDT 2017 diff --git a/bg_helper/__init__.py b/bg_helper/__init__.py index 24f2883..8fafbba 100644 --- a/bg_helper/__init__.py +++ b/bg_helper/__init__.py @@ -105,10 +105,14 @@ def call_func(func, *args, **kwargs): class SimpleBackgroundTask(object): - """Run a single command in a background thread + """Run a single command in a background thread and log any exceptions - Just initialize with the function and any args/kwargs. The background - thread is started right away and any exceptions raised will be logged + You can pass a callable object, or a string representing a shell command + + - if passing a callable, you may also pass in the args and kwargs + - since the callable will be executed by the `call_func` function, + the `logger` and `verbose` keyword arguments (if passed in) will be + used by `call_func` """ def __init__(self, func, *args, **kwargs): """ diff --git a/setup.py b/setup.py index 57fc307..4905e6d 100644 --- a/setup.py +++ b/setup.py @@ -1,10 +1,14 @@ from setuptools import setup, find_packages +with open('README.rst', 'r') as fp: + long_description = fp.read() + setup( name='bg-helper', version='0.1.1', description='Common CLI background helpers', + long_description=long_description, author='Ken', author_email='kenjyco@gmail.com', license='MIT',