Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Bevaka 1
Stjärnmärk 0
Wiki 捐赠
gooderp18绿色标准版
Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.
Träd: 0f75e31513
Grenar Taggar
${ item.name }
Skapa branchen ${ searchTerm }
från '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/shlex.html

776 lines
63KB
Rå Blame Historik 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="shlex — Simple lexical analysis" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/shlex.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Source code: Lib/shlex.py The shlex class makes it easy to write lexical analyzers for simple syntaxes resembling that of the Unix shell. This will often be useful for writing minilanguages, (for e..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Source code: Lib/shlex.py The shlex class makes it easy to write lexical analyzers for simple syntaxes resembling that of the Unix shell. This will often be useful for writing minilanguages, (for e..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>shlex — Simple lexical analysis &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="Graphical User Interfaces with Tk" href="tk.html" />

  39.     <link rel="prev" title="cmd — Support for line-oriented command interpreters" href="cmd.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/shlex.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code> — Simple lexical analysis</a><ul>

  99. <li><a class="reference internal" href="#shlex-objects">shlex Objects</a></li>

  100. <li><a class="reference internal" href="#parsing-rules">Parsing Rules</a></li>

  101. <li><a class="reference internal" href="#improved-compatibility-with-shells">Improved Compatibility with Shells</a></li>

  102. </ul>

  103. </li>

  104. </ul>

  105. 

  106.   </div>

  107.   <div>

  108.     <h4>Previous topic</h4>

  109.     <p class="topless"><a href="cmd.html"

  110.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmd</span></code> — Support for line-oriented command interpreters</a></p>

  111.   </div>

  112.   <div>

  113.     <h4>Next topic</h4>

  114.     <p class="topless"><a href="tk.html"

  115.                           title="next chapter">Graphical User Interfaces with Tk</a></p>

  116.   </div>

  117.   <div role="note" aria-label="source link">

  118.     <h3>This Page</h3>

  119.     <ul class="this-page-menu">

  120.       <li><a href="../bugs.html">Report a Bug</a></li>

  121.       <li>

  122.         <a href="https://github.com/python/cpython/blob/main/Doc/library/shlex.rst"

  123.             rel="nofollow">Show Source

  124.         </a>

  125.       </li>

  126.     </ul>

  127.   </div>

  128.         </nav>

  129.     </div>

  130. </div>

  131. 

  132.   

  133.     <div class="related" role="navigation" aria-label="related navigation">

  134.       <h3>Navigation</h3>

  135.       <ul>

  136.         <li class="right" style="margin-right: 10px">

  137.           <a href="../genindex.html" title="General Index"

  138.              accesskey="I">index</a></li>

  139.         <li class="right" >

  140.           <a href="../py-modindex.html" title="Python Module Index"

  141.              >modules</a> |</li>

  142.         <li class="right" >

  143.           <a href="tk.html" title="Graphical User Interfaces with Tk"

  144.              accesskey="N">next</a> |</li>

  145.         <li class="right" >

  146.           <a href="cmd.html" title="cmd — Support for line-oriented command interpreters"

  147.              accesskey="P">previous</a> |</li>

  148. 

  149.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  150.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  151.           <li class="switchers">

  152.             <div class="language_switcher_placeholder"></div>

  153.             <div class="version_switcher_placeholder"></div>

  154.           </li>

  155.           <li>

  156.               

  157.           </li>

  158.     <li id="cpython-language-and-version">

  159.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  160.     </li>

  161. 

  162.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  163.           <li class="nav-item nav-item-2"><a href="frameworks.html" accesskey="U">Program Frameworks</a> &#187;</li>

  164.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code> — Simple lexical analysis</a></li>

  165.                 <li class="right">

  166.                     

  167. 

  168.     <div class="inline-search" role="search">

  169.         <form class="inline-search" action="../search.html" method="get">

  170.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  171.           <input type="submit" value="Go" />

  172.         </form>

  173.     </div>

  174.                      |

  175.                 </li>

  176.             <li class="right">

  177. <label class="theme-selector-label">

  178.     Theme

  179.     <select class="theme-selector" oninput="activateTheme(this.value)">

  180.         <option value="auto" selected>Auto</option>

  181.         <option value="light">Light</option>

  182.         <option value="dark">Dark</option>

  183.     </select>

  184. </label> |</li>

  185.             

  186.       </ul>

  187.     </div>    

  188. 

  189.     <div class="document">

  190.       <div class="documentwrapper">

  191.         <div class="bodywrapper">

  192.           <div class="body" role="main">

  193.             

  194.   <section id="module-shlex">

  195. <span id="shlex-simple-lexical-analysis"></span><h1><a class="reference internal" href="#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a> — Simple lexical analysis<a class="headerlink" href="#module-shlex" title="Link to this heading">¶</a></h1>

  196. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/shlex.py">Lib/shlex.py</a></p>

  197. <hr class="docutils" />

  198. <p>The <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> class makes it easy to write lexical analyzers for

  199. simple syntaxes resembling that of the Unix shell.  This will often be useful

  200. for writing minilanguages, (for example, in run control files for Python

  201. applications) or for parsing quoted strings.</p>

  202. <p>The <a class="reference internal" href="#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a> module defines the following functions:</p>

  203. <dl class="py function">

  204. <dt class="sig sig-object py" id="shlex.split">

  205. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">split</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">comments</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">posix</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.split" title="Link to this definition">¶</a></dt>

  206. <dd><p>Split the string <em>s</em> using shell-like syntax. If <em>comments</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>

  207. (the default), the parsing of comments in the given string will be disabled

  208. (setting the <a class="reference internal" href="#shlex.shlex.commenters" title="shlex.shlex.commenters"><code class="xref py py-attr docutils literal notranslate"><span class="pre">commenters</span></code></a> attribute of the

  209. <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> instance to the empty string).  This function operates

  210. in POSIX mode by default, but uses non-POSIX mode if the <em>posix</em> argument is

  211. false.</p>

  212. <div class="versionchanged">

  213. <p><span class="versionmodified changed">Changed in version 3.12: </span>Passing <code class="docutils literal notranslate"><span class="pre">None</span></code> for <em>s</em> argument now raises an exception, rather than

  214. reading <a class="reference internal" href="sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a>.</p>

  215. </div>

  216. </dd></dl>

  217. 

  218. <dl class="py function">

  219. <dt class="sig sig-object py" id="shlex.join">

  220. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">join</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">split_command</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.join" title="Link to this definition">¶</a></dt>

  221. <dd><p>Concatenate the tokens of the list <em>split_command</em> and return a string.

  222. This function is the inverse of <a class="reference internal" href="#shlex.split" title="shlex.split"><code class="xref py py-func docutils literal notranslate"><span class="pre">split()</span></code></a>.</p>

  223. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">shlex</span> <span class="kn">import</span> <span class="n">join</span>

  224. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">join</span><span class="p">([</span><span class="s1">&#39;echo&#39;</span><span class="p">,</span> <span class="s1">&#39;-n&#39;</span><span class="p">,</span> <span class="s1">&#39;Multiple words&#39;</span><span class="p">]))</span>

  225. <span class="go">echo -n &#39;Multiple words&#39;</span>

  226. </pre></div>

  227. </div>

  228. <p>The returned value is shell-escaped to protect against injection

  229. vulnerabilities (see <a class="reference internal" href="#shlex.quote" title="shlex.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote()</span></code></a>).</p>

  230. <div class="versionadded">

  231. <p><span class="versionmodified added">New in version 3.8.</span></p>

  232. </div>

  233. </dd></dl>

  234. 

  235. <dl class="py function">

  236. <dt class="sig sig-object py" id="shlex.quote">

  237. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">quote</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.quote" title="Link to this definition">¶</a></dt>

  238. <dd><p>Return a shell-escaped version of the string <em>s</em>.  The returned value is a

  239. string that can safely be used as one token in a shell command line, for

  240. cases where you cannot use a list.</p>

  241. <div class="admonition warning" id="shlex-quote-warning">

  242. <p class="admonition-title">Warning</p>

  243. <p>The <code class="docutils literal notranslate"><span class="pre">shlex</span></code> module is <strong>only designed for Unix shells</strong>.</p>

  244. <p>The <a class="reference internal" href="#shlex.quote" title="shlex.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote()</span></code></a> function is not guaranteed to be correct on non-POSIX

  245. compliant shells or shells from other operating systems such as Windows.

  246. Executing commands quoted by this module on such shells can open up the

  247. possibility of a command injection vulnerability.</p>

  248. <p>Consider using functions that pass command arguments with lists such as

  249. <a class="reference internal" href="subprocess.html#subprocess.run" title="subprocess.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">subprocess.run()</span></code></a> with <code class="docutils literal notranslate"><span class="pre">shell=False</span></code>.</p>

  250. </div>

  251. <p>This idiom would be unsafe:</p>

  252. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">filename</span> <span class="o">=</span> <span class="s1">&#39;somefile; rm -rf ~&#39;</span>

  253. <span class="gp">&gt;&gt;&gt; </span><span class="n">command</span> <span class="o">=</span> <span class="s1">&#39;ls -l </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>

  254. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">command</span><span class="p">)</span>  <span class="c1"># executed by a shell: boom!</span>

  255. <span class="go">ls -l somefile; rm -rf ~</span>

  256. </pre></div>

  257. </div>

  258. <p><a class="reference internal" href="#shlex.quote" title="shlex.quote"><code class="xref py py-func docutils literal notranslate"><span class="pre">quote()</span></code></a> lets you plug the security hole:</p>

  259. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">shlex</span> <span class="kn">import</span> <span class="n">quote</span>

  260. <span class="gp">&gt;&gt;&gt; </span><span class="n">command</span> <span class="o">=</span> <span class="s1">&#39;ls -l </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">quote</span><span class="p">(</span><span class="n">filename</span><span class="p">))</span>

  261. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">command</span><span class="p">)</span>

  262. <span class="go">ls -l &#39;somefile; rm -rf ~&#39;</span>

  263. <span class="gp">&gt;&gt;&gt; </span><span class="n">remote_command</span> <span class="o">=</span> <span class="s1">&#39;ssh home </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">quote</span><span class="p">(</span><span class="n">command</span><span class="p">))</span>

  264. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">remote_command</span><span class="p">)</span>

  265. <span class="go">ssh home &#39;ls -l &#39;&quot;&#39;&quot;&#39;somefile; rm -rf ~&#39;&quot;&#39;&quot;&#39;&#39;</span>

  266. </pre></div>

  267. </div>

  268. <p>The quoting is compatible with UNIX shells and with <a class="reference internal" href="#shlex.split" title="shlex.split"><code class="xref py py-func docutils literal notranslate"><span class="pre">split()</span></code></a>:</p>

  269. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">shlex</span> <span class="kn">import</span> <span class="n">split</span>

  270. <span class="gp">&gt;&gt;&gt; </span><span class="n">remote_command</span> <span class="o">=</span> <span class="n">split</span><span class="p">(</span><span class="n">remote_command</span><span class="p">)</span>

  271. <span class="gp">&gt;&gt;&gt; </span><span class="n">remote_command</span>

  272. <span class="go">[&#39;ssh&#39;, &#39;home&#39;, &quot;ls -l &#39;somefile; rm -rf ~&#39;&quot;]</span>

  273. <span class="gp">&gt;&gt;&gt; </span><span class="n">command</span> <span class="o">=</span> <span class="n">split</span><span class="p">(</span><span class="n">remote_command</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span>

  274. <span class="gp">&gt;&gt;&gt; </span><span class="n">command</span>

  275. <span class="go">[&#39;ls&#39;, &#39;-l&#39;, &#39;somefile; rm -rf ~&#39;]</span>

  276. </pre></div>

  277. </div>

  278. <div class="versionadded">

  279. <p><span class="versionmodified added">New in version 3.3.</span></p>

  280. </div>

  281. </dd></dl>

  282. 

  283. <p>The <a class="reference internal" href="#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a> module defines the following class:</p>

  284. <dl class="py class">

  285. <dt class="sig sig-object py" id="shlex.shlex">

  286. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">shlex</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">instream</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">infile</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">posix</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">punctuation_chars</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex" title="Link to this definition">¶</a></dt>

  287. <dd><p>A <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> instance or subclass instance is a lexical analyzer

  288. object.  The initialization argument, if present, specifies where to read

  289. characters from.  It must be a file-/stream-like object with

  290. <a class="reference internal" href="io.html#io.TextIOBase.read" title="io.TextIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> and <a class="reference internal" href="io.html#io.TextIOBase.readline" title="io.TextIOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> methods, or

  291. a string.  If no argument is given, input will be taken from <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>.

  292. The second optional argument is a filename string, which sets the initial

  293. value of the <a class="reference internal" href="#shlex.shlex.infile" title="shlex.shlex.infile"><code class="xref py py-attr docutils literal notranslate"><span class="pre">infile</span></code></a> attribute.  If the <em>instream</em>

  294. argument is omitted or equal to <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>, this second argument

  295. defaults to “stdin”.  The <em>posix</em> argument defines the operational mode:

  296. when <em>posix</em> is not true (default), the <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> instance will

  297. operate in compatibility mode.  When operating in POSIX mode,

  298. <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> will try to be as close as possible to the POSIX shell

  299. parsing rules.  The <em>punctuation_chars</em> argument provides a way to make the

  300. behaviour even closer to how real shells parse.  This can take a number of

  301. values: the default value, <code class="docutils literal notranslate"><span class="pre">False</span></code>, preserves the behaviour seen under

  302. Python 3.5 and earlier.  If set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, then parsing of the characters

  303. <code class="docutils literal notranslate"><span class="pre">();&lt;&gt;|&amp;</span></code> is changed: any run of these characters (considered punctuation

  304. characters) is returned as a single token.  If set to a non-empty string of

  305. characters, those characters will be used as the punctuation characters.  Any

  306. characters in the <a class="reference internal" href="#shlex.shlex.wordchars" title="shlex.shlex.wordchars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">wordchars</span></code></a> attribute that appear in

  307. <em>punctuation_chars</em> will be removed from <a class="reference internal" href="#shlex.shlex.wordchars" title="shlex.shlex.wordchars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">wordchars</span></code></a>.  See

  308. <a class="reference internal" href="#improved-shell-compatibility"><span class="std std-ref">Improved Compatibility with Shells</span></a> for more information. <em>punctuation_chars</em>

  309. can be set only upon <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> instance creation and can’t be

  310. modified later.</p>

  311. <div class="versionchanged">

  312. <p><span class="versionmodified changed">Changed in version 3.6: </span>The <em>punctuation_chars</em> parameter was added.</p>

  313. </div>

  314. </dd></dl>

  315. 

  316. <div class="admonition seealso">

  317. <p class="admonition-title">See also</p>

  318. <dl class="simple">

  319. <dt>Module <a class="reference internal" href="configparser.html#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a></dt><dd><p>Parser for configuration files similar to the Windows <code class="file docutils literal notranslate"><span class="pre">.ini</span></code> files.</p>

  320. </dd>

  321. </dl>

  322. </div>

  323. <section id="shlex-objects">

  324. <span id="id1"></span><h2>shlex Objects<a class="headerlink" href="#shlex-objects" title="Link to this heading">¶</a></h2>

  325. <p>A <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> instance has the following methods:</p>

  326. <dl class="py method">

  327. <dt class="sig sig-object py" id="shlex.shlex.get_token">

  328. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">get_token</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.get_token" title="Link to this definition">¶</a></dt>

  329. <dd><p>Return a token.  If tokens have been stacked using <a class="reference internal" href="#shlex.shlex.push_token" title="shlex.shlex.push_token"><code class="xref py py-meth docutils literal notranslate"><span class="pre">push_token()</span></code></a>, pop a

  330. token off the stack.  Otherwise, read one from the input stream.  If reading

  331. encounters an immediate end-of-file, <a class="reference internal" href="#shlex.shlex.eof" title="shlex.shlex.eof"><code class="xref py py-attr docutils literal notranslate"><span class="pre">eof</span></code></a> is returned (the empty

  332. string (<code class="docutils literal notranslate"><span class="pre">''</span></code>) in non-POSIX mode, and <code class="docutils literal notranslate"><span class="pre">None</span></code> in POSIX mode).</p>

  333. </dd></dl>

  334. 

  335. <dl class="py method">

  336. <dt class="sig sig-object py" id="shlex.shlex.push_token">

  337. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">push_token</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.push_token" title="Link to this definition">¶</a></dt>

  338. <dd><p>Push the argument onto the token stack.</p>

  339. </dd></dl>

  340. 

  341. <dl class="py method">

  342. <dt class="sig sig-object py" id="shlex.shlex.read_token">

  343. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">read_token</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.read_token" title="Link to this definition">¶</a></dt>

  344. <dd><p>Read a raw token.  Ignore the pushback stack, and do not interpret source

  345. requests.  (This is not ordinarily a useful entry point, and is documented here

  346. only for the sake of completeness.)</p>

  347. </dd></dl>

  348. 

  349. <dl class="py method">

  350. <dt class="sig sig-object py" id="shlex.shlex.sourcehook">

  351. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">sourcehook</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.sourcehook" title="Link to this definition">¶</a></dt>

  352. <dd><p>When <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> detects a source request (see <a class="reference internal" href="#shlex.shlex.source" title="shlex.shlex.source"><code class="xref py py-attr docutils literal notranslate"><span class="pre">source</span></code></a>

  353. below) this method is given the following token as argument, and expected

  354. to return a tuple consisting of a filename and an open file-like object.</p>

  355. <p>Normally, this method first strips any quotes off the argument.  If the result

  356. is an absolute pathname, or there was no previous source request in effect, or

  357. the previous source was a stream (such as <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>), the result is left

  358. alone.  Otherwise, if the result is a relative pathname, the directory part of

  359. the name of the file immediately before it on the source inclusion stack is

  360. prepended (this behavior is like the way the C preprocessor handles <code class="docutils literal notranslate"><span class="pre">#include</span>

  361. <span class="pre">&quot;file.h&quot;</span></code>).</p>

  362. <p>The result of the manipulations is treated as a filename, and returned as the

  363. first component of the tuple, with <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> called on it to yield the second

  364. component. (Note: this is the reverse of the order of arguments in instance

  365. initialization!)</p>

  366. <p>This hook is exposed so that you can use it to implement directory search paths,

  367. addition of file extensions, and other namespace hacks. There is no

  368. corresponding ‘close’ hook, but a shlex instance will call the

  369. <a class="reference internal" href="io.html#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method of the sourced input stream when it returns

  370. EOF.</p>

  371. <p>For more explicit control of source stacking, use the <a class="reference internal" href="#shlex.shlex.push_source" title="shlex.shlex.push_source"><code class="xref py py-meth docutils literal notranslate"><span class="pre">push_source()</span></code></a> and

  372. <a class="reference internal" href="#shlex.shlex.pop_source" title="shlex.shlex.pop_source"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pop_source()</span></code></a> methods.</p>

  373. </dd></dl>

  374. 

  375. <dl class="py method">

  376. <dt class="sig sig-object py" id="shlex.shlex.push_source">

  377. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">push_source</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">newstream</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">newfile</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.push_source" title="Link to this definition">¶</a></dt>

  378. <dd><p>Push an input source stream onto the input stack.  If the filename argument is

  379. specified it will later be available for use in error messages.  This is the

  380. same method used internally by the <a class="reference internal" href="#shlex.shlex.sourcehook" title="shlex.shlex.sourcehook"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sourcehook()</span></code></a> method.</p>

  381. </dd></dl>

  382. 

  383. <dl class="py method">

  384. <dt class="sig sig-object py" id="shlex.shlex.pop_source">

  385. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">pop_source</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.pop_source" title="Link to this definition">¶</a></dt>

  386. <dd><p>Pop the last-pushed input source from the input stack. This is the same method

  387. used internally when the lexer reaches EOF on a stacked input stream.</p>

  388. </dd></dl>

  389. 

  390. <dl class="py method">

  391. <dt class="sig sig-object py" id="shlex.shlex.error_leader">

  392. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">error_leader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">infile</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#shlex.shlex.error_leader" title="Link to this definition">¶</a></dt>

  393. <dd><p>This method generates an error message leader in the format of a Unix C compiler

  394. error label; the format is <code class="docutils literal notranslate"><span class="pre">'&quot;%s&quot;,</span> <span class="pre">line</span> <span class="pre">%d:</span> <span class="pre">'</span></code>, where the <code class="docutils literal notranslate"><span class="pre">%s</span></code> is replaced

  395. with the name of the current source file and the <code class="docutils literal notranslate"><span class="pre">%d</span></code> with the current input

  396. line number (the optional arguments can be used to override these).</p>

  397. <p>This convenience is provided to encourage <a class="reference internal" href="#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a> users to generate error

  398. messages in the standard, parseable format understood by Emacs and other Unix

  399. tools.</p>

  400. </dd></dl>

  401. 

  402. <p>Instances of <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> subclasses have some public instance

  403. variables which either control lexical analysis or can be used for debugging:</p>

  404. <dl class="py attribute">

  405. <dt class="sig sig-object py" id="shlex.shlex.commenters">

  406. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">commenters</span></span><a class="headerlink" href="#shlex.shlex.commenters" title="Link to this definition">¶</a></dt>

  407. <dd><p>The string of characters that are recognized as comment beginners. All

  408. characters from the comment beginner to end of line are ignored. Includes just

  409. <code class="docutils literal notranslate"><span class="pre">'#'</span></code> by default.</p>

  410. </dd></dl>

  411. 

  412. <dl class="py attribute">

  413. <dt class="sig sig-object py" id="shlex.shlex.wordchars">

  414. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">wordchars</span></span><a class="headerlink" href="#shlex.shlex.wordchars" title="Link to this definition">¶</a></dt>

  415. <dd><p>The string of characters that will accumulate into multi-character tokens.  By

  416. default, includes all ASCII alphanumerics and underscore.  In POSIX mode, the

  417. accented characters in the Latin-1 set are also included.  If

  418. <a class="reference internal" href="#shlex.shlex.punctuation_chars" title="shlex.shlex.punctuation_chars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">punctuation_chars</span></code></a> is not empty, the characters <code class="docutils literal notranslate"><span class="pre">~-./*?=</span></code>, which can

  419. appear in filename specifications and command line parameters, will also be

  420. included in this attribute, and any characters which appear in

  421. <code class="docutils literal notranslate"><span class="pre">punctuation_chars</span></code> will be removed from <code class="docutils literal notranslate"><span class="pre">wordchars</span></code> if they are present

  422. there. If <a class="reference internal" href="#shlex.shlex.whitespace_split" title="shlex.shlex.whitespace_split"><code class="xref py py-attr docutils literal notranslate"><span class="pre">whitespace_split</span></code></a> is set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, this will have no

  423. effect.</p>

  424. </dd></dl>

  425. 

  426. <dl class="py attribute">

  427. <dt class="sig sig-object py" id="shlex.shlex.whitespace">

  428. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">whitespace</span></span><a class="headerlink" href="#shlex.shlex.whitespace" title="Link to this definition">¶</a></dt>

  429. <dd><p>Characters that will be considered whitespace and skipped.  Whitespace bounds

  430. tokens.  By default, includes space, tab, linefeed and carriage-return.</p>

  431. </dd></dl>

  432. 

  433. <dl class="py attribute">

  434. <dt class="sig sig-object py" id="shlex.shlex.escape">

  435. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">escape</span></span><a class="headerlink" href="#shlex.shlex.escape" title="Link to this definition">¶</a></dt>

  436. <dd><p>Characters that will be considered as escape. This will be only used in POSIX

  437. mode, and includes just <code class="docutils literal notranslate"><span class="pre">'\'</span></code> by default.</p>

  438. </dd></dl>

  439. 

  440. <dl class="py attribute">

  441. <dt class="sig sig-object py" id="shlex.shlex.quotes">

  442. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">quotes</span></span><a class="headerlink" href="#shlex.shlex.quotes" title="Link to this definition">¶</a></dt>

  443. <dd><p>Characters that will be considered string quotes.  The token accumulates until

  444. the same quote is encountered again (thus, different quote types protect each

  445. other as in the shell.)  By default, includes ASCII single and double quotes.</p>

  446. </dd></dl>

  447. 

  448. <dl class="py attribute">

  449. <dt class="sig sig-object py" id="shlex.shlex.escapedquotes">

  450. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">escapedquotes</span></span><a class="headerlink" href="#shlex.shlex.escapedquotes" title="Link to this definition">¶</a></dt>

  451. <dd><p>Characters in <a class="reference internal" href="#shlex.shlex.quotes" title="shlex.shlex.quotes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">quotes</span></code></a> that will interpret escape characters defined in

  452. <a class="reference internal" href="#shlex.shlex.escape" title="shlex.shlex.escape"><code class="xref py py-attr docutils literal notranslate"><span class="pre">escape</span></code></a>.  This is only used in POSIX mode, and includes just <code class="docutils literal notranslate"><span class="pre">'&quot;'</span></code> by

  453. default.</p>

  454. </dd></dl>

  455. 

  456. <dl class="py attribute">

  457. <dt class="sig sig-object py" id="shlex.shlex.whitespace_split">

  458. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">whitespace_split</span></span><a class="headerlink" href="#shlex.shlex.whitespace_split" title="Link to this definition">¶</a></dt>

  459. <dd><p>If <code class="docutils literal notranslate"><span class="pre">True</span></code>, tokens will only be split in whitespaces.  This is useful, for

  460. example, for parsing command lines with <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a>, getting

  461. tokens in a similar way to shell arguments.  When used in combination with

  462. <a class="reference internal" href="#shlex.shlex.punctuation_chars" title="shlex.shlex.punctuation_chars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">punctuation_chars</span></code></a>, tokens will be split on whitespace in addition to

  463. those characters.</p>

  464. <div class="versionchanged">

  465. <p><span class="versionmodified changed">Changed in version 3.8: </span>The <a class="reference internal" href="#shlex.shlex.punctuation_chars" title="shlex.shlex.punctuation_chars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">punctuation_chars</span></code></a> attribute was made compatible with the

  466. <a class="reference internal" href="#shlex.shlex.whitespace_split" title="shlex.shlex.whitespace_split"><code class="xref py py-attr docutils literal notranslate"><span class="pre">whitespace_split</span></code></a> attribute.</p>

  467. </div>

  468. </dd></dl>

  469. 

  470. <dl class="py attribute">

  471. <dt class="sig sig-object py" id="shlex.shlex.infile">

  472. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">infile</span></span><a class="headerlink" href="#shlex.shlex.infile" title="Link to this definition">¶</a></dt>

  473. <dd><p>The name of the current input file, as initially set at class instantiation time

  474. or stacked by later source requests.  It may be useful to examine this when

  475. constructing error messages.</p>

  476. </dd></dl>

  477. 

  478. <dl class="py attribute">

  479. <dt class="sig sig-object py" id="shlex.shlex.instream">

  480. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">instream</span></span><a class="headerlink" href="#shlex.shlex.instream" title="Link to this definition">¶</a></dt>

  481. <dd><p>The input stream from which this <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> instance is reading

  482. characters.</p>

  483. </dd></dl>

  484. 

  485. <dl class="py attribute">

  486. <dt class="sig sig-object py" id="shlex.shlex.source">

  487. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">source</span></span><a class="headerlink" href="#shlex.shlex.source" title="Link to this definition">¶</a></dt>

  488. <dd><p>This attribute is <code class="docutils literal notranslate"><span class="pre">None</span></code> by default.  If you assign a string to it, that

  489. string will be recognized as a lexical-level inclusion request similar to the

  490. <code class="docutils literal notranslate"><span class="pre">source</span></code> keyword in various shells.  That is, the immediately following token

  491. will be opened as a filename and input will be taken from that stream until

  492. EOF, at which point the <a class="reference internal" href="io.html#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method of that stream will be

  493. called and the input source will again become the original input stream.  Source

  494. requests may be stacked any number of levels deep.</p>

  495. </dd></dl>

  496. 

  497. <dl class="py attribute">

  498. <dt class="sig sig-object py" id="shlex.shlex.debug">

  499. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">debug</span></span><a class="headerlink" href="#shlex.shlex.debug" title="Link to this definition">¶</a></dt>

  500. <dd><p>If this attribute is numeric and <code class="docutils literal notranslate"><span class="pre">1</span></code> or more, a <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a>

  501. instance will print verbose progress output on its behavior.  If you need

  502. to use this, you can read the module source code to learn the details.</p>

  503. </dd></dl>

  504. 

  505. <dl class="py attribute">

  506. <dt class="sig sig-object py" id="shlex.shlex.lineno">

  507. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">lineno</span></span><a class="headerlink" href="#shlex.shlex.lineno" title="Link to this definition">¶</a></dt>

  508. <dd><p>Source line number (count of newlines seen so far plus one).</p>

  509. </dd></dl>

  510. 

  511. <dl class="py attribute">

  512. <dt class="sig sig-object py" id="shlex.shlex.token">

  513. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">token</span></span><a class="headerlink" href="#shlex.shlex.token" title="Link to this definition">¶</a></dt>

  514. <dd><p>The token buffer.  It may be useful to examine this when catching exceptions.</p>

  515. </dd></dl>

  516. 

  517. <dl class="py attribute">

  518. <dt class="sig sig-object py" id="shlex.shlex.eof">

  519. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">eof</span></span><a class="headerlink" href="#shlex.shlex.eof" title="Link to this definition">¶</a></dt>

  520. <dd><p>Token used to determine end of file. This will be set to the empty string

  521. (<code class="docutils literal notranslate"><span class="pre">''</span></code>), in non-POSIX mode, and to <code class="docutils literal notranslate"><span class="pre">None</span></code> in POSIX mode.</p>

  522. </dd></dl>

  523. 

  524. <dl class="py attribute">

  525. <dt class="sig sig-object py" id="shlex.shlex.punctuation_chars">

  526. <span class="sig-prename descclassname"><span class="pre">shlex.</span></span><span class="sig-name descname"><span class="pre">punctuation_chars</span></span><a class="headerlink" href="#shlex.shlex.punctuation_chars" title="Link to this definition">¶</a></dt>

  527. <dd><p>A read-only property. Characters that will be considered punctuation. Runs of

  528. punctuation characters will be returned as a single token. However, note that no

  529. semantic validity checking will be performed: for example, ‘&gt;&gt;&gt;’ could be

  530. returned as a token, even though it may not be recognised as such by shells.</p>

  531. <div class="versionadded">

  532. <p><span class="versionmodified added">New in version 3.6.</span></p>

  533. </div>

  534. </dd></dl>

  535. 

  536. </section>

  537. <section id="parsing-rules">

  538. <span id="shlex-parsing-rules"></span><h2>Parsing Rules<a class="headerlink" href="#parsing-rules" title="Link to this heading">¶</a></h2>

  539. <p>When operating in non-POSIX mode, <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> will try to obey to the

  540. following rules.</p>

  541. <ul class="simple">

  542. <li><p>Quote characters are not recognized within words (<code class="docutils literal notranslate"><span class="pre">Do&quot;Not&quot;Separate</span></code> is

  543. parsed as the single word <code class="docutils literal notranslate"><span class="pre">Do&quot;Not&quot;Separate</span></code>);</p></li>

  544. <li><p>Escape characters are not recognized;</p></li>

  545. <li><p>Enclosing characters in quotes preserve the literal value of all characters

  546. within the quotes;</p></li>

  547. <li><p>Closing quotes separate words (<code class="docutils literal notranslate"><span class="pre">&quot;Do&quot;Separate</span></code> is parsed as <code class="docutils literal notranslate"><span class="pre">&quot;Do&quot;</span></code> and

  548. <code class="docutils literal notranslate"><span class="pre">Separate</span></code>);</p></li>

  549. <li><p>If <a class="reference internal" href="#shlex.shlex.whitespace_split" title="shlex.shlex.whitespace_split"><code class="xref py py-attr docutils literal notranslate"><span class="pre">whitespace_split</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, any character not

  550. declared to be a word character, whitespace, or a quote will be returned as

  551. a single-character token. If it is <code class="docutils literal notranslate"><span class="pre">True</span></code>, <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> will only

  552. split words in whitespaces;</p></li>

  553. <li><p>EOF is signaled with an empty string (<code class="docutils literal notranslate"><span class="pre">''</span></code>);</p></li>

  554. <li><p>It’s not possible to parse empty strings, even if quoted.</p></li>

  555. </ul>

  556. <p>When operating in POSIX mode, <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> will try to obey to the

  557. following parsing rules.</p>

  558. <ul class="simple">

  559. <li><p>Quotes are stripped out, and do not separate words (<code class="docutils literal notranslate"><span class="pre">&quot;Do&quot;Not&quot;Separate&quot;</span></code> is

  560. parsed as the single word <code class="docutils literal notranslate"><span class="pre">DoNotSeparate</span></code>);</p></li>

  561. <li><p>Non-quoted escape characters (e.g. <code class="docutils literal notranslate"><span class="pre">'\'</span></code>) preserve the literal value of the

  562. next character that follows;</p></li>

  563. <li><p>Enclosing characters in quotes which are not part of

  564. <a class="reference internal" href="#shlex.shlex.escapedquotes" title="shlex.shlex.escapedquotes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">escapedquotes</span></code></a> (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;'&quot;</span></code>) preserve the literal value

  565. of all characters within the quotes;</p></li>

  566. <li><p>Enclosing characters in quotes which are part of

  567. <a class="reference internal" href="#shlex.shlex.escapedquotes" title="shlex.shlex.escapedquotes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">escapedquotes</span></code></a> (e.g. <code class="docutils literal notranslate"><span class="pre">'&quot;'</span></code>) preserves the literal value

  568. of all characters within the quotes, with the exception of the characters

  569. mentioned in <a class="reference internal" href="#shlex.shlex.escape" title="shlex.shlex.escape"><code class="xref py py-attr docutils literal notranslate"><span class="pre">escape</span></code></a>.  The escape characters retain its

  570. special meaning only when followed by the quote in use, or the escape

  571. character itself. Otherwise the escape character will be considered a

  572. normal character.</p></li>

  573. <li><p>EOF is signaled with a <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> value;</p></li>

  574. <li><p>Quoted empty strings (<code class="docutils literal notranslate"><span class="pre">''</span></code>) are allowed.</p></li>

  575. </ul>

  576. </section>

  577. <section id="improved-compatibility-with-shells">

  578. <span id="improved-shell-compatibility"></span><h2>Improved Compatibility with Shells<a class="headerlink" href="#improved-compatibility-with-shells" title="Link to this heading">¶</a></h2>

  579. <div class="versionadded">

  580. <p><span class="versionmodified added">New in version 3.6.</span></p>

  581. </div>

  582. <p>The <a class="reference internal" href="#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a> class provides compatibility with the parsing performed by

  583. common Unix shells like <code class="docutils literal notranslate"><span class="pre">bash</span></code>, <code class="docutils literal notranslate"><span class="pre">dash</span></code>, and <code class="docutils literal notranslate"><span class="pre">sh</span></code>.  To take advantage of

  584. this compatibility, specify the <code class="docutils literal notranslate"><span class="pre">punctuation_chars</span></code> argument in the

  585. constructor.  This defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>, which preserves pre-3.6 behaviour.

  586. However, if it is set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, then parsing of the characters <code class="docutils literal notranslate"><span class="pre">();&lt;&gt;|&amp;</span></code>

  587. is changed: any run of these characters is returned as a single token.  While

  588. this is short of a full parser for shells (which would be out of scope for the

  589. standard library, given the multiplicity of shells out there), it does allow

  590. you to perform processing of command lines more easily than you could

  591. otherwise.  To illustrate, you can see the difference in the following snippet:</p>

  592. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="go"> &gt;&gt;&gt; import shlex</span>

  593. <span class="go"> &gt;&gt;&gt; text = &quot;a &amp;&amp; b; c &amp;&amp; d || e; f &gt;&#39;abc&#39;; (def \&quot;ghi\&quot;)&quot;</span>

  594. <span class="go"> &gt;&gt;&gt; s = shlex.shlex(text, posix=True)</span>

  595. <span class="go"> &gt;&gt;&gt; s.whitespace_split = True</span>

  596. <span class="go"> &gt;&gt;&gt; list(s)</span>

  597. <span class="go"> [&#39;a&#39;, &#39;&amp;&amp;&#39;, &#39;b;&#39;, &#39;c&#39;, &#39;&amp;&amp;&#39;, &#39;d&#39;, &#39;||&#39;, &#39;e;&#39;, &#39;f&#39;, &#39;&gt;abc;&#39;, &#39;(def&#39;, &#39;ghi)&#39;]</span>

  598. <span class="go"> &gt;&gt;&gt; s = shlex.shlex(text, posix=True, punctuation_chars=True)</span>

  599. <span class="go"> &gt;&gt;&gt; s.whitespace_split = True</span>

  600. <span class="go"> &gt;&gt;&gt; list(s)</span>

  601. <span class="go"> [&#39;a&#39;, &#39;&amp;&amp;&#39;, &#39;b&#39;, &#39;;&#39;, &#39;c&#39;, &#39;&amp;&amp;&#39;, &#39;d&#39;, &#39;||&#39;, &#39;e&#39;, &#39;;&#39;, &#39;f&#39;, &#39;&gt;&#39;, &#39;abc&#39;, &#39;;&#39;,</span>

  602. <span class="go"> &#39;(&#39;, &#39;def&#39;, &#39;ghi&#39;, &#39;)&#39;]</span>

  603. </pre></div>

  604. </div>

  605. <p>Of course, tokens will be returned which are not valid for shells, and you’ll

  606. need to implement your own error checks on the returned tokens.</p>

  607. <p>Instead of passing <code class="docutils literal notranslate"><span class="pre">True</span></code> as the value for the punctuation_chars parameter,

  608. you can pass a string with specific characters, which will be used to determine

  609. which characters constitute punctuation. For example:</p>

  610. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">shlex</span>

  611. <span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">shlex</span><span class="o">.</span><span class="n">shlex</span><span class="p">(</span><span class="s2">&quot;a &amp;&amp; b || c&quot;</span><span class="p">,</span> <span class="n">punctuation_chars</span><span class="o">=</span><span class="s2">&quot;|&quot;</span><span class="p">)</span>

  612. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>

  613. <span class="go">[&#39;a&#39;, &#39;&amp;&#39;, &#39;&amp;&#39;, &#39;b&#39;, &#39;||&#39;, &#39;c&#39;]</span>

  614. </pre></div>

  615. </div>

  616. <div class="admonition note">

  617. <p class="admonition-title">Note</p>

  618. <p>When <code class="docutils literal notranslate"><span class="pre">punctuation_chars</span></code> is specified, the <a class="reference internal" href="#shlex.shlex.wordchars" title="shlex.shlex.wordchars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">wordchars</span></code></a>

  619. attribute is augmented with the characters <code class="docutils literal notranslate"><span class="pre">~-./*?=</span></code>.  That is because these

  620. characters can appear in file names (including wildcards) and command-line

  621. arguments (e.g. <code class="docutils literal notranslate"><span class="pre">--color=auto</span></code>). Hence:</p>

  622. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">shlex</span>

  623. <span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">shlex</span><span class="o">.</span><span class="n">shlex</span><span class="p">(</span><span class="s1">&#39;~/a &amp;&amp; b-c --color=auto || d *.py?&#39;</span><span class="p">,</span>

  624. <span class="gp">... </span>                <span class="n">punctuation_chars</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  625. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>

  626. <span class="go">[&#39;~/a&#39;, &#39;&amp;&amp;&#39;, &#39;b-c&#39;, &#39;--color=auto&#39;, &#39;||&#39;, &#39;d&#39;, &#39;*.py?&#39;]</span>

  627. </pre></div>

  628. </div>

  629. <p>However, to match the shell as closely as possible, it is recommended to

  630. always use <code class="docutils literal notranslate"><span class="pre">posix</span></code> and <a class="reference internal" href="#shlex.shlex.whitespace_split" title="shlex.shlex.whitespace_split"><code class="xref py py-attr docutils literal notranslate"><span class="pre">whitespace_split</span></code></a> when using

  631. <a class="reference internal" href="#shlex.shlex.punctuation_chars" title="shlex.shlex.punctuation_chars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">punctuation_chars</span></code></a>, which will negate

  632. <a class="reference internal" href="#shlex.shlex.wordchars" title="shlex.shlex.wordchars"><code class="xref py py-attr docutils literal notranslate"><span class="pre">wordchars</span></code></a> entirely.</p>

  633. </div>

  634. <p>For best effect, <code class="docutils literal notranslate"><span class="pre">punctuation_chars</span></code> should be set in conjunction with

  635. <code class="docutils literal notranslate"><span class="pre">posix=True</span></code>. (Note that <code class="docutils literal notranslate"><span class="pre">posix=False</span></code> is the default for

  636. <a class="reference internal" href="#shlex.shlex" title="shlex.shlex"><code class="xref py py-class docutils literal notranslate"><span class="pre">shlex</span></code></a>.)</p>

  637. </section>

  638. </section>

  639. 

  640. 

  641.             <div class="clearer"></div>

  642.           </div>

  643.         </div>

  644.       </div>

  645.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  646.         <div class="sphinxsidebarwrapper">

  647.   <div>

  648.     <h3><a href="../contents.html">Table of Contents</a></h3>

  649.     <ul>

  650. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code> — Simple lexical analysis</a><ul>

  651. <li><a class="reference internal" href="#shlex-objects">shlex Objects</a></li>

  652. <li><a class="reference internal" href="#parsing-rules">Parsing Rules</a></li>

  653. <li><a class="reference internal" href="#improved-compatibility-with-shells">Improved Compatibility with Shells</a></li>

  654. </ul>

  655. </li>

  656. </ul>

  657. 

  658.   </div>

  659.   <div>

  660.     <h4>Previous topic</h4>

  661.     <p class="topless"><a href="cmd.html"

  662.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmd</span></code> — Support for line-oriented command interpreters</a></p>

  663.   </div>

  664.   <div>

  665.     <h4>Next topic</h4>

  666.     <p class="topless"><a href="tk.html"

  667.                           title="next chapter">Graphical User Interfaces with Tk</a></p>

  668.   </div>

  669.   <div role="note" aria-label="source link">

  670.     <h3>This Page</h3>

  671.     <ul class="this-page-menu">

  672.       <li><a href="../bugs.html">Report a Bug</a></li>

  673.       <li>

  674.         <a href="https://github.com/python/cpython/blob/main/Doc/library/shlex.rst"

  675.             rel="nofollow">Show Source

  676.         </a>

  677.       </li>

  678.     </ul>

  679.   </div>

  680.         </div>

  681. <div id="sidebarbutton" title="Collapse sidebar">

  682. <span>«</span>

  683. </div>

  684. 

  685.       </div>

  686.       <div class="clearer"></div>

  687.     </div>  

  688.     <div class="related" role="navigation" aria-label="related navigation">

  689.       <h3>Navigation</h3>

  690.       <ul>

  691.         <li class="right" style="margin-right: 10px">

  692.           <a href="../genindex.html" title="General Index"

  693.              >index</a></li>

  694.         <li class="right" >

  695.           <a href="../py-modindex.html" title="Python Module Index"

  696.              >modules</a> |</li>

  697.         <li class="right" >

  698.           <a href="tk.html" title="Graphical User Interfaces with Tk"

  699.              >next</a> |</li>

  700.         <li class="right" >

  701.           <a href="cmd.html" title="cmd — Support for line-oriented command interpreters"

  702.              >previous</a> |</li>

  703. 

  704.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  705.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  706.           <li class="switchers">

  707.             <div class="language_switcher_placeholder"></div>

  708.             <div class="version_switcher_placeholder"></div>

  709.           </li>

  710.           <li>

  711.               

  712.           </li>

  713.     <li id="cpython-language-and-version">

  714.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  715.     </li>

  716. 

  717.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  718.           <li class="nav-item nav-item-2"><a href="frameworks.html" >Program Frameworks</a> &#187;</li>

  719.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code> — Simple lexical analysis</a></li>

  720.                 <li class="right">

  721.                     

  722. 

  723.     <div class="inline-search" role="search">

  724.         <form class="inline-search" action="../search.html" method="get">

  725.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  726.           <input type="submit" value="Go" />

  727.         </form>

  728.     </div>

  729.                      |

  730.                 </li>

  731.             <li class="right">

  732. <label class="theme-selector-label">

  733.     Theme

  734.     <select class="theme-selector" oninput="activateTheme(this.value)">

  735.         <option value="auto" selected>Auto</option>

  736.         <option value="light">Light</option>

  737.         <option value="dark">Dark</option>

  738.     </select>

  739. </label> |</li>

  740.             

  741.       </ul>

  742.     </div>  

  743.     <div class="footer">

  744.     &copy; 

  745.       <a href="../copyright.html">

  746.     

  747.     Copyright

  748.     

  749.       </a>

  750.      2001-2024, Python Software Foundation.

  751.     <br />

  752.     This page is licensed under the Python Software Foundation License Version 2.

  753.     <br />

  754.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  755.     <br />

  756.     

  757.       See <a href="/license.html">History and License</a> for more information.<br />

  758.     

  759.     

  760.     <br />

  761. 

  762.     The Python Software Foundation is a non-profit corporation.

  763. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  764. <br />

  765.     <br />

  766.       Last updated on Apr 09, 2024 (13:47 UTC).

  767.     

  768.       <a href="/bugs.html">Found a bug</a>?

  769.     

  770.     <br />

  771. 

  772.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  773.     </div>

  774. 

  775.   </body>

  776. </html>
上海开阖软件有限公司 沪ICP备12045867号-1