uTools-Manuals/docs/python/site.html

<div class="body" role="main"><div class="section" id="module-site"><h1><span class="yiyi-st" id="yiyi-10">29.13. <a class="reference internal" href="#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal"><span class="pre">site</span></code></a>  - 网站特定的配置钩</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源代码：</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/site.py">Lib / site.py</a></span></p><p><span class="yiyi-st" id="yiyi-12"><strong>此模块在初始化期间自动导入。</strong></span><span class="yiyi-st" id="yiyi-13">可以使用解释器的<a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal"><span class="pre">-S</span></code></a>选项抑制自动导入。</span></p><p id="index-0"><span class="yiyi-st" id="yiyi-14">导入此模块将会将站点特定的路径附加到模块搜索路径，并添加一些内置字段，除非使用<a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal"><span class="pre">-S</span></code></a>。</span><span class="yiyi-st" id="yiyi-15">在这种情况下，可以安全地导入此模块，而不会自动修改模块搜索路径或添加内置模块。</span><span class="yiyi-st" id="yiyi-16">要显式触发通常的特定于站点的添加，请调用<a class="reference internal" href="#site.main" title="site.main"><code class="xref py py-func docutils literal"><span class="pre">site.main()</span></code></a>函数。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-17"><span class="versionmodified">在版本3.3中更改：</span>导入用于触发路径操作的模块，即使使用<a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal"><span class="pre">-S</span></code></a>。</span></p></div><p id="index-1"><span class="yiyi-st" id="yiyi-18">它从头部和尾部构造最多四个目录开始。</span><span class="yiyi-st" id="yiyi-19">对于头部，它使用<code class="docutils literal"><span class="pre">sys.prefix</span></code>和<code class="docutils literal"><span class="pre">sys.exec_prefix</span></code>；空头被跳过。</span><span class="yiyi-st" id="yiyi-20">对于尾部，它使用空字符串，然后<code class="file docutils literal"><span class="pre">lib/site-packages</span></code>（在Windows上）或<code class="file docutils literal"><span class="pre">lib / python</span> <em><span class="pre">X.Y</span></em> <span class="pre">/ site-packages</span></code>（在Unix和Macintosh上）。</span><span class="yiyi-st" id="yiyi-21">对于每个不同的头 - 尾组合，它看到它是否指现有目录，如果是，则将其添加到<code class="docutils literal"><span class="pre">sys.path</span></code>，并且还检查新添加的配置文件路径。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-22"><span class="versionmodified">在3.5版本中更改：</span>已删除对“site-python”目录的支持。</span></p></div><p><span class="yiyi-st" id="yiyi-23">如果一个名为“pyvenv.cfg”的文件存在于sys.executable之上的一个目录下，sys.prefix和sys.exec_prefix被设置为该目录，并且还检查site-packages（sys.base_prefix和sys.base_exec_prefix将始终是“真正的”前缀的Python安装）。</span><span class="yiyi-st" id="yiyi-24">如果“pyvenv.cfg”（引导配置文件）包含设置为“false”（不区分大小写）以外的任何内容的关键字“include-system-site-packages”，系统级前缀仍将搜索站点 - 包装；否则他们不会。</span></p><p><span class="yiyi-st" id="yiyi-25">路径配置文件是名称形式为<code class="file docutils literal"><em><span class="pre">name</span></em> <span class="pre">.pth</span></code>并存在于上述四个目录中的文件；其内容是要添加到<code class="docutils literal"><span class="pre">sys.path</span></code>的附加项目（每行一个）。</span><span class="yiyi-st" id="yiyi-26">不存在的项目从不会添加到<code class="docutils literal"><span class="pre">sys.path</span></code>。</span><span class="yiyi-st" id="yiyi-27">没有任何项目添加到<code class="docutils literal"><span class="pre">sys.path</span></code>多次。</span><span class="yiyi-st" id="yiyi-28">将跳过以<code class="docutils literal"><span class="pre">#</span></code>开头的空行和行。</span><span class="yiyi-st" id="yiyi-29">以<code class="docutils literal"><span class="pre">import</span></code>开头的行（后跟空格或制表符）被执行。</span></p><p id="index-2"><span class="yiyi-st" id="yiyi-30">例如，假设<code class="docutils literal"><span class="pre">sys.prefix</span></code>和<code class="docutils literal"><span class="pre">sys.exec_prefix</span></code>设置为<code class="file docutils literal"><span class="pre">/usr/local</span></code>。</span><span class="yiyi-st" id="yiyi-31">Python X.Y库随后安装在<code class="file docutils literal"><span class="pre">/ usr / local / lib / python</span> <em><span class="pre">X.Y</span></em></code>中。</span><span class="yiyi-st" id="yiyi-32">假设它有三个子目录的子目录<code class="file docutils literal"><span class="pre">/ usr / local / lib / python</span> <em><span class="pre">X.Y</span></em> <span class="pre">/ site-packages</span> <code class="file docutils literal"><span class="pre">foo</span></code>，<code class="file docutils literal"><span class="pre">bar</span></code>和<code class="file docutils literal"><span class="pre">spam</span></code>和两个路径配置文件<code class="file docutils literal"><span class="pre">foo.pth</span></code>和<code class="file docutils literal"><span class="pre">bar.pth</span></code>。</code></span><span class="yiyi-st" id="yiyi-33">假设<code class="file docutils literal"><span class="pre">foo.pth</span></code>包含以下内容：</span></p><div class="highlight-none"><div class="highlight"><pre><span></span># foo package configuration

