| Name | interactive-process JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2025-01-24 18:47:05 |
| maintainer | None |
| docs_url | None |
| author | Yason Khaburzaniya |
| requires_python | <4.0,>=3.10 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Interactive Process · [](https://pypi.org/project/interactive-process/)
[](https://github.com/breba-apps/interactive_process/actions/workflows/test.yaml)
A Python package that provides a simple interface to manage interactive shells using a pseudo-terminal. It wraps around [PtyProcessUnicode][ptyprocess-docs] to let you send commands, read outputs, handle timeouts, and gracefully terminate processes.
- **License:** [MIT](#license)
- **Author:** Yason Khaburzaniya
## Description
The `interactive-process` package allows you to spawn and interact with a shell (`/bin/bash` on Unix-like systems or `cmd.exe` on Windows) in a controlled pseudo-terminal environment. This is useful when you need to automate or script tasks that depend on interactive command-line behavior, such as sending commands and reading their outputs in real time.
Key features include:
1. **Cross-Platform Shell Access** – Automatically chooses the correct shell based on the operating system. (Nonblocking reads do not work due to select not supporting file descriptors on windows)
2. **Customizable Environment** – Control environment variables and echo behavior.
3. **Non-Blocking Reads** – Read output with a configurable timeout; raises a `TimeoutError` if no data is received in time.
4. **Exception Handling** – Raises specialized exceptions for terminated processes or I/O issues.
5. **Easy Cleanup** – Gracefully terminate processes with a single method call.
## Installation
This package is published on PyPI under the name `interactive-process`. To install:
```bash
pip install interactive-process
```
You will also need [`ptyprocess`][ptyprocess-pypi], which will be automatically installed if it’s not already present in your environment.
## Usage
Below is an example demonstrating how to create an interactive process, send commands, read outputs, and handle potential errors or timeouts.
```python
from interactive_process import InteractiveProcess, TerminatedProcessError, ReadWriteError
# Create an InteractiveProcess instance
proc = InteractiveProcess()
try:
# Send a simple echo command
proc.send_command("echo Hello, Interactive Shell!")
# Attempt to read the response with a 0.1s timeout
output = proc.read_nonblocking(timeout=0.1)
print("Output received:\n", output)
except TerminatedProcessError as e:
print("Process terminated unexpectedly:", e)
except ReadWriteError as e:
print("Read/Write error:", e)
except TimeoutError as e:
print("No data received within timeout:", e)
finally:
# Ensure the process is terminated properly
proc.close()
```
### Debugging in a Container
If you need to run in a container because you are having issues in a system other than your own, run the following commands from the package root directory.
**First build and start the container**
```shell
docker build -t my-poetry-image .
docker run -it --rm \
-v "$(pwd)":/usr/src/interactive-process \
my-poetry-image
```
**Then inside the container you will be able to run tests and an example**
```shell
poetry install
poetry run pytest
poetry run interactive-process
```
## API Reference
### InteractiveProcess
**Constructor**
```python
InteractiveProcess(env={"PS1": "", "TERM": "dumb"}, echo=False)
```
- **env** (dict): Environment variables for the subprocess. Default is `{"PS1": "", "TERM": "dumb"}`.
- **echo** (bool): Whether to echo commands in the console.
**send_command(command)**
- Sends a command string to the subprocess.
**read_nonblocking(timeout=0.1)**
- Reads output from the subprocess with the specified `timeout`.
- If no data is read within `timeout` seconds, a `TimeoutError` is raised.
**close()**
- Terminates the subprocess if it is still alive.
### Exceptions
- **TerminatedProcessError**
Raised when the subprocess has terminated unexpectedly.
- **ReadWriteError**
Raised when an error occurs during reading from or writing to the subprocess.
## Contributing
1. **Fork** this repository.
2. Create a new **feature branch**:
```bash
git checkout -b feature/my-new-feature
```
3. **Commit your changes**:
```bash
git commit -am "Add new feature"
```
4. **Push to the branch**:
```bash
git push origin feature/my-new-feature
```
5. Open a **Pull Request** on GitHub and provide a clear explanation of your changes.
## License
[MIT LICENSE](LICENSE)
[ptyprocess-docs]: https://pexpect.readthedocs.io/en/stable/api/pty_process.html
[ptyprocess-pypi]: https://pypi.org/project/ptyprocess/
Raw data
{
"_id": null,
"home_page": null,
"name": "interactive-process",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Yason Khaburzaniya",
"author_email": "yason@hey.com",
"download_url": "https://files.pythonhosted.org/packages/31/e1/db8a0c2d657ae32ee793a7f241918a10e6662ba26f75353a1057bbaa6542/interactive_process-0.2.5.tar.gz",
"platform": null,
"description": "# Interactive Process · [](https://pypi.org/project/interactive-process/)\n[](https://github.com/breba-apps/interactive_process/actions/workflows/test.yaml)\n\nA Python package that provides a simple interface to manage interactive shells using a pseudo-terminal. It wraps around [PtyProcessUnicode][ptyprocess-docs] to let you send commands, read outputs, handle timeouts, and gracefully terminate processes.\n\n- **License:** [MIT](#license)\n- **Author:** Yason Khaburzaniya\n\n## Description\n\nThe `interactive-process` package allows you to spawn and interact with a shell (`/bin/bash` on Unix-like systems or `cmd.exe` on Windows) in a controlled pseudo-terminal environment. This is useful when you need to automate or script tasks that depend on interactive command-line behavior, such as sending commands and reading their outputs in real time.\n\nKey features include:\n1. **Cross-Platform Shell Access** \u2013 Automatically chooses the correct shell based on the operating system. (Nonblocking reads do not work due to select not supporting file descriptors on windows)\n2. **Customizable Environment** \u2013 Control environment variables and echo behavior.\n3. **Non-Blocking Reads** \u2013 Read output with a configurable timeout; raises a `TimeoutError` if no data is received in time.\n4. **Exception Handling** \u2013 Raises specialized exceptions for terminated processes or I/O issues.\n5. **Easy Cleanup** \u2013 Gracefully terminate processes with a single method call.\n\n## Installation\n\nThis package is published on PyPI under the name `interactive-process`. To install:\n\n```bash\npip install interactive-process\n```\n\nYou will also need [`ptyprocess`][ptyprocess-pypi], which will be automatically installed if it\u2019s not already present in your environment.\n\n## Usage\n\nBelow is an example demonstrating how to create an interactive process, send commands, read outputs, and handle potential errors or timeouts.\n\n```python\nfrom interactive_process import InteractiveProcess, TerminatedProcessError, ReadWriteError\n\n# Create an InteractiveProcess instance\nproc = InteractiveProcess()\n\ntry:\n # Send a simple echo command\n proc.send_command(\"echo Hello, Interactive Shell!\")\n\n # Attempt to read the response with a 0.1s timeout\n output = proc.read_nonblocking(timeout=0.1)\n print(\"Output received:\\n\", output)\n\nexcept TerminatedProcessError as e:\n print(\"Process terminated unexpectedly:\", e)\nexcept ReadWriteError as e:\n print(\"Read/Write error:\", e)\nexcept TimeoutError as e:\n print(\"No data received within timeout:\", e)\nfinally:\n # Ensure the process is terminated properly\n proc.close()\n```\n\n### Debugging in a Container\n\nIf you need to run in a container because you are having issues in a system other than your own, run the following commands from the package root directory.\n\n**First build and start the container**\n```shell\ndocker build -t my-poetry-image .\n\ndocker run -it --rm \\ \n -v \"$(pwd)\":/usr/src/interactive-process \\\n my-poetry-image\n```\n**Then inside the container you will be able to run tests and an example**\n```shell\npoetry install\n\npoetry run pytest\npoetry run interactive-process\n```\n\n## API Reference\n\n### InteractiveProcess\n\n**Constructor**\n```python\nInteractiveProcess(env={\"PS1\": \"\", \"TERM\": \"dumb\"}, echo=False)\n```\n- **env** (dict): Environment variables for the subprocess. Default is `{\"PS1\": \"\", \"TERM\": \"dumb\"}`.\n- **echo** (bool): Whether to echo commands in the console.\n\n**send_command(command)**\n- Sends a command string to the subprocess.\n\n**read_nonblocking(timeout=0.1)**\n- Reads output from the subprocess with the specified `timeout`.\n- If no data is read within `timeout` seconds, a `TimeoutError` is raised.\n\n**close()**\n- Terminates the subprocess if it is still alive.\n\n### Exceptions\n\n- **TerminatedProcessError**\n Raised when the subprocess has terminated unexpectedly.\n\n- **ReadWriteError**\n Raised when an error occurs during reading from or writing to the subprocess.\n\n## Contributing\n\n1. **Fork** this repository.\n2. Create a new **feature branch**:\n ```bash\n git checkout -b feature/my-new-feature\n ```\n3. **Commit your changes**:\n ```bash\n git commit -am \"Add new feature\"\n ```\n4. **Push to the branch**:\n ```bash\n git push origin feature/my-new-feature\n ```\n5. Open a **Pull Request** on GitHub and provide a clear explanation of your changes.\n\n## License\n\n[MIT LICENSE](LICENSE)\n\n\n\n[ptyprocess-docs]: https://pexpect.readthedocs.io/en/stable/api/pty_process.html\n[ptyprocess-pypi]: https://pypi.org/project/ptyprocess/",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.2.5",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "838b36000c0fce66596c97ffba3b34f2e6dcd8b6397a17e097c53b69d31cdc96",
"md5": "94f27817d485cc7f347184eeddc2f76f",
"sha256": "290e72fefc33a3638efc879fcbf250302adfc284398d68b7406a2d1f0971b6a7"
},
"downloads": -1,
"filename": "interactive_process-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94f27817d485cc7f347184eeddc2f76f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 5967,
"upload_time": "2025-01-24T18:47:04",
"upload_time_iso_8601": "2025-01-24T18:47:04.099934Z",
"url": "https://files.pythonhosted.org/packages/83/8b/36000c0fce66596c97ffba3b34f2e6dcd8b6397a17e097c53b69d31cdc96/interactive_process-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "31e1db8a0c2d657ae32ee793a7f241918a10e6662ba26f75353a1057bbaa6542",
"md5": "69d6f7155781afa98bcdaf2b892e2d25",
"sha256": "347ecc4c081da7a5bb8b408bab40364e2584c8e7b82a02bf0aaf6be08a98144b"
},
"downloads": -1,
"filename": "interactive_process-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "69d6f7155781afa98bcdaf2b892e2d25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 4561,
"upload_time": "2025-01-24T18:47:05",
"upload_time_iso_8601": "2025-01-24T18:47:05.045046Z",
"url": "https://files.pythonhosted.org/packages/31/e1/db8a0c2d657ae32ee793a7f241918a10e6662ba26f75353a1057bbaa6542/interactive_process-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-24 18:47:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "interactive-process"
}
