<p align="center">
<img src="https://github.com/Apakottur/shpyx/blob/main/shpyx.png?raw=true" />
</p>
[](https://pypi.org/project/shpyx/)
[](https://pypi.org/project/shpyx/)
[](https://pypi.org/project/shpyx/)
**shpyx** is a simple, lightweight and typed library for running shell commands in Python.
Use `shpyx.run` to run a shell command in a subprocess:
```python
>>> import shpyx
>>> shpyx.run("echo 1")
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
>>> shpyx.run("echo 1").return_code
0
>>> shpyx.run("echo 1").stdout
'1\n'
>>> shpyx.run("echo 1").stderr
''
```
## Installation
Install with `pip`:
```shell
pip install shpyx
```
## How Tos
### Run a command
In string format:
```python
>>> shpyx.run("echo 1")
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
```
In list format:
```python
>>> shpyx.run(["echo", ["1"])
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
```
### Run a command and print live output
```python
>>> shpyx.run("echo 1", log_output=True)
1
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
```
### Run a command with shell specific logic
When the argument to `run` is a string, an actual shell is created in the subprocess and shell logic can be used.
For example, the pipe operator can be used in bash/sh:
```python
>>> shpyx.run("seq 1 5 | grep '2'")
ShellCmdResult(cmd="seq 1 5 | grep '2'", stdout='2\n', stderr='', all_output='2\n', return_code=0)
```
### Create a custom runner
Use a custom runner to override the execution defaults, and not have to pass them to every call.
For example, we can change the default value of `log_cmd`, so that all commands are logged:
```python
>>> shpyx.run("echo 1")
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
>>> shpyx.run("echo 1", log_cmd=True)
Running: echo 1
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
>>> runner = shpyx.Runner(log_cmd=True)
>>> runner.run("echo 1")
Running: echo 1
ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0)
```
### Propagating terminal control sequences
Note: as of now this is only supported for Unix environments.
Some commands, like `psql`, might output special characters used for terminal management like cursor movement and
colors. For example, the `psql` command is used to start an interactive shell against a Postgres DB:
```python
shpyx.run(f"psql -h {host} -p {port} -U {user} -d {database}", log_output=True)
```
However, the above call will not work as good as running `psql` directly, due to terminal control sequences not being
properly propagated. To make it work well, we need to use the [script](https://man7.org/linux/man-pages/man1/script.1.html)
utility which will properly propagate all control sequences:
```python
# Linux:
shpyx.run(f"script -q -c 'psql -h {host} -p {port} -U {user} -d {database}'", log_output=True)
# MacOS:
shpyx.run(f"script -q psql -h {host} -p {port} -U {user} -d {database}", log_output=True)
```
shpyx provides a keyword argument that does this wrapping automatically, `unix_raw`:
```python
shpyx.run(f"psql -h {host} -p {port} -U {user} -d {database}", log_output=True, unix_raw=True)
```
The flag is disabled by default, and should only be used for interactive commands like `psql`.
## API Reference
The following arguments are supported by `Runner`:
| Name | Description | Default |
| -------------------- | -------------------------------------------------------------------------- | ------- |
| `log_cmd` | Log the executed command. | `False` |
| `log_output` | Log the live output of the command (while it is being executed). | `False` |
| `verify_return_code` | Raise an exception if the shell return code of the command is not `0`. | `True` |
| `verify_stderr` | Raise an exception if anything was written to stderr during the execution. | `False` |
| `use_signal_names` | Log the name of the signal corresponding to a non-zero error code. | `True` |
The following arguments are supported by `run`:
| Name | Description | Default |
| -------------------- | -------------------------------------------------------------------------- | ------------------------ |
| `log_cmd` | Log the executed command. | `Runner default` |
| `log_output` | Log the live output of the command (while it is being executed). | `Runner default` |
| `verify_return_code` | Raise an exception if the shell return code of the command is not `0`. | `Runner default` |
| `verify_stderr` | Raise an exception if anything was written to stderr during the execution. | `Runner default` |
| `use_signal_names` | Log the name of the signal corresponding to a non-zero error code. | `Runner default` |
| `env` | Environment variables to set during the execution of the command. | `Same as parent process` |
| `exec_dir` | Custom path to execute the command in (defaults to current directory). | `Same as parent process` |
| `unix_raw` | (UNIX ONLY) Whether to use the `script` Unix utility to run the command. | `False` |
## Implementation details
`shpyx` is a wrapper around the excellent [subprocess](https://docs.python.org/3/library/subprocess.html) module, aiming
to concentrate all the different API functions (`Popen`/`communicate`/`poll`/`wait`) into a single function - `shpyx.run`.
While the core API logic is fully supported on both Unix and Windows systems, there is some OS specific code for minor quality-of-life
improvements.
For example, on non Windows systems, [fcntl](https://docs.python.org/3/library/fcntl.html) is used to configure the subprocess to
always be incorruptible (which means one can CTRL-C out of any command).
## Security
The call to `subprocess.Popen` uses `shell=True` when the input to `run` is a string (to support shell logic like bash piping).
This means that an actual system shell is being created, and the subprocess has the permissions of the main Python process.
It is therefore recommended not pass any untrusted input to `shpyx.run`.
For more info, see [security considerations](https://docs.python.org/3/library/subprocess.html#security-considerations).
## Useful links
Relevant Python libraries:
- [subprocess](https://docs.python.org/3/library/subprocess.html)
- [shlex](https://docs.python.org/3/library/shlex.html)
Other 3rd-party libraries for running shell commands in Python:
- [sarge](https://github.com/vsajip/sarge)
- [sh](https://github.com/amoffat/sh)
- [invoke](https://github.com/pyinvoke/invoke)
## Contributing
To contribute simply open a PR with your changes.
Tests, linters and type checks are run in CI through GitHub Actions.
### Running checks locally
To run checks locally, start by installing all the development dependencies:
```shell
poetry install
```
To run the linters use `pre-commit`:
```shell
pre-commit run -a
```
To run the unit tests use `pytest`:
```shell
pytest -c tests/pytest.ini tests
```
To run type checks use `mypy`:
```shell
mypy --config-file shpyx/mypy.toml shpyx tests
```
To trigger a deployment of a new version upon merge, bump the version number in `pyproject.toml`.
Raw data
{
"_id": null,
"home_page": "https://github.com/Apakottur/shpyx",
"name": "shpyx",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "shell, bash, terminal, script",
"author": "Yossi Rozantsev",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9a/92/70e73a9dc6afa3dbb4e609ff22eb4e8be60a43642b8c64ee9e5554fbde62/shpyx-0.0.30.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://github.com/Apakottur/shpyx/blob/main/shpyx.png?raw=true\" />\n</p>\n\n[](https://pypi.org/project/shpyx/)\n[](https://pypi.org/project/shpyx/)\n[](https://pypi.org/project/shpyx/)\n\n**shpyx** is a simple, lightweight and typed library for running shell commands in Python.\n\nUse `shpyx.run` to run a shell command in a subprocess:\n\n```python\n>>> import shpyx\n>>> shpyx.run(\"echo 1\")\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n>>> shpyx.run(\"echo 1\").return_code\n0\n>>> shpyx.run(\"echo 1\").stdout\n'1\\n'\n>>> shpyx.run(\"echo 1\").stderr\n''\n```\n\n## Installation\n\nInstall with `pip`:\n\n```shell\npip install shpyx\n```\n\n## How Tos\n\n### Run a command\n\nIn string format:\n\n```python\n>>> shpyx.run(\"echo 1\")\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n```\n\nIn list format:\n\n```python\n>>> shpyx.run([\"echo\", [\"1\"])\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n```\n\n### Run a command and print live output\n\n```python\n>>> shpyx.run(\"echo 1\", log_output=True)\n1\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n```\n\n### Run a command with shell specific logic\n\nWhen the argument to `run` is a string, an actual shell is created in the subprocess and shell logic can be used.\nFor example, the pipe operator can be used in bash/sh:\n\n```python\n>>> shpyx.run(\"seq 1 5 | grep '2'\")\nShellCmdResult(cmd=\"seq 1 5 | grep '2'\", stdout='2\\n', stderr='', all_output='2\\n', return_code=0)\n```\n\n### Create a custom runner\n\nUse a custom runner to override the execution defaults, and not have to pass them to every call.\n\nFor example, we can change the default value of `log_cmd`, so that all commands are logged:\n\n```python\n>>> shpyx.run(\"echo 1\")\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n\n>>> shpyx.run(\"echo 1\", log_cmd=True)\nRunning: echo 1\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n\n>>> runner = shpyx.Runner(log_cmd=True)\n>>> runner.run(\"echo 1\")\nRunning: echo 1\nShellCmdResult(cmd='echo 1', stdout='1\\n', stderr='', all_output='1\\n', return_code=0)\n```\n\n### Propagating terminal control sequences\n\nNote: as of now this is only supported for Unix environments.\n\nSome commands, like `psql`, might output special characters used for terminal management like cursor movement and\ncolors. For example, the `psql` command is used to start an interactive shell against a Postgres DB:\n\n```python\nshpyx.run(f\"psql -h {host} -p {port} -U {user} -d {database}\", log_output=True)\n```\n\nHowever, the above call will not work as good as running `psql` directly, due to terminal control sequences not being\nproperly propagated. To make it work well, we need to use the [script](https://man7.org/linux/man-pages/man1/script.1.html)\nutility which will properly propagate all control sequences:\n\n```python\n# Linux:\nshpyx.run(f\"script -q -c 'psql -h {host} -p {port} -U {user} -d {database}'\", log_output=True)\n# MacOS:\nshpyx.run(f\"script -q psql -h {host} -p {port} -U {user} -d {database}\", log_output=True)\n\n```\n\nshpyx provides a keyword argument that does this wrapping automatically, `unix_raw`:\n\n```python\nshpyx.run(f\"psql -h {host} -p {port} -U {user} -d {database}\", log_output=True, unix_raw=True)\n```\n\nThe flag is disabled by default, and should only be used for interactive commands like `psql`.\n\n## API Reference\n\nThe following arguments are supported by `Runner`:\n\n| Name | Description | Default |\n| -------------------- | -------------------------------------------------------------------------- | ------- |\n| `log_cmd` | Log the executed command. | `False` |\n| `log_output` | Log the live output of the command (while it is being executed). | `False` |\n| `verify_return_code` | Raise an exception if the shell return code of the command is not `0`. | `True` |\n| `verify_stderr` | Raise an exception if anything was written to stderr during the execution. | `False` |\n| `use_signal_names` | Log the name of the signal corresponding to a non-zero error code. | `True` |\n\nThe following arguments are supported by `run`:\n\n| Name | Description | Default |\n| -------------------- | -------------------------------------------------------------------------- | ------------------------ |\n| `log_cmd` | Log the executed command. | `Runner default` |\n| `log_output` | Log the live output of the command (while it is being executed). | `Runner default` |\n| `verify_return_code` | Raise an exception if the shell return code of the command is not `0`. | `Runner default` |\n| `verify_stderr` | Raise an exception if anything was written to stderr during the execution. | `Runner default` |\n| `use_signal_names` | Log the name of the signal corresponding to a non-zero error code. | `Runner default` |\n| `env` | Environment variables to set during the execution of the command. | `Same as parent process` |\n| `exec_dir` | Custom path to execute the command in (defaults to current directory). | `Same as parent process` |\n| `unix_raw` | (UNIX ONLY) Whether to use the `script` Unix utility to run the command. | `False` |\n\n## Implementation details\n\n`shpyx` is a wrapper around the excellent [subprocess](https://docs.python.org/3/library/subprocess.html) module, aiming\nto concentrate all the different API functions (`Popen`/`communicate`/`poll`/`wait`) into a single function - `shpyx.run`.\n\nWhile the core API logic is fully supported on both Unix and Windows systems, there is some OS specific code for minor quality-of-life\nimprovements.\nFor example, on non Windows systems, [fcntl](https://docs.python.org/3/library/fcntl.html) is used to configure the subprocess to\nalways be incorruptible (which means one can CTRL-C out of any command).\n\n## Security\n\nThe call to `subprocess.Popen` uses `shell=True` when the input to `run` is a string (to support shell logic like bash piping).\nThis means that an actual system shell is being created, and the subprocess has the permissions of the main Python process.\n\nIt is therefore recommended not pass any untrusted input to `shpyx.run`.\n\nFor more info, see [security considerations](https://docs.python.org/3/library/subprocess.html#security-considerations).\n\n## Useful links\n\nRelevant Python libraries:\n\n- [subprocess](https://docs.python.org/3/library/subprocess.html)\n- [shlex](https://docs.python.org/3/library/shlex.html)\n\nOther 3rd-party libraries for running shell commands in Python:\n\n- [sarge](https://github.com/vsajip/sarge)\n- [sh](https://github.com/amoffat/sh)\n- [invoke](https://github.com/pyinvoke/invoke)\n\n## Contributing\n\nTo contribute simply open a PR with your changes.\n\nTests, linters and type checks are run in CI through GitHub Actions.\n\n### Running checks locally\n\nTo run checks locally, start by installing all the development dependencies:\n\n```shell\npoetry install\n```\n\nTo run the linters use `pre-commit`:\n\n```shell\npre-commit run -a\n```\n\nTo run the unit tests use `pytest`:\n\n```shell\npytest -c tests/pytest.ini tests\n```\n\nTo run type checks use `mypy`:\n\n```shell\nmypy --config-file shpyx/mypy.toml shpyx tests\n```\n\nTo trigger a deployment of a new version upon merge, bump the version number in `pyproject.toml`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Run shell commands in Python",
"version": "0.0.30",
"project_urls": {
"Documentation": "https://github.com/Apakottur/shpyx",
"Homepage": "https://github.com/Apakottur/shpyx",
"Repository": "https://github.com/Apakottur/shpyx"
},
"split_keywords": [
"shell",
" bash",
" terminal",
" script"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3ce3f5cf1f6b5cdeb17a41de48956ae026031b12c3c21baf67ffc284776524d",
"md5": "fefaac31cac989578cc27134a842bceb",
"sha256": "77d192d6fa834fc4440d0961bf5a27f9df09f42d0afa210b7a11bba05e9c3c73"
},
"downloads": -1,
"filename": "shpyx-0.0.30-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fefaac31cac989578cc27134a842bceb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 10364,
"upload_time": "2024-09-30T12:40:59",
"upload_time_iso_8601": "2024-09-30T12:40:59.371784Z",
"url": "https://files.pythonhosted.org/packages/c3/ce/3f5cf1f6b5cdeb17a41de48956ae026031b12c3c21baf67ffc284776524d/shpyx-0.0.30-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9a9270e73a9dc6afa3dbb4e609ff22eb4e8be60a43642b8c64ee9e5554fbde62",
"md5": "5b26b7abc2d9c1cef3b005a4119c163e",
"sha256": "2e6b2d68b3726414433c5e771c869a4dce7888f1d92ed97f19aaf379dc5cfd8f"
},
"downloads": -1,
"filename": "shpyx-0.0.30.tar.gz",
"has_sig": false,
"md5_digest": "5b26b7abc2d9c1cef3b005a4119c163e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 10466,
"upload_time": "2024-09-30T12:41:00",
"upload_time_iso_8601": "2024-09-30T12:41:00.616144Z",
"url": "https://files.pythonhosted.org/packages/9a/92/70e73a9dc6afa3dbb4e609ff22eb4e8be60a43642b8c64ee9e5554fbde62/shpyx-0.0.30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 12:41:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Apakottur",
"github_project": "shpyx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shpyx"
}
JSON
