Metadata-Version: 1.1
Name: shellescape
Version: 3.8.1
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)
Home-page: https://github.com/chrissimpkins/shellescape
Author: Christopher Simpkins
Author-email: git.simpkins@gmail.com
License: MIT license
Description-Content-Type: text/markdown
Description: # 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)
        
        
        
Keywords: shell,quote,escape,backport,command line,command,subprocess
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: Microsoft :: Windows
