Install
-------
::
% pip3 install bg-helper
Usage
-----
``import bg_helper as bh``
Helper functions in ``bg_helper`` that can be used to:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- run shell commands in a variety of ways
::
run(cmd, stderr_to_stdout=False, debug=False, timeout=None, exception=False, show=False)
Run a shell command and return the exit status
- cmd: string with shell command
- stderr_to_stdout: if True, redirect stderr to stdout
- debug: if True, insert breakpoint right before subprocess.call
- timeout: number of seconds to wait before stopping cmd
- exception: if True, raise Exception if non-zero exit status or TimeoutExpired
- show: if True, show the command before executing
run_output(cmd, strip=True, debug=False, timeout=None, exception=False, show=False)
Run a shell command and return output or error
- cmd: string with shell command
- strip: if True, strip trailing and leading whitespace from output
- debug: if True, insert breakpoint right before subprocess.call
- timeout: number of seconds to wait before stopping cmd
- exception: if True, raise Exception if non-zero exit status or TimeoutExpired
- show: if True, show the command before executing
run_or_die(cmd, stderr_to_stdout=False, debug=False, timeout=None, exception=False, show=False)
Run a shell command; if non-success, raise Exception or exit the system
- cmd: string with shell command
- stderr_to_stdout: if True, redirect stderr to stdout
- debug: if True, insert breakpoint right before subprocess.call
- timeout: number of seconds to wait before stopping cmd
- exception: if True, raise Exception if non-zero exit status or TimeoutExpired
- show: if True, show the command before executing
- call a Python function & capture the value or any uncaught exceptions
::
call_func(func, *args, **kwargs)
Call a func with arbitrary args/kwargs and capture uncaught exceptions
The following kwargs will be popped and used internally:
- logger: logger object to use
- verbose: if True (default), print line separator & tracebacks when caught
The returned dict will always have at least the following keys:
- `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`
- start a long-running shell command or Python function in the
background (like ``vlc`` media player)
::
SimpleBackgroundTask(func, *args, **kwargs)
Run a single command in a background thread and log any exceptions
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`
Helper functions in ``bg_helper.tools``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
git
^^^
- ``ctx_repo_path_root``
- ``git_repo_path_root``
- ``git_clone``
- ``git_fetch``
- ``git_origin_url``
- ``git_do``
- ``git_current_branch``
- ``git_current_tracking_branch``
- ``git_last_tag``
- ``git_tag_message``
- ``git_last_tag_message``
- ``git_tags``
- ``git_first_commit_id``
- ``git_last_commit_id``
- ``git_commits_since_last_tag``
- ``git_unpushed_commits``
- ``git_untracked_files``
- ``git_stashlist``
- ``git_status``
- ``git_info_dict``
- ``git_info_string``
- ``git_branch_date``
- ``git_remote_branches``
- ``git_local_branches``
- ``git_remote_branches_merged_with``
- ``git_local_branches_merged_with``
grep
^^^^
- ``grep_output``
pip
^^^
- ``pip_freeze``
- ``pip_install_editable``
ps
^^
- ``ps_output``
ssh
^^^
- ``ssh_to_server``
- ``ssh_pem_files``
- ``ssh_private_key_files``
- ``ssh_configured_hosts``
- ``ssh_determine_aws_user_for_server``
docker
^^^^^^
- ``docker_ok``
- ``docker_stop``
- ``docker_start_or_run``
- ``docker_container_id``
- ``docker_container_inspect``
- ``docker_container_config``
- ``docker_container_env_vars``
- ``docker_logs``
- ``docker_exec``
- ``docker_exec_wait``
- ``docker_shell``
- ``docker_cleanup_volumes``
- ``docker_redis_start``
- ``docker_redis_cli``
- ``docker_mongo_start``
- ``docker_mongo_cli``
- ``docker_postgres_start``
- ``docker_postgres_cli``
- ``docker_postgres_wait``
- ``docker_mysql_start``
- ``docker_mysql_cli``
- ``docker_mysql_wait``
- ``docker_alpine_start``
- ``docker_ubuntu_start``
- ``docker_fedora_start``
Examples
--------
::
% 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 "<ipython-input-2-ac0fa5de647a>", line 2, in lame
return 1/0
ZeroDivisionError: division by zero
Out[7]:
{'args': '()',
'error_type': "<class 'ZeroDivisionError'>",
'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 "<ipython-input-2-ac0fa5de647a>", 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 "<ipython-input-2-ac0fa5de647a>", line 2, in lame
return 1/0
ZeroDivisionError: division by zero
In [9]: bh.SimpleBackgroundTask('echo "hello from console" > /tmp/blahblah.txt')
Out[9]: <bg_helper.SimpleBackgroundTask at 0x7ff112229c18>
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]: <bg_helper.SimpleBackgroundTask at 0x7ff110057cf8>
In [13]: cat /tmp/blahblah.txt
hello from console
Sat Apr 1 12:33:23 CDT 2017
Raw data
{
"_id": null,
"home_page": "https://github.com/kenjyco/bg-helper",
"name": "bg-helper",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "background,shell,git,ssh,docker,redis,mongodb,postgres,postgresql,mysql,helper,kenjyco",
"author": "Ken",
"author_email": "kenjyco@gmail.com",
"download_url": "https://github.com/kenjyco/bg-helper/tarball/v0.1.19",
"platform": null,
"description": "Install\n-------\n\n::\n\n % pip3 install bg-helper\n\nUsage\n-----\n\n ``import bg_helper as bh``\n\nHelper functions in ``bg_helper`` that can be used to:\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- run shell commands in a variety of ways\n\n ::\n\n run(cmd, stderr_to_stdout=False, debug=False, timeout=None, exception=False, show=False)\n Run a shell command and return the exit status\n\n - cmd: string with shell command\n - stderr_to_stdout: if True, redirect stderr to stdout\n - debug: if True, insert breakpoint right before subprocess.call\n - timeout: number of seconds to wait before stopping cmd\n - exception: if True, raise Exception if non-zero exit status or TimeoutExpired\n - show: if True, show the command before executing\n\n run_output(cmd, strip=True, debug=False, timeout=None, exception=False, show=False)\n Run a shell command and return output or error\n\n - cmd: string with shell command\n - strip: if True, strip trailing and leading whitespace from output\n - debug: if True, insert breakpoint right before subprocess.call\n - timeout: number of seconds to wait before stopping cmd\n - exception: if True, raise Exception if non-zero exit status or TimeoutExpired\n - show: if True, show the command before executing\n\n run_or_die(cmd, stderr_to_stdout=False, debug=False, timeout=None, exception=False, show=False)\n Run a shell command; if non-success, raise Exception or exit the system\n\n - cmd: string with shell command\n - stderr_to_stdout: if True, redirect stderr to stdout\n - debug: if True, insert breakpoint right before subprocess.call\n - timeout: number of seconds to wait before stopping cmd\n - exception: if True, raise Exception if non-zero exit status or TimeoutExpired\n - show: if True, show the command before executing\n\n- call a Python function & capture the value or any uncaught exceptions\n\n ::\n\n call_func(func, *args, **kwargs)\n Call a func with arbitrary args/kwargs and capture uncaught exceptions\n\n The following kwargs will be popped and used internally:\n\n - logger: logger object to use\n - verbose: if True (default), print line separator & tracebacks when caught\n\n The returned dict will always have at least the following keys:\n\n - `func_name`\n - `args`\n - `kwargs`\n - `status` (ok/error)\n\n If the function call was successful, there will also be a `value` key. If\n there was an uncaught exception, the following additional keys will be\n provided in the return dict\n\n - `error_type`\n - `error_value`\n - `fqdn`\n - `func_doc`\n - `func_module`\n - `time_epoch`\n - `time_string`\n - `traceback_string`\n\n- start a long-running shell command or Python function in the\n background (like ``vlc`` media player)\n\n ::\n\n SimpleBackgroundTask(func, *args, **kwargs)\n Run a single command in a background thread and log any exceptions\n\n You can pass a callable object, or a string representing a shell command\n\n - if passing a callable, you may also pass in the args and kwargs\n - since the callable will be executed by the `call_func` function,\n the `logger` and `verbose` keyword arguments (if passed in) will be\n used by `call_func`\n\nHelper functions in ``bg_helper.tools``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\ngit\n^^^\n\n- ``ctx_repo_path_root``\n- ``git_repo_path_root``\n- ``git_clone``\n- ``git_fetch``\n- ``git_origin_url``\n- ``git_do``\n- ``git_current_branch``\n- ``git_current_tracking_branch``\n- ``git_last_tag``\n- ``git_tag_message``\n- ``git_last_tag_message``\n- ``git_tags``\n- ``git_first_commit_id``\n- ``git_last_commit_id``\n- ``git_commits_since_last_tag``\n- ``git_unpushed_commits``\n- ``git_untracked_files``\n- ``git_stashlist``\n- ``git_status``\n- ``git_info_dict``\n- ``git_info_string``\n- ``git_branch_date``\n- ``git_remote_branches``\n- ``git_local_branches``\n- ``git_remote_branches_merged_with``\n- ``git_local_branches_merged_with``\n\ngrep\n^^^^\n\n- ``grep_output``\n\npip\n^^^\n\n- ``pip_freeze``\n- ``pip_install_editable``\n\nps\n^^\n\n- ``ps_output``\n\nssh\n^^^\n\n- ``ssh_to_server``\n- ``ssh_pem_files``\n- ``ssh_private_key_files``\n- ``ssh_configured_hosts``\n- ``ssh_determine_aws_user_for_server``\n\ndocker\n^^^^^^\n\n- ``docker_ok``\n- ``docker_stop``\n- ``docker_start_or_run``\n- ``docker_container_id``\n- ``docker_container_inspect``\n- ``docker_container_config``\n- ``docker_container_env_vars``\n- ``docker_logs``\n- ``docker_exec``\n- ``docker_exec_wait``\n- ``docker_shell``\n- ``docker_cleanup_volumes``\n- ``docker_redis_start``\n- ``docker_redis_cli``\n- ``docker_mongo_start``\n- ``docker_mongo_cli``\n- ``docker_postgres_start``\n- ``docker_postgres_cli``\n- ``docker_postgres_wait``\n- ``docker_mysql_start``\n- ``docker_mysql_cli``\n- ``docker_mysql_wait``\n- ``docker_alpine_start``\n- ``docker_ubuntu_start``\n- ``docker_fedora_start``\n\nExamples\n--------\n\n::\n\n % ipython\n ...\n\n In [1]: import bg_helper as bh\n\n In [2]: def lame():\n ...: return 1/0\n\n In [3]: def blah(*args, **kwargs):\n ...: return locals()\n\n In [4]: bh.call_func(blah)\n Out[4]: \n {'args': '()',\n 'func_name': 'blah',\n 'kwargs': '{}',\n 'status': 'ok',\n 'value': {'args': (), 'kwargs': {}}}\n\n In [5]: bh.call_func(blah, 'cats', 'dogs')\n Out[5]: \n {'args': \"('cats', 'dogs')\",\n 'func_name': 'blah',\n 'kwargs': '{}',\n 'status': 'ok',\n 'value': {'args': ('cats', 'dogs'), 'kwargs': {}}}\n\n In [6]: bh.call_func(blah, 'cats', 'dogs', meh=[1, 2, 3, 4, 5])\n Out[6]: \n {'args': \"('cats', 'dogs')\",\n 'func_name': 'blah',\n 'kwargs': \"{'meh': [1, 2, 3, 4, 5]}\",\n 'status': 'ok',\n 'value': {'args': ('cats', 'dogs'), 'kwargs': {'meh': [1, 2, 3, 4, 5]}}}\n\n In [7]: bh.call_func(lame)\n ======================================================================\n 2017-04-01 12:32:35,107: func=lame args=() kwargs={}\n 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 \"<ipython-input-2-ac0fa5de647a>\", line 2, in lame\n return 1/0\n ZeroDivisionError: division by zero\n\n Out[7]: \n {'args': '()',\n 'error_type': \"<class 'ZeroDivisionError'>\",\n 'error_value': \"ZeroDivisionError('division by zero',)\",\n 'fqdn': 'x200-purple',\n 'func_doc': None,\n 'func_module': '__main__',\n 'func_name': 'lame',\n 'kwargs': '{}',\n 'status': 'error',\n 'time_epoch': 1491067955.1004958,\n 'time_string': '2017_0401-Sat-123235',\n '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 \"<ipython-input-2-ac0fa5de647a>\", line 2, in lame\\n return 1/0\\nZeroDivisionError: division by zero\\n'}\n\n In [8]: cat log--bg-helper.log\n 2017-04-01 12:32:35,107 - ERROR - call_func: func=lame args=() kwargs={}\n 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 \"<ipython-input-2-ac0fa5de647a>\", line 2, in lame\n return 1/0\n ZeroDivisionError: division by zero\n\n In [9]: bh.SimpleBackgroundTask('echo \"hello from console\" > /tmp/blahblah.txt')\n Out[9]: <bg_helper.SimpleBackgroundTask at 0x7ff112229c18>\n\n In [10]: ls /tmp/blahblah.txt\n /tmp/blahblah.txt\n\n In [11]: cat /tmp/blahblah.txt\n hello from console\n\n In [12]: bh.SimpleBackgroundTask('echo \"$(date)\" >> /tmp/blahblah.txt')\n Out[12]: <bg_helper.SimpleBackgroundTask at 0x7ff110057cf8>\n\n In [13]: cat /tmp/blahblah.txt\n hello from console\n Sat Apr 1 12:33:23 CDT 2017\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI helpers for background tasks (shell), docker (databases), git, and SSH",
"version": "0.1.19",
"project_urls": {
"Download": "https://github.com/kenjyco/bg-helper/tarball/v0.1.19",
"Homepage": "https://github.com/kenjyco/bg-helper"
},
"split_keywords": [
"background",
"shell",
"git",
"ssh",
"docker",
"redis",
"mongodb",
"postgres",
"postgresql",
"mysql",
"helper",
"kenjyco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62d6b1d9a07eab650b37e1585fee1e6621a379258404b7a0e5d27778f5a407d6",
"md5": "96340fa35841aa27ef5f0ceb7b221689",
"sha256": "d2d4fabb9099f331baea46911a65efe60e25bbc5a0fc3e414b77672b6b250bd7"
},
"downloads": -1,
"filename": "bg_helper-0.1.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96340fa35841aa27ef5f0ceb7b221689",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23808,
"upload_time": "2023-07-10T05:11:41",
"upload_time_iso_8601": "2023-07-10T05:11:41.948049Z",
"url": "https://files.pythonhosted.org/packages/62/d6/b1d9a07eab650b37e1585fee1e6621a379258404b7a0e5d27778f5a407d6/bg_helper-0.1.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-10 05:11:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenjyco",
"github_project": "bg-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "fs-helper",
"specs": []
},
{
"name": "importlib-metadata",
"specs": []
},
{
"name": "input-helper",
"specs": []
}
],
"lcname": "bg-helper"
}
JSON
