diff options
author | CoprDistGit <infra@openeuler.org> | 2023-06-20 09:59:27 +0000 |
---|---|---|
committer | CoprDistGit <infra@openeuler.org> | 2023-06-20 09:59:27 +0000 |
commit | 2ede31ef64ad21dc30ecf740869a7d598a48dfa8 (patch) | |
tree | 805334ef218c57c64cc1bbd3c87c50542a97e951 /python-shpyx.spec | |
parent | 97d9bd9a688f6f219cd7d69086c8de94d52114d4 (diff) |
automatic import of python-shpyxopeneuler20.03
Diffstat (limited to 'python-shpyx.spec')
-rw-r--r-- | python-shpyx.spec | 696 |
1 files changed, 696 insertions, 0 deletions
diff --git a/python-shpyx.spec b/python-shpyx.spec new file mode 100644 index 0000000..f562f76 --- /dev/null +++ b/python-shpyx.spec @@ -0,0 +1,696 @@ +%global _empty_manifest_terminate_build 0 +Name: python-shpyx +Version: 0.0.25 +Release: 1 +Summary: Run shell commands in Python +License: MIT +URL: https://github.com/Apakottur/shpyx +Source0: https://mirrors.aliyun.com/pypi/web/packages/bc/7b/c888aa06e6229929733deb346c166ba0da53182f26279dc9ae96532fb65e/shpyx-0.0.25.tar.gz +BuildArch: noarch + + +%description +<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").return_code +0 +>>> shpyx.run("echo 1").stdout +'1\n' +>>> shpyx.run("echo 1").stderr +'' +>>> shpyx.run("echo 1") +ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0) +``` + +## 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 user libraries for running shell commands in Python: + +- [sarge](https://github.com/vsajip/sarge) +- [sh](https://github.com/amoffat/sh) + +## 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.ini shpyx tests +``` + +To trigger a deployment of a new version upon merge, bump the version number in `pyproject.toml`. + + +%package -n python3-shpyx +Summary: Run shell commands in Python +Provides: python-shpyx +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-shpyx +<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").return_code +0 +>>> shpyx.run("echo 1").stdout +'1\n' +>>> shpyx.run("echo 1").stderr +'' +>>> shpyx.run("echo 1") +ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0) +``` + +## 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 user libraries for running shell commands in Python: + +- [sarge](https://github.com/vsajip/sarge) +- [sh](https://github.com/amoffat/sh) + +## 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.ini shpyx tests +``` + +To trigger a deployment of a new version upon merge, bump the version number in `pyproject.toml`. + + +%package help +Summary: Development documents and examples for shpyx +Provides: python3-shpyx-doc +%description help +<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").return_code +0 +>>> shpyx.run("echo 1").stdout +'1\n' +>>> shpyx.run("echo 1").stderr +'' +>>> shpyx.run("echo 1") +ShellCmdResult(cmd='echo 1', stdout='1\n', stderr='', all_output='1\n', return_code=0) +``` + +## 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 user libraries for running shell commands in Python: + +- [sarge](https://github.com/vsajip/sarge) +- [sh](https://github.com/amoffat/sh) + +## 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.ini shpyx tests +``` + +To trigger a deployment of a new version upon merge, bump the version number in `pyproject.toml`. + + +%prep +%autosetup -n shpyx-0.0.25 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-shpyx -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Tue Jun 20 2023 Python_Bot <Python_Bot@openeuler.org> - 0.0.25-1 +- Package Spec generated |