shellescape


Nameshellescape JSON
Version 3.8.1 PyPI version JSON
download
home_pagehttps://github.com/chrissimpkins/shellescape
SummaryShell 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)
upload_time2020-01-25 21:28:23
maintainer
docs_urlNone
authorChristopher Simpkins
requires_python
licenseMIT license
keywords shell quote escape backport command line command subprocess
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.01121s