.. contents:: **subprocrunner**
:backlinks: top
:depth: 2
Summary
=============
A Python wrapper library for ``subprocess`` module.
|PyPI pkg ver| |Supported Python versions| |Supported Python implementations| |CI status| |Test coverage| |CodeQL|
.. |PyPI pkg ver| image:: https://badge.fury.io/py/subprocrunner.svg
:target: https://badge.fury.io/py/subprocrunner
:alt: PyPI package version
.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/subprocrunner.svg
:target: https://pypi.org/project/subprocrunner
:alt: Supported Python versions
.. |Supported Python implementations| image:: https://img.shields.io/pypi/implementation/subprocrunner.svg
:target: https://pypi.org/project/subprocrunner
:alt: Supported Python implementations
.. |CI status| image:: https://github.com/thombashi/subprocrunner/actions/workflows/ci.yml/badge.svg
:target: https://github.com/thombashi/subprocrunner/actions/workflows/ci.yml
:alt: CI status of Linux/macOS/Windows
.. |Test coverage| image:: https://coveralls.io/repos/github/thombashi/subprocrunner/badge.svg?branch=master
:target: https://coveralls.io/github/thombashi/subprocrunner?branch=master
:alt: Test coverage
.. |CodeQL| image:: https://github.com/thombashi/subprocrunner/actions/workflows/github-code-scanning/codeql/badge.svg
:target: https://github.com/thombashi/subprocrunner/actions/workflows/github-code-scanning/codeql
:alt: CodeQL
Usage
========
Execute a command
----------------------------
:Sample Code:
.. code:: python
from subprocrunner import SubprocessRunner
runner = SubprocessRunner(["echo", "test"])
print(runner)
print(f"return code: {runner.run()}")
print(f"stdout: {runner.stdout}")
runner = SubprocessRunner(["ls", "__not_exist_dir__"])
print(runner)
print(f"return code: {runner.run()}")
print(f"stderr: {runner.stderr}")
:Output:
.. code::
SubprocessRunner(command='echo test', returncode='not yet executed')
return code: 0
stdout: test
SubprocessRunner(command='ls __not_exist_dir__', returncode='not yet executed')
return code: 2
stderr: ls: cannot access '__not_exist_dir__': No such file or directory
Execute a command with retries
--------------------------------------------------------
:Sample Code:
.. code:: python
from subprocrunner import Retry, SubprocessRunner
SubprocessRunner(command).run(retry=Retry(total=3, backoff_factor=0.2, jitter=0.2))
Raise an exception when a command execution failed
--------------------------------------------------------
:Sample Code:
.. code:: python
import sys
from subprocrunner import SubprocessRunner
from subprocrunner.error import CalledProcessError
runner = SubprocessRunner("ls not-exist-dir")
# raise an exception at run
try:
runner.run(check=True)
except CalledProcessError as e:
print(f"run(check=True): {e}\n{e.stderr}", file=sys.stderr)
# raise an exception after run
runner.run()
try:
runner.raise_for_returncode()
except CalledProcessError as e:
print(f"raise_for_returncode(): {e}\n{e.stderr}", file=sys.stderr)
:Output:
.. code::
run(check=True): Command 'ls not-exist-dir' returned non-zero exit status 2.
ls: cannot access 'not-exist-dir': No such file or directory
raise_for_returncode(): Command 'ls not-exist-dir' returned non-zero exit status 2.
ls: cannot access 'not-exist-dir': No such file or directory
dry run
----------------------------
Commands are not actually run when passing ``dry_run=True`` to ``SubprocessRunner`` class constructor.
:Sample Code:
.. code:: python
from subprocrunner import SubprocessRunner
runner = SubprocessRunner("echo test", dry_run=True)
print(runner)
print(f"return code: {runner.run()}")
print(f"stdout: {runner.stdout}")
:Output:
.. code::
SubprocessRunner(command='echo test', returncode='not yet executed', dryrun=True)
return code: 0
stdout:
Get execution command history
--------------------------------------------------------
:Sample Code:
.. code:: python
from subprocrunner import SubprocessRunner
SubprocessRunner.clear_history()
SubprocessRunner.is_save_history = True
SubprocessRunner(["echo", "hoge"]).run()
SubprocessRunner(["echo", "foo"]).run()
print("\n".join(SubprocessRunner.get_history()))
:Output:
.. code::
echo hoge
echo foo
Get a command information
----------------------------
.. code-block:: pycon
>>> from subprocrunner import Which
>>> which = Which("ls")
>>> which.is_exist()
True
>>> which.abspath()
'/usr/bin/ls'
>>> which
command=ls, is_exist=True, abspath=/usr/bin/ls
Installation
============
Install from PyPI
------------------------------
::
pip install subprocrunner
Install from PPA (for Ubuntu)
------------------------------
::
sudo add-apt-repository ppa:thombashi/ppa
sudo apt update
sudo apt install python3-subprocrunner
Dependencies
============
- Python 3.7+
- `Python package dependencies (automatically installed) <https://github.com/thombashi/subprocrunner/network/dependencies>`__
Optional dependencies
----------------------------------
- `loguru <https://github.com/Delgan/loguru>`__
- Used for logging if the package installed
Raw data
{
"_id": null,
"home_page": "https://github.com/thombashi/subprocrunner",
"name": "subprocrunner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "library, subprocess",
"author": "Tsuyoshi Hombashi",
"author_email": "tsuyoshi.hombashi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/57/a6/e3a704af7236df05f423fe8c6bc169b752ab0a2a9e266c27d608d3366152/subprocrunner-2.0.1.tar.gz",
"platform": null,
"description": ".. contents:: **subprocrunner**\n :backlinks: top\n :depth: 2\n\n\nSummary\n=============\nA Python wrapper library for ``subprocess`` module.\n\n|PyPI pkg ver| |Supported Python versions| |Supported Python implementations| |CI status| |Test coverage| |CodeQL|\n\n.. |PyPI pkg ver| image:: https://badge.fury.io/py/subprocrunner.svg\n :target: https://badge.fury.io/py/subprocrunner\n :alt: PyPI package version\n\n.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/subprocrunner.svg\n :target: https://pypi.org/project/subprocrunner\n :alt: Supported Python versions\n\n.. |Supported Python implementations| image:: https://img.shields.io/pypi/implementation/subprocrunner.svg\n :target: https://pypi.org/project/subprocrunner\n :alt: Supported Python implementations\n\n.. |CI status| image:: https://github.com/thombashi/subprocrunner/actions/workflows/ci.yml/badge.svg\n :target: https://github.com/thombashi/subprocrunner/actions/workflows/ci.yml\n :alt: CI status of Linux/macOS/Windows\n\n.. |Test coverage| image:: https://coveralls.io/repos/github/thombashi/subprocrunner/badge.svg?branch=master\n :target: https://coveralls.io/github/thombashi/subprocrunner?branch=master\n :alt: Test coverage\n\n.. |CodeQL| image:: https://github.com/thombashi/subprocrunner/actions/workflows/github-code-scanning/codeql/badge.svg\n :target: https://github.com/thombashi/subprocrunner/actions/workflows/github-code-scanning/codeql\n :alt: CodeQL\n\n\nUsage\n========\nExecute a command\n----------------------------\n:Sample Code:\n .. code:: python\n\n from subprocrunner import SubprocessRunner\n\n runner = SubprocessRunner([\"echo\", \"test\"])\n print(runner)\n print(f\"return code: {runner.run()}\")\n print(f\"stdout: {runner.stdout}\")\n \n runner = SubprocessRunner([\"ls\", \"__not_exist_dir__\"])\n print(runner)\n print(f\"return code: {runner.run()}\")\n print(f\"stderr: {runner.stderr}\")\n \n:Output:\n .. code::\n\n SubprocessRunner(command='echo test', returncode='not yet executed')\n return code: 0\n stdout: test\n \n SubprocessRunner(command='ls __not_exist_dir__', returncode='not yet executed')\n return code: 2\n stderr: ls: cannot access '__not_exist_dir__': No such file or directory\n\nExecute a command with retries\n--------------------------------------------------------\n\n:Sample Code:\n .. code:: python\n\n from subprocrunner import Retry, SubprocessRunner\n\n SubprocessRunner(command).run(retry=Retry(total=3, backoff_factor=0.2, jitter=0.2))\n\nRaise an exception when a command execution failed\n--------------------------------------------------------\n:Sample Code:\n .. code:: python\n\n import sys\n from subprocrunner import SubprocessRunner\n from subprocrunner.error import CalledProcessError\n\n runner = SubprocessRunner(\"ls not-exist-dir\")\n\n # raise an exception at run\n try:\n runner.run(check=True)\n except CalledProcessError as e:\n print(f\"run(check=True): {e}\\n{e.stderr}\", file=sys.stderr)\n\n\n # raise an exception after run\n runner.run()\n try:\n runner.raise_for_returncode()\n except CalledProcessError as e:\n print(f\"raise_for_returncode(): {e}\\n{e.stderr}\", file=sys.stderr)\n\n:Output:\n .. code::\n\n run(check=True): Command 'ls not-exist-dir' returned non-zero exit status 2.\n ls: cannot access 'not-exist-dir': No such file or directory\n\n raise_for_returncode(): Command 'ls not-exist-dir' returned non-zero exit status 2.\n ls: cannot access 'not-exist-dir': No such file or directory\n\ndry run\n----------------------------\nCommands are not actually run when passing ``dry_run=True`` to ``SubprocessRunner`` class constructor.\n\n:Sample Code:\n .. code:: python\n\n from subprocrunner import SubprocessRunner\n\n runner = SubprocessRunner(\"echo test\", dry_run=True)\n print(runner)\n print(f\"return code: {runner.run()}\")\n print(f\"stdout: {runner.stdout}\")\n \n:Output:\n .. code::\n\n SubprocessRunner(command='echo test', returncode='not yet executed', dryrun=True)\n return code: 0\n stdout: \n\nGet execution command history\n--------------------------------------------------------\n:Sample Code:\n .. code:: python\n\n from subprocrunner import SubprocessRunner\n\n SubprocessRunner.clear_history()\n SubprocessRunner.is_save_history = True\n \n SubprocessRunner([\"echo\", \"hoge\"]).run()\n SubprocessRunner([\"echo\", \"foo\"]).run()\n \n print(\"\\n\".join(SubprocessRunner.get_history()))\n\n:Output:\n .. code::\n\n echo hoge\n echo foo\n\nGet a command information\n----------------------------\n.. code-block:: pycon\n\n >>> from subprocrunner import Which\n >>> which = Which(\"ls\")\n >>> which.is_exist()\n True\n >>> which.abspath()\n '/usr/bin/ls'\n >>> which\n command=ls, is_exist=True, abspath=/usr/bin/ls\n\n\nInstallation\n============\n\nInstall from PyPI\n------------------------------\n::\n\n pip install subprocrunner\n\nInstall from PPA (for Ubuntu)\n------------------------------\n::\n\n sudo add-apt-repository ppa:thombashi/ppa\n sudo apt update\n sudo apt install python3-subprocrunner\n\n\nDependencies\n============\n- Python 3.7+\n- `Python package dependencies (automatically installed) <https://github.com/thombashi/subprocrunner/network/dependencies>`__\n\nOptional dependencies\n----------------------------------\n- `loguru <https://github.com/Delgan/loguru>`__\n - Used for logging if the package installed\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python wrapper library for subprocess module.",
"version": "2.0.1",
"project_urls": {
"Changlog": "https://github.com/thombashi/subprocrunner/releases",
"Homepage": "https://github.com/thombashi/subprocrunner",
"Source": "https://github.com/thombashi/subprocrunner",
"Tracker": "https://github.com/thombashi/subprocrunner/issues"
},
"split_keywords": [
"library",
" subprocess"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "26f2d8361d6b9ac84656122e01c2c0c677e2b64f94d799149020a4b1869b337e",
"md5": "64f8c0864b04a7869e24e91c20703b93",
"sha256": "778e1bcec011b3214d247bf65c42b26f3d3f0a25d12188def6b9574c6671e166"
},
"downloads": -1,
"filename": "subprocrunner-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64f8c0864b04a7869e24e91c20703b93",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11173,
"upload_time": "2024-04-06T16:03:17",
"upload_time_iso_8601": "2024-04-06T16:03:17.098442Z",
"url": "https://files.pythonhosted.org/packages/26/f2/d8361d6b9ac84656122e01c2c0c677e2b64f94d799149020a4b1869b337e/subprocrunner-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "57a6e3a704af7236df05f423fe8c6bc169b752ab0a2a9e266c27d608d3366152",
"md5": "092b8e0724d3d1f974a0922fed3d4195",
"sha256": "3723226a1bf6b51569fd8f82aa4f0588eef7adf129d16aac8b317555624e8f69"
},
"downloads": -1,
"filename": "subprocrunner-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "092b8e0724d3d1f974a0922fed3d4195",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15112,
"upload_time": "2024-04-06T16:03:19",
"upload_time_iso_8601": "2024-04-06T16:03:19.372861Z",
"url": "https://files.pythonhosted.org/packages/57/a6/e3a704af7236df05f423fe8c6bc169b752ab0a2a9e266c27d608d3366152/subprocrunner-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-06 16:03:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thombashi",
"github_project": "subprocrunner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "subprocrunner"
}
JSON
