| Name | jk_simpleexec JSON |
| Version |
0.2024.8.11
JSON |
| download |
| home_page | None |
| Summary | Python module to run command line programs in a convenient way and retrieve their output after they terminated. |
| upload_time | 2024-08-11 12:52:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
exec
shell
execute
popen
kill
spawn
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
jk_simpleexec
===============================
Introduction
--------------------------------
This python module provides a convenient interface to execute commands and catch their output. Additionally it provides convenient ways of running and killing other processes.
Information about this module can be found here:
* [github.org](https://github.com/jkpubsrc/python-module-jk-simpleexec)
* [pypi.python.org](https://pypi.python.org/pypi/jk_simpleexec)
How to use this module
--------------------------------
### Import
To import this module use the following statement:
```python
import jk_simpleexec
```
### Invoking a program: Example
Here is an example how to invoke a command:
```python
cmdResult = jk_simpleexec.invokeCmd1(
cmdPath = "/usr/bin/ls",
cmdArgs = [
"-la",
],
dataToPipeAsStdIn = None, # this is the default; listed here only for completeness;
workingDirectory = "/",
)
cmdResult.dump()
```
This will internally use Python's `subprocess.Popen(..)` to run the specified program and receive it's output.
The data returned by `invokeCmd(..)` is a data container for the result.
For simplicity a `cmdResult.dump()` is invoked here in order to write all received information to STDOUT.
(In a real world scenario you will likely want to process some of that data.)
NOTE: There exists an older version of `jk_simpleexec.invokeCmd1(..)` named `jk_simpleexec.invokeCmd(..)`. This `invokeCmd1(..)` was implemented as a step to
overcome limitations of the `invokeCmd(..)` API. In the future please use the more recent version `invokeCmd1(..)` instead of `invokeCmd(..)`.
Likely `invokeCmd(..)` will be removed in future versions.
API
--------------------------------
### The `invokeCmd1(..)` function
```python
#
# Synchroneously invokes the specified command on the local machine. Output of STDOUT and STDERR is collected and returned by the <c>CommandResult</c> return object.
#
# @param string cmdPath (required) The (absolute) path to the program to invoke.
# @param string[] cmdArgs (required) A list of arguments. Specify <c>None</c> if you do not want to have any arguments.
# Please note that there is no shell to interprete these commands.
# @param str|bytes[] dataToPipeAsStdIn (optional) Either a string or binary data (or None) that should be passed on to the application invoked usint STDIN.
# If string data is presented it is automatically encoded using UTF-8
# @param str workingDirectory (optional) If you specify a working directory here this function will change to this working directory
# specified in <c>workingDirector</c> and return to the previous one after the command has been completed.
# @param TextDataProcessingPolicy stdOutProcessing (optional) If specified you can override defaults of the STDOUT preprocessing that can already be done by this function.
# @param TextDataProcessingPolicy stdErrProcessing (optional) If specified you can override defaults of the STDERR preprocessing that can already be done by this function.
#
# @return CommandOutput Returns an object that contains the exit status, (preprocessed) STDOUT and (preprocessed) STDERR data.
#
def invokeCmd1(
cmdPath:str,
cmdArgs:list,
dataToPipeAsStdIn:typing.Union[str,bytes,bytearray] = None,
workingDirectory:str = None,
stdOutProcessing:TextDataProcessingPolicy = None,
stdErrProcessing:TextDataProcessingPolicy = None,
) -> CommandResult
```
### The `CommandResult` object returned
`CommandResult` objects are returned if commands have been executed successfully. Classes of that type will provide a set of properties and methods.
NOTE: I use signatures similiar to C-style here as this way the required types for arguments can be understood more easily.
#### Properties
* `str commandPath` : Returns the path used for invoking the command.
* `str commandArguments` : Returns the arguments used for invoking the command.
* `int returnCode` : The return code of the command after completion.
* `list stdOutLines` : The STDOUT output of the command as a list of text lines.
* `list stdErrLines` : The STDERR output of the command as a list of text lines.
* `str stdOutStr` : The STDOUT output of the command as a single string.
* `str stdErrStr` : The STDERR output of the command as a single string.
* `TextData stdOut` : Direct access to the internal `TextData` object that manages the STDOUT output.
* `TextData stdErr` : Direct access to the internal `TextData` object that manages the STDERR output.
* `bool isError` : Returns `True` if either the return code is non-zero or `STDERR` contains some data.
### Methods
* `void dump(str prefix = None, callable printFunc = None)` : Write debugging data to STDOUT (if `printFunc` is `None`, or use the specified callable as a replacement for `print(..)`).
* `dict getStdOutAsJSON()` : Interpret the text data as JSON data and return it.
* `ElementTree getStdOutAsXML()` : Interpret the text data as XML and return an ElemenTree object.
* `* getStdOutAsLXML()` : Interpret the text data as an LXML tree object and return it. (Requires `lxml` to be installed.)
* `void raiseExceptionOnError(exceptionMessage:str, bDumpStatusOnError:bool = False)` : If the return code is no-zero or <c>STDERR</c> contains data an exception is thrown using the specified exception message.
* `dict toJSON()` : Convert the whole object to a JSON dictionary.
Contact Information
--------------------------------
This is Open Source code. That not only gives you the possibility of freely using this code it also
allows you to contribute. Feel free to contact the author(s) of this software listed below, either
for comments, collaboration requests, suggestions for improvement or reporting bugs:
* Jürgen Knauth: pubsrc@binary-overflow.de
License
--------------------------------
This software is provided under the following license:
* Apache Software License 2.0
Raw data
{
"_id": null,
"home_page": null,
"name": "jk_simpleexec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "J\u00fcrgen Knauth <pubsrc@binary-overflow.de>",
"keywords": "exec, shell, execute, Popen, kill, spawn",
"author": null,
"author_email": "J\u00fcrgen Knauth <pubsrc@binary-overflow.de>",
"download_url": "https://files.pythonhosted.org/packages/35/3c/638d9b420055d4e7966929e84651b86b4d11a30cadd4406141a8c3960343/jk_simpleexec-0.2024.8.11.tar.gz",
"platform": null,
"description": "jk_simpleexec\n===============================\n\nIntroduction\n--------------------------------\n\nThis python module provides a convenient interface to execute commands and catch their output. Additionally it provides convenient ways of running and killing other processes.\n\nInformation about this module can be found here:\n\n* [github.org](https://github.com/jkpubsrc/python-module-jk-simpleexec)\n* [pypi.python.org](https://pypi.python.org/pypi/jk_simpleexec)\n\nHow to use this module\n--------------------------------\n\n### Import\n\nTo import this module use the following statement:\n\n```python\nimport jk_simpleexec\n```\n\n### Invoking a program: Example\n\nHere is an example how to invoke a command:\n\n```python\ncmdResult = jk_simpleexec.invokeCmd1(\n\tcmdPath = \"/usr/bin/ls\",\n\tcmdArgs = [\n\t\t\"-la\",\n\t],\n\tdataToPipeAsStdIn = None,\t\t# this is the default; listed here only for completeness;\n\tworkingDirectory = \"/\",\n)\n\ncmdResult.dump()\n```\n\nThis will internally use Python's `subprocess.Popen(..)` to run the specified program and receive it's output.\n\nThe data returned by `invokeCmd(..)` is a data container for the result.\nFor simplicity a `cmdResult.dump()` is invoked here in order to write all received information to STDOUT.\n(In a real world scenario you will likely want to process some of that data.)\n\nNOTE: There exists an older version of `jk_simpleexec.invokeCmd1(..)` named `jk_simpleexec.invokeCmd(..)`. This `invokeCmd1(..)` was implemented as a step to\novercome limitations of the `invokeCmd(..)` API. In the future please use the more recent version `invokeCmd1(..)` instead of `invokeCmd(..)`.\nLikely `invokeCmd(..)` will be removed in future versions.\n\nAPI\n--------------------------------\n\n### The `invokeCmd1(..)` function\n\n```python\n#\n# Synchroneously invokes the specified command on the local machine. Output of STDOUT and STDERR is collected and returned by the <c>CommandResult</c> return object.\n#\n# @param\t\tstring cmdPath\t\t\t\t\t\t\t\t(required) The (absolute) path to the program to invoke.\n# @param\t\tstring[] cmdArgs\t\t\t\t\t\t\t(required) A list of arguments. Specify <c>None</c> if you do not want to have any arguments.\n#\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tPlease note that there is no shell to interprete these commands.\n# @param\t\tstr|bytes[] dataToPipeAsStdIn\t\t\t\t(optional) Either a string or binary data (or None) that should be passed on to the application invoked usint STDIN.\n#\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tIf string data is presented it is automatically encoded using UTF-8\n# @param\t\tstr workingDirectory\t\t\t\t\t\t(optional) If you specify a working directory here this function will change to this working directory\n#\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tspecified in <c>workingDirector</c> and return to the previous one after the command has been completed.\n# @param\t\tTextDataProcessingPolicy stdOutProcessing\t(optional) If specified you can override defaults of the STDOUT preprocessing that can already be done by this function.\n# @param\t\tTextDataProcessingPolicy stdErrProcessing\t(optional) If specified you can override defaults of the STDERR preprocessing that can already be done by this function.\n#\n# @return\t\tCommandOutput\t\t\t\t\t\t\t\tReturns an object that contains the exit status, (preprocessed) STDOUT and (preprocessed) STDERR data.\n#\ndef invokeCmd1(\n\t\tcmdPath:str,\n\t\tcmdArgs:list,\n\t\tdataToPipeAsStdIn:typing.Union[str,bytes,bytearray] = None,\n\t\tworkingDirectory:str = None,\n\t\tstdOutProcessing:TextDataProcessingPolicy = None,\n\t\tstdErrProcessing:TextDataProcessingPolicy = None,\n\t) -> CommandResult\n```\n\n### The `CommandResult` object returned\n\n`CommandResult` objects are returned if commands have been executed successfully. Classes of that type will provide a set of properties and methods.\n\nNOTE: I use signatures similiar to C-style here as this way the required types for arguments can be understood more easily.\n\n#### Properties\n\n* `str commandPath` : Returns the path used for invoking the command.\n* `str commandArguments` : Returns the arguments used for invoking the command.\n* `int returnCode` : The return code of the command after completion.\n* `list stdOutLines` : The STDOUT output of the command as a list of text lines.\n* `list stdErrLines` : The STDERR output of the command as a list of text lines.\n* `str stdOutStr` : The STDOUT output of the command as a single string.\n* `str stdErrStr` : The STDERR output of the command as a single string.\n* `TextData stdOut` : Direct access to the internal `TextData` object that manages the STDOUT output.\n* `TextData stdErr` : Direct access to the internal `TextData` object that manages the STDERR output.\n* `bool isError` : Returns `True` if either the return code is non-zero or `STDERR` contains some data.\n\n### Methods\n\n* `void dump(str prefix = None, callable printFunc = None)` : Write debugging data to STDOUT (if `printFunc` is `None`, or use the specified callable as a replacement for `print(..)`).\n* `dict getStdOutAsJSON()` : Interpret the text data as JSON data and return it.\n* `ElementTree getStdOutAsXML()` : Interpret the text data as XML and return an ElemenTree object.\n* `* getStdOutAsLXML()` : Interpret the text data as an LXML tree object and return it. (Requires `lxml` to be installed.)\n* `void raiseExceptionOnError(exceptionMessage:str, bDumpStatusOnError:bool = False)` : If the return code is no-zero or <c>STDERR</c> contains data an exception is thrown using the specified exception message.\n* `dict toJSON()` : Convert the whole object to a JSON dictionary.\n\nContact Information\n--------------------------------\n\nThis is Open Source code. That not only gives you the possibility of freely using this code it also\nallows you to contribute. Feel free to contact the author(s) of this software listed below, either\nfor comments, collaboration requests, suggestions for improvement or reporting bugs:\n\n* J\u00fcrgen Knauth: pubsrc@binary-overflow.de\n\nLicense\n--------------------------------\n\nThis software is provided under the following license:\n\n* Apache Software License 2.0\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python module to run command line programs in a convenient way and retrieve their output after they terminated.",
"version": "0.2024.8.11",
"project_urls": null,
"split_keywords": [
"exec",
" shell",
" execute",
" popen",
" kill",
" spawn"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a4f42839695007f67f74a55ca9fb1b891d28464cdc75481049568a5230397ad7",
"md5": "15f24707809aff364576a91f32997674",
"sha256": "4ec3f33f19cf826ebd6a78446d66c8ff7896ec94e4547f21fa0cd7ba9ed02563"
},
"downloads": -1,
"filename": "jk_simpleexec-0.2024.8.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15f24707809aff364576a91f32997674",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12411,
"upload_time": "2024-08-11T12:52:28",
"upload_time_iso_8601": "2024-08-11T12:52:28.901593Z",
"url": "https://files.pythonhosted.org/packages/a4/f4/2839695007f67f74a55ca9fb1b891d28464cdc75481049568a5230397ad7/jk_simpleexec-0.2024.8.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "353c638d9b420055d4e7966929e84651b86b4d11a30cadd4406141a8c3960343",
"md5": "94250c96af72d9cb58897491e8a1440f",
"sha256": "a072eb4ec21ae8618aec8d7cb0c5f578876fc4fb0c831294d1d35a88e1abdd7d"
},
"downloads": -1,
"filename": "jk_simpleexec-0.2024.8.11.tar.gz",
"has_sig": false,
"md5_digest": "94250c96af72d9cb58897491e8a1440f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11047,
"upload_time": "2024-08-11T12:52:30",
"upload_time_iso_8601": "2024-08-11T12:52:30.644468Z",
"url": "https://files.pythonhosted.org/packages/35/3c/638d9b420055d4e7966929e84651b86b4d11a30cadd4406141a8c3960343/jk_simpleexec-0.2024.8.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-11 12:52:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "jk_simpleexec"
}
