# python-shell-source
A python module for sourcing variables from shell scripts.
## Installation
You can install this package with pip or conda.
```sh
$ pip install shell-source
```
```sh
$ conda install -c abrahammurciano shell-source
```
## Documentation
The full documentation is available [here](https://abrahammurciano.github.io/python-shell-source/shell_source)
## Usage
This module provides a function `source` which attempts to mimic the shell's source command.
The purpose of this function is to allow you to run a shell script which sets either environment variables or local variables, and then give you access to those variables. Normally this is not a straght-forward task, but this function achieves it by running the script in its intended shell then injecting commands to the shell to write its local variables and its environment variables to a temporary file. Finally it reads the temporary file and parses it to return to you with exactly the data you asked for.
### Basic Usage
If you just pass a script and an interpreter you'll get back all the environment variables and local variables visible to and set by the script.
```py
>>> from shell_source import source
>>> variables = source("path/to/script.sh", "bash")
>>> # It returns a dictionary of local and environment variables known by the script.
>>> variables
{"USER": "abraham", "PATH": "/bin:/usr/bin", ..., "foo": "bar"}
```
### Requesting Specific Variables
If you specify the argument `variables`, then only those variables you passed will be present as keys in the returned dictionary.
```py
>>> source("path/to/script.sh", "zsh", variables=("foo", "bar", "biz"))
{"foo": ..., "bar": ..., "biz", ...}
```
### Ignoring Local Variables
If you don't want to obtain any local variables set by the script, but only want the environment variables, you can pass `ignore_locals=True`.
### Passing Arguments to the shell
If you want to pass arguments to the shell, for example `-x` or `-e`, you can pass it directly in the `shell` argument.
```py
>>> source("path/to/script.sh", "bash -x")
```
### Passing Arguments to the script
If you want to pass arguments to the script being sourced, you can pass them in the `args` argument.
```py
>>> source("path/to/script.sh", "bash", args=("foo", "bar"))
```
### Supporting Different Shells
This module has been tested to work with `bash`, `zsh`, and `ksh` out of the box. You can use any other shell that's somewhat posix compliant, but it it doesn't work, you may have to create a class derived from the `Scripter` class to indicate to `source` how to interact with the shell you want to use.
Some specialized implementations of `Scripter` are provided in `shell_source.scripters` for shells that are not posix compliant, such as `csh`, `tcsh` and `fish`.
For example, to use `tcsh` to source a script, you can use the `CshScripter` class like so:
```py
>>> source("path/to/script.csh", "tcsh", scripter=CshScripter())
```
Raw data
{
"_id": null,
"home_page": "https://github.com/abrahammurciano/python-shell-source",
"name": "shell-source",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "shell,source,environment",
"author": "Abraham Murciano",
"author_email": "abrahammurciano@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a8/0b/c4ee6404c2039dad0afadcf2e54aa95d721b687c91c8ed73da59843b58b3/shell_source-3.0.0.tar.gz",
"platform": null,
"description": "# python-shell-source\nA python module for sourcing variables from shell scripts.\n\n## Installation\n\nYou can install this package with pip or conda.\n```sh\n$ pip install shell-source\n```\n```sh\n$ conda install -c abrahammurciano shell-source\n```\n\n## Documentation\n\nThe full documentation is available [here](https://abrahammurciano.github.io/python-shell-source/shell_source)\n\n## Usage\nThis module provides a function `source` which attempts to mimic the shell's source command.\n\nThe purpose of this function is to allow you to run a shell script which sets either environment variables or local variables, and then give you access to those variables. Normally this is not a straght-forward task, but this function achieves it by running the script in its intended shell then injecting commands to the shell to write its local variables and its environment variables to a temporary file. Finally it reads the temporary file and parses it to return to you with exactly the data you asked for.\n\n### Basic Usage\n\nIf you just pass a script and an interpreter you'll get back all the environment variables and local variables visible to and set by the script.\n\n```py\n>>> from shell_source import source\n>>> variables = source(\"path/to/script.sh\", \"bash\")\n>>> # It returns a dictionary of local and environment variables known by the script.\n>>> variables\n{\"USER\": \"abraham\", \"PATH\": \"/bin:/usr/bin\", ..., \"foo\": \"bar\"}\n```\n\n### Requesting Specific Variables\n\nIf you specify the argument `variables`, then only those variables you passed will be present as keys in the returned dictionary.\n\n```py\n>>> source(\"path/to/script.sh\", \"zsh\", variables=(\"foo\", \"bar\", \"biz\"))\n{\"foo\": ..., \"bar\": ..., \"biz\", ...}\n```\n\n### Ignoring Local Variables\n\nIf you don't want to obtain any local variables set by the script, but only want the environment variables, you can pass `ignore_locals=True`.\n\n### Passing Arguments to the shell\n\nIf you want to pass arguments to the shell, for example `-x` or `-e`, you can pass it directly in the `shell` argument.\n\n```py\n>>> source(\"path/to/script.sh\", \"bash -x\")\n```\n\n### Passing Arguments to the script\n\nIf you want to pass arguments to the script being sourced, you can pass them in the `args` argument.\n\n```py\n>>> source(\"path/to/script.sh\", \"bash\", args=(\"foo\", \"bar\"))\n```\n\n### Supporting Different Shells\n\nThis module has been tested to work with `bash`, `zsh`, and `ksh` out of the box. You can use any other shell that's somewhat posix compliant, but it it doesn't work, you may have to create a class derived from the `Scripter` class to indicate to `source` how to interact with the shell you want to use.\n\nSome specialized implementations of `Scripter` are provided in `shell_source.scripters` for shells that are not posix compliant, such as `csh`, `tcsh` and `fish`.\n\nFor example, to use `tcsh` to source a script, you can use the `CshScripter` class like so:\n\n```py\n>>> source(\"path/to/script.csh\", \"tcsh\", scripter=CshScripter())\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python module for sourcing variables from shell scripts",
"version": "3.0.0",
"project_urls": {
"Documentation": "https://abrahammurciano.github.io/python-shell-source/shell_source/",
"Homepage": "https://github.com/abrahammurciano/python-shell-source",
"Repository": "https://github.com/abrahammurciano/python-shell-source"
},
"split_keywords": [
"shell",
"source",
"environment"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b39e0042ea43a1e4092969f25f675aab7d26150fb32ed5ff49568d587f317a67",
"md5": "34a34f1b07db78b848cb9c83bbd7fec5",
"sha256": "79e0bbe02e1de81b43336a739ec14033e85eb863b23d53139fb79eaffab28266"
},
"downloads": -1,
"filename": "shell_source-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34a34f1b07db78b848cb9c83bbd7fec5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 8226,
"upload_time": "2023-05-24T17:16:03",
"upload_time_iso_8601": "2023-05-24T17:16:03.904431Z",
"url": "https://files.pythonhosted.org/packages/b3/9e/0042ea43a1e4092969f25f675aab7d26150fb32ed5ff49568d587f317a67/shell_source-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a80bc4ee6404c2039dad0afadcf2e54aa95d721b687c91c8ed73da59843b58b3",
"md5": "fc3203d05b9071fdb2b58271a3032cd4",
"sha256": "adbc3967c01aad4d8e94fa0c5a49dc6782689c003b639fc9af0f5ea822ab0543"
},
"downloads": -1,
"filename": "shell_source-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fc3203d05b9071fdb2b58271a3032cd4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 5920,
"upload_time": "2023-05-24T17:16:05",
"upload_time_iso_8601": "2023-05-24T17:16:05.455274Z",
"url": "https://files.pythonhosted.org/packages/a8/0b/c4ee6404c2039dad0afadcf2e54aa95d721b687c91c8ed73da59843b58b3/shell_source-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-24 17:16:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abrahammurciano",
"github_project": "python-shell-source",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shell-source"
}
JSON
