# shellescape
## Description
The shellescape Python module defines the `shellescape.quote()` function that returns a shell-escaped version of a Python string. This is a backport of the `shlex.quote()` function from Python 3.8 that makes it accessible to users of Python 3 versions < 3.3 and all Python 2.x versions.
### quote(s)
*From the Python documentation*:
Return a shell-escaped version of the string s. The returned value is a string that can safely be used as one token in a shell command line, for cases where you cannot use a list.
This idiom would be unsafe:
```python
>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l {}'.format(filename)
>>> print(command) # executed by a shell: boom!
ls -l somefile; rm -rf ~
```
`quote()` lets you plug the security hole:
```python
>>> command = 'ls -l {}'.format(quote(filename))
>>> print(command)
ls -l 'somefile; rm -rf ~'
>>> remote_command = 'ssh home {}'.format(quote(command))
>>> print(remote_command)
ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''
```
The quoting is compatible with UNIX shells and with `shlex.split()`:
```python
>>> remote_command = split(remote_command)
>>> remote_command
['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
>>> command = split(remote_command[-1])
>>> command
['ls', '-l', 'somefile; rm -rf ~']
```
## Usage
Include `shellescape` in your project setup.py file `install_requires` dependency definition list:
```python
setup(
...
install_requires=['shellescape'],
...
)
```
Then import the `quote` function into your module(s) and use it as needed:
```python
#!/usr/bin/env python
# -*- coding: utf-8 -*-
from shellescape import quote
filename = "somefile; rm -rf ~"
escaped_shell_command = 'ls -l {}'.format(quote(filename))
```
## License
[LICENSE](https://github.com/chrissimpkins/shellescape/blob/master/docs/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/chrissimpkins/shellescape",
"name": "shellescape",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "shell,quote,escape,backport,command line,command,subprocess",
"author": "Christopher Simpkins",
"author_email": "git.simpkins@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/19/40/13b9e84bf04774365830cbed1bd95a989d5324a99d207bcb1619a6c517f2/shellescape-3.8.1.tar.gz",
"platform": "any",
"description": "# shellescape\n\n## Description\n\nThe shellescape Python module defines the `shellescape.quote()` function that returns a shell-escaped version of a Python string. This is a backport of the `shlex.quote()` function from Python 3.8 that makes it accessible to users of Python 3 versions < 3.3 and all Python 2.x versions.\n\n\n### quote(s)\n\n*From the Python documentation*:\n\nReturn a shell-escaped version of the string s. The returned value is a string that can safely be used as one token in a shell command line, for cases where you cannot use a list.\n\nThis idiom would be unsafe:\n\n```python\n>>> filename = 'somefile; rm -rf ~'\n>>> command = 'ls -l {}'.format(filename)\n>>> print(command) # executed by a shell: boom!\nls -l somefile; rm -rf ~\n```\n\n`quote()` lets you plug the security hole:\n\n```python\n>>> command = 'ls -l {}'.format(quote(filename))\n>>> print(command)\nls -l 'somefile; rm -rf ~'\n>>> remote_command = 'ssh home {}'.format(quote(command))\n>>> print(remote_command)\nssh home 'ls -l '\"'\"'somefile; rm -rf ~'\"'\"''\n```\n\nThe quoting is compatible with UNIX shells and with `shlex.split()`:\n\n```python\n>>> remote_command = split(remote_command)\n>>> remote_command\n['ssh', 'home', \"ls -l 'somefile; rm -rf ~'\"]\n>>> command = split(remote_command[-1])\n>>> command\n['ls', '-l', 'somefile; rm -rf ~']\n```\n\n\n## Usage\n\nInclude `shellescape` in your project setup.py file `install_requires` dependency definition list:\n\n```python\nsetup(\n ...\n install_requires=['shellescape'],\n ...\n)\n```\n\nThen import the `quote` function into your module(s) and use it as needed:\n\n```python\n#!/usr/bin/env python\n# -*- coding: utf-8 -*-\n\nfrom shellescape import quote\n\nfilename = \"somefile; rm -rf ~\"\nescaped_shell_command = 'ls -l {}'.format(quote(filename))\n```\n\n## License\n\n[LICENSE](https://github.com/chrissimpkins/shellescape/blob/master/docs/LICENSE)\n\n\n\n\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Shell escape a string to safely use it as a token in a shell command (backport of cPython shlex.quote for Python versions 2.x & < 3.3)",
"version": "3.8.1",
"split_keywords": [
"shell",
"quote",
"escape",
"backport",
"command line",
"command",
"subprocess"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "26e30843610330a890d96f35aa22859b",
"sha256": "f17127e390fa3f9aaa80c69c16ea73615fd9b5318fd8309c1dca6168ae7d85bf"
},
"downloads": -1,
"filename": "shellescape-3.8.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "26e30843610330a890d96f35aa22859b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 3081,
"upload_time": "2020-01-25T21:28:21",
"upload_time_iso_8601": "2020-01-25T21:28:21.772484Z",
"url": "https://files.pythonhosted.org/packages/d0/f4/0081137fceff5779cd4205c1e96657e41cc2d2d56c940dc8eeb6111780f7/shellescape-3.8.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "82e0074ef39471286f37d701e9efce7e",
"sha256": "40b310b30479be771bf3ab28bd8d40753778488bd46ea0969ba0b35038c3ec26"
},
"downloads": -1,
"filename": "shellescape-3.8.1.tar.gz",
"has_sig": false,
"md5_digest": "82e0074ef39471286f37d701e9efce7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5246,
"upload_time": "2020-01-25T21:28:23",
"upload_time_iso_8601": "2020-01-25T21:28:23.228297Z",
"url": "https://files.pythonhosted.org/packages/19/40/13b9e84bf04774365830cbed1bd95a989d5324a99d207bcb1619a6c517f2/shellescape-3.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-01-25 21:28:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "chrissimpkins",
"github_project": "shellescape",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "shellescape"
}
JSON