foo
bar
bletch
</pre></div></div><p><span class="yiyi-st" id="yiyi-34">和<code class="file docutils literal"><span class="pre">bar.pth</span></code>包含：</span></p><div class="highlight-none"><div class="highlight"><pre><span></span># bar package configuration

bar
</pre></div></div><p><span class="yiyi-st" id="yiyi-35">然后，以下顺序将以下特定于版本的目录添加到<code class="docutils literal"><span class="pre">sys.path</span></code>：</span></p><div class="highlight-none"><div class="highlight"><pre><span></span>/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo
</pre></div></div><p><span class="yiyi-st" id="yiyi-36">请注意，<code class="file docutils literal"><span class="pre">bletch</span></code>被省略，因为它不存在；由于<code class="file docutils literal"><span class="pre">bar.pth</span></code>在字母之前<code class="file docutils literal"><span class="pre">foo.pth</span></code>之前，<code class="file docutils literal"><span class="pre">bar</span></code>目录位于<code class="file docutils literal"><span class="pre">foo</span></code>和<code class="file docutils literal"><span class="pre">spam</span></code>被省略，因为它在任一路径配置文件中未提及。</span></p><p id="index-3"><span class="yiyi-st" id="yiyi-37">在这些路径操作之后，尝试导入名为<code class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></code>的模块，该模块可以执行任意特定于站点的自定义。</span><span class="yiyi-st" id="yiyi-38">它通常由系统管理员在site-packages目录中创建。</span><span class="yiyi-st" id="yiyi-39">如果此导入失败并出现<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal"><span class="pre">ImportError</span></code></a>异常，则会被忽略。</span><span class="yiyi-st" id="yiyi-40">如果Python启动时没有可用的输出流，如Windows上的<code class="file docutils literal"><span class="pre">pythonw.exe</span></code>（默认情况下用于启动IDLE），则会忽略<code class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></code>的尝试输出。</span><span class="yiyi-st" id="yiyi-41">除了<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal"><span class="pre">ImportError</span></code></a>之外的任何异常都会导致进程无声或可能是神秘的故障。</span></p><p id="index-4"><span class="yiyi-st" id="yiyi-42">此后，尝试导入名为<code class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></code>的模块，如果<a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><code class="xref py py-data docutils literal"><span class="pre">ENABLE_USER_SITE</span></code></a>为true，则可以执行任意用户特定的自定义。</span><span class="yiyi-st" id="yiyi-43">该文件旨在在用户site-packages目录（见下文）中创建，这是<code class="docutils literal"><span class="pre">sys.path</span></code>的一部分，除非由<a class="reference internal" href="../using/cmdline.html#cmdoption-s"><code class="xref std std-option docutils literal"><span class="pre">-s</span></code></a>禁用。将默认忽略<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal"><span class="pre">ImportError</span></code></a>。</span></p><p><span class="yiyi-st" id="yiyi-44">注意，对于一些非Unix系统，<code class="docutils literal"><span class="pre">sys.prefix</span></code>和<code class="docutils literal"><span class="pre">sys.exec_prefix</span></code>为空，并且跳过路径操作；但仍尝试导入<code class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></code>和<code class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></code>。</span></p><div class="section" id="readline-configuration"><h2><span class="yiyi-st" id="yiyi-45">29.13.1. </span><span class="yiyi-st" id="yiyi-46">Readline configuration</span></h2><p><span class="yiyi-st" id="yiyi-47">On systems that support <a class="reference internal" href="readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-mod docutils literal"><span class="pre">readline</span></code></a>, this module will also import and configure the <a class="reference internal" href="rlcompleter.html#module-rlcompleter" title="rlcompleter: Python identifier completion, suitable for the GNU readline library."><code class="xref py py-mod docutils literal"><span class="pre">rlcompleter</span></code></a> module, if Python is started in <a class="reference internal" href="../tutorial/interpreter.html#tut-interactive"><span>interactive mode</span></a> and without the <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal"><span class="pre">-S</span></code></a> option. </span><span class="yiyi-st" id="yiyi-48">默认行为是启用制表符完成，并使用<code class="file docutils literal"><span class="pre">~/.python_history</span></code>作为历史保存文件。</span><span class="yiyi-st" id="yiyi-49">要禁用它，请在您的<code class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></code>或<code class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></code>模块或您的<span class="target" id="index-5"></span>模块中删除（或覆盖）<a class="reference internal" href="sys.html#sys.__interactivehook__" title="sys.__interactivehook__"><code class="xref py py-data docutils literal"><span class="pre">sys.__interactivehook__</span></code></a> <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONSTARTUP"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONSTARTUP</span></code></a>文件。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-50"><span class="versionmodified">在版本3.4中更改：</span>自动激活rlcompleter和历史记录。</span></p></div></div><div class="section" id="module-contents"><h2><span class="yiyi-st" id="yiyi-51">29.13.2. </span><span class="yiyi-st" id="yiyi-52">Module contents</span></h2><dl class="data"><dt id="site.PREFIXES"><span class="yiyi-st" id="yiyi-53"> <code class="descclassname">site.</code><code class="descname">PREFIXES</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-54">site-packages目录的前缀列表。</span></p></dd></dl><dl class="data"><dt id="site.ENABLE_USER_SITE"><span class="yiyi-st" id="yiyi-55"> <code class="descclassname">site.</code><code class="descname">ENABLE_USER_SITE</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-56">标志显示用户site-packages目录的状态。</span><span class="yiyi-st" id="yiyi-57"><code class="docutils literal"><span class="pre">True</span></code>表示已启用，并已添加到<code class="docutils literal"><span class="pre">sys.path</span></code>。</span><span class="yiyi-st" id="yiyi-58"><code class="docutils literal"><span class="pre">False</span></code>表示已由用户请求停用（<a class="reference internal" href="../using/cmdline.html#cmdoption-s"><code class="xref std std-option docutils literal"><span class="pre">-s</span></code></a>或<span class="target" id="index-6"></span> <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNOUSERSITE"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONNOUSERSITE</span></code></a>）。</span><span class="yiyi-st" id="yiyi-59"><code class="docutils literal"><span class="pre">None</span></code>表示由于安全原因（用户或组ID与有效ID不匹配）或管理员已禁用。</span></p></dd></dl><dl class="data"><dt id="site.USER_SITE"><span class="yiyi-st" id="yiyi-60"> <code class="descclassname">site.</code><code class="descname">USER_SITE</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-61">用户站点的路径 - 正在运行的Python的包。</span><span class="yiyi-st" id="yiyi-62">可以<code class="docutils literal"><span class="pre">None</span></code>如果<a class="reference internal" href="#site.getusersitepackages" title="site.getusersitepackages"><code class="xref py py-func docutils literal"><span class="pre">getusersitepackages()</span></code></a>尚未被调用。</span><span class="yiyi-st" id="yiyi-63">对于UNIX和非框架，默认值为<code class="file docutils literal"><span class="pre">〜/ .local / lib / python</span> <em><span class="pre">X.Y</span></em> <span class="pre">/ site-packages</span>  Mac OS X构建，<code class="file docutils literal"><span class="pre">〜/ Library / Python /</span> <em><span class="pre">X.Y</span></em> <span class="pre">/ lib / python / site-packages</span></code>框架构建和<code class="file docutils literal"><em><span class="pre">%APPDATA%</span></em> <span class="pre">\ Python \ Python</span> <em><span class="pre">XY</span></em> <span class="pre">\ site-packages</span>  t10 &gt;在Windows上。</code></code></span><span class="yiyi-st" id="yiyi-64">此目录是网站目录，这意味着它将处理<code class="file docutils literal"><span class="pre">.pth</span></code>文件。</span></p></dd></dl><dl class="data"><dt id="site.USER_BASE"><span class="yiyi-st" id="yiyi-65"> <code class="descclassname">site.</code><code class="descname">USER_BASE</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-66">用户site-packages的基本目录的路径。</span><span class="yiyi-st" id="yiyi-67">可以<code class="docutils literal"><span class="pre">None</span></code>如果<a class="reference internal" href="#site.getuserbase" title="site.getuserbase"><code class="xref py py-func docutils literal"><span class="pre">getuserbase()</span></code></a>尚未被调用。</span><span class="yiyi-st" id="yiyi-68">对于UNIX和Mac OS X非框架构建，默认值为<code class="file docutils literal"><span class="pre">~/.local</span></code>，<code class="file docutils literal"><span class="pre">〜/ Library / Python /</span> <em><span class="pre">X.Y</span></em> （对于Mac框架构建）和<code class="file docutils literal"><em><span class="pre">%APPDATA%</span></em> <span class="pre">\ Python</span></code></code></span><span class="yiyi-st" id="yiyi-69">Distutils使用此值计算脚本，数据文件，Python模块等的安装目录。</span><span class="yiyi-st" id="yiyi-70">用于<a class="reference internal" href="../install/index.html#inst-alt-install-user"><span>user installation scheme</span></a>。</span><span class="yiyi-st" id="yiyi-71">另见<span class="target" id="index-7"></span> <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONUSERBASE"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONUSERBASE</span></code></a>。</span></p></dd></dl><dl class="function"><dt id="site.main"><span class="yiyi-st" id="yiyi-72"> <code class="descclassname">site.</code><code class="descname">main</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-73">将所有标准站点特定目录添加到模块搜索路径。</span><span class="yiyi-st" id="yiyi-74">此模块导入时，此函数会自动调用，除非Python解释器以<a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal"><span class="pre">-S</span></code></a>标志启动。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-75"><span class="versionmodified">在版本3.3中更改：</span>此函数用于无条件调用。</span></p></div></dd></dl><dl class="function"><dt id="site.addsitedir"><span class="yiyi-st" id="yiyi-76"> <code class="descclassname">site.</code><code class="descname">addsitedir</code><span class="sig-paren">(</span><em>sitedir</em>, <em>known_paths=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-77">将目录添加到sys.path并处理其<code class="file docutils literal"><span class="pre">.pth</span></code>文件。</span><span class="yiyi-st" id="yiyi-78">通常用于<code class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></code>或<code class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></code>（见上文）。</span></p></dd></dl><dl class="function"><dt id="site.getsitepackages"><span class="yiyi-st" id="yiyi-79"> <code class="descclassname">site.</code><code class="descname">getsitepackages</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-80">返回一个包含所有全局site-packages目录的列表。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-81"><span class="versionmodified">版本3.2中的新功能。</span></span></p></div></dd></dl><dl class="function"><dt id="site.getuserbase"><span class="yiyi-st" id="yiyi-82"> <code class="descclassname">site.</code><code class="descname">getuserbase</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-83">返回用户基本目录<a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><code class="xref py py-data docutils literal"><span class="pre">USER_BASE</span></code></a>的路径。</span><span class="yiyi-st" id="yiyi-84">如果尚未初始化，此功能也将设置它，遵守<span class="target" id="index-8"></span> <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONUSERBASE"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONUSERBASE</span></code></a>。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-85"><span class="versionmodified">版本3.2中的新功能。</span></span></p></div></dd></dl><dl class="function"><dt id="site.getusersitepackages"><span class="yiyi-st" id="yiyi-86"> <code class="descclassname">site.</code><code class="descname">getusersitepackages</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-87">返回用户特定的site-packages目录<a class="reference internal" href="#site.USER_SITE" title="site.USER_SITE"><code class="xref py py-data docutils literal"><span class="pre">USER_SITE</span></code></a>的路径。</span><span class="yiyi-st" id="yiyi-88">如果尚未初始化，此函数也将设置它，遵守<span class="target" id="index-9"></span> <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNOUSERSITE"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONNOUSERSITE</span></code></a>和<a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><code class="xref py py-data docutils literal"><span class="pre">USER_BASE</span></code></a>。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-89"><span class="versionmodified">版本3.2中的新功能。</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-90"><a class="reference internal" href="#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal"><span class="pre">site</span></code></a>模块还提供了一种从命令行获取用户目录的方法：</span></p><div class="highlight-sh"><div class="highlight"><pre><span></span>$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages
</pre></div></div><p><span class="yiyi-st" id="yiyi-91">如果没有参数调用，它将打印标准输出上的<a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal"><span class="pre">sys.path</span></code></a>的内容，后面是<a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><code class="xref py py-data docutils literal"><span class="pre">USER_BASE</span></code></a>的值，以及目录是否存在， <a class="reference internal" href="#site.USER_SITE" title="site.USER_SITE"><code class="xref py py-data docutils literal"><span class="pre">USER_SITE</span></code></a>的内容，最后是<a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><code class="xref py py-data docutils literal"><span class="pre">ENABLE_USER_SITE</span></code></a>的值。</span></p><dl class="cmdoption"><dt id="cmdoption-site--user-base"><span class="yiyi-st" id="yiyi-92"> <code class="descname">--user-base</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-93">打印用户基本目录的路径。</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-site--user-site"><span class="yiyi-st" id="yiyi-94"> <code class="descname">--user-site</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-95">打印用户site-packages目录的路径。</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-96">如果给出两个选项，将打印用户基本和用户站点（始终按此顺序），用<a class="reference internal" href="os.html#os.pathsep" title="os.pathsep"><code class="xref py py-data docutils literal"><span class="pre">os.pathsep</span></code></a>分隔。</span></p><p><span class="yiyi-st" id="yiyi-97">如果给出任何选项，脚本将退出，其中包含以下值之一：<code class="docutils literal"><span class="pre">O</span></code>如果用户site-packages目录已启用，则<code class="docutils literal"><span class="pre">1</span></code> <code class="docutils literal"><span class="pre">2</span></code>如果由于安全原因或管理员禁用，并且值大于2（如果存在错误）。</span></p><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-98">也可以看看</span></p><p class="last"><span class="yiyi-st" id="yiyi-99"><span class="target" id="index-10"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0370"><strong>PEP 370</strong></a>  - 每个用户site-packages目录</span></p></div></div></div></div>