<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>28.13. site — Site-specific configuration hook — Python v3.3.0 documentation</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.3.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v3.3.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v3.3.0 documentation" href="../index.html" />
<link rel="up" title="28. Python Runtime Services" href="python.html" />
<link rel="next" title="28.14. fpectl — Floating point exception control" href="fpectl.html" />
<link rel="prev" title="28.12. inspect — Inspect live objects" href="inspect.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="fpectl.html" title="28.14. fpectl — Floating point exception control"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="inspect.html" title="28.12. inspect — Inspect live objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="http://www.python.org/">Python</a> »</li>
<li><a href="../index.html">3.3.0 Documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="python.html" accesskey="U">28. Python Runtime Services</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-site">
<span id="site-site-specific-configuration-hook"></span><h1>28.13. <a class="reference internal" href="#module-site" title="site: Module responsible for site-specific configuration."><tt class="xref py py-mod docutils literal"><span class="pre">site</span></tt></a> — Site-specific configuration hook<a class="headerlink" href="#module-site" title="Permalink to this headline">¶</a></h1>
<p><strong>Source code:</strong> <a class="reference external" href="http://hg.python.org/cpython/file/3.3/Lib/site.py">Lib/site.py</a></p>
<hr class="docutils" />
<p><strong>This module is automatically imported during initialization.</strong> The automatic
import can be suppressed using the interpreter’s <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><em class="xref std std-option">-S</em></a> option.</p>
<p id="index-0">Importing this module will append site-specific paths to the module search path
and add a few builtins, unless <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><em class="xref std std-option">-S</em></a> was used. In that case, this module
can be safely imported with no automatic modifications to the module search path
or additions to the builtins. To explicitly trigger the usual site-specific
additions, call the <a class="reference internal" href="#site.main" title="site.main"><tt class="xref py py-func docutils literal"><span class="pre">site.main()</span></tt></a> function.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.3:</span> Importing the module used to trigger paths manipulation even when using
<a class="reference internal" href="../using/cmdline.html#cmdoption-S"><em class="xref std std-option">-S</em></a>.</p>
<p id="index-1">It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses <tt class="docutils literal"><span class="pre">sys.prefix</span></tt> and <tt class="docutils literal"><span class="pre">sys.exec_prefix</span></tt>; empty heads
are skipped. For the tail part, it uses the empty string and then
<tt class="file docutils literal"><span class="pre">lib/site-packages</span></tt> (on Windows) or
<tt class="file docutils literal"><span class="pre">lib/python|version|/site-packages</span></tt> and then <tt class="file docutils literal"><span class="pre">lib/site-python</span></tt> (on
Unix and Macintosh). For each of the distinct head-tail combinations, it sees
if it refers to an existing directory, and if so, adds it to <tt class="docutils literal"><span class="pre">sys.path</span></tt> and
also inspects the newly added path for configuration files.</p>
<p>If a file named “pyvenv.cfg” exists one directory above sys.executable,
sys.prefix and sys.exec_prefix are set to that directory and
it is also checked for site-packages and site-python (sys.base_prefix and
sys.base_exec_prefix will always be the “real” prefixes of the Python
installation). If “pyvenv.cfg” (a bootstrap configuration file) contains
the key “include-system-site-packages” set to anything other than “false”
(case-insensitive), the system-level prefixes will still also be
searched for site-packages; otherwise they won’t.</p>
<p>A path configuration file is a file whose name has the form <tt class="file docutils literal"><em><span class="pre">name</span></em><span class="pre">.pth</span></tt>
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to <tt class="docutils literal"><span class="pre">sys.path</span></tt>. Non-existing items
are never added to <tt class="docutils literal"><span class="pre">sys.path</span></tt>, and no check is made that the item refers to a
directory rather than a file. No item is added to <tt class="docutils literal"><span class="pre">sys.path</span></tt> more than
once. Blank lines and lines beginning with <tt class="docutils literal"><span class="pre">#</span></tt> are skipped. Lines starting
with <tt class="docutils literal"><span class="pre">import</span></tt> (followed by space or tab) are executed.</p>
<p id="index-2">For example, suppose <tt class="docutils literal"><span class="pre">sys.prefix</span></tt> and <tt class="docutils literal"><span class="pre">sys.exec_prefix</span></tt> are set to
<tt class="file docutils literal"><span class="pre">/usr/local</span></tt>. The Python X.Y library is then installed in
<tt class="file docutils literal"><span class="pre">/usr/local/lib/python</span><em><span class="pre">X.Y</span></em></tt>. Suppose this has
a subdirectory <tt 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></tt> with three
subsubdirectories, <tt class="file docutils literal"><span class="pre">foo</span></tt>, <tt class="file docutils literal"><span class="pre">bar</span></tt> and <tt class="file docutils literal"><span class="pre">spam</span></tt>, and two path
configuration files, <tt class="file docutils literal"><span class="pre">foo.pth</span></tt> and <tt class="file docutils literal"><span class="pre">bar.pth</span></tt>. Assume
<tt class="file docutils literal"><span class="pre">foo.pth</span></tt> contains the following:</p>
<div class="highlight-none"><div class="highlight"><pre># foo package configuration
foo
bar
bletch
</pre></div>
</div>
<p>and <tt class="file docutils literal"><span class="pre">bar.pth</span></tt> contains:</p>
<div class="highlight-none"><div class="highlight"><pre># bar package configuration
bar
</pre></div>
</div>
<p>Then the following version-specific directories are added to
<tt class="docutils literal"><span class="pre">sys.path</span></tt>, in this order:</p>
<div class="highlight-none"><div class="highlight"><pre>/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo
</pre></div>
</div>
<p>Note that <tt class="file docutils literal"><span class="pre">bletch</span></tt> is omitted because it doesn’t exist; the <tt class="file docutils literal"><span class="pre">bar</span></tt>
directory precedes the <tt class="file docutils literal"><span class="pre">foo</span></tt> directory because <tt class="file docutils literal"><span class="pre">bar.pth</span></tt> comes
alphabetically before <tt class="file docutils literal"><span class="pre">foo.pth</span></tt>; and <tt class="file docutils literal"><span class="pre">spam</span></tt> is omitted because it is
not mentioned in either path configuration file.</p>
<p id="index-3">After these path manipulations, an attempt is made to import a module named
<tt class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></tt>, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory. If this import fails with an <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a> exception, it is
silently ignored.</p>
<p id="index-4">After this, an attempt is made to import a module named <tt class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></tt>,
which can perform arbitrary user-specific customizations, if
<a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><tt class="xref py py-data docutils literal"><span class="pre">ENABLE_USER_SITE</span></tt></a> is true. This file is intended to be created in the
user site-packages directory (see below), which is part of <tt class="docutils literal"><span class="pre">sys.path</span></tt> unless
disabled by <a class="reference internal" href="../using/cmdline.html#cmdoption-s"><em class="xref std std-option">-s</em></a>. An <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a> will be silently ignored.</p>
<p>Note that for some non-Unix systems, <tt class="docutils literal"><span class="pre">sys.prefix</span></tt> and <tt class="docutils literal"><span class="pre">sys.exec_prefix</span></tt> are
empty, and the path manipulations are skipped; however the import of
<tt class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></tt> and <tt class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></tt> is still attempted.</p>
<dl class="data">
<dt id="site.PREFIXES">
<tt class="descclassname">site.</tt><tt class="descname">PREFIXES</tt><a class="headerlink" href="#site.PREFIXES" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of prefixes for site-packages directories.</p>
</dd></dl>
<dl class="data">
<dt id="site.ENABLE_USER_SITE">
<tt class="descclassname">site.</tt><tt class="descname">ENABLE_USER_SITE</tt><a class="headerlink" href="#site.ENABLE_USER_SITE" title="Permalink to this definition">¶</a></dt>
<dd><p>Flag showing the status of the user site-packages directory. <tt class="xref docutils literal"><span class="pre">True</span></tt> means
that it is enabled and was added to <tt class="docutils literal"><span class="pre">sys.path</span></tt>. <tt class="xref docutils literal"><span class="pre">False</span></tt> means that it
was disabled by user request (with <a class="reference internal" href="../using/cmdline.html#cmdoption-s"><em class="xref std std-option">-s</em></a> or
<span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNOUSERSITE"><tt class="xref std std-envvar docutils literal"><span class="pre">PYTHONNOUSERSITE</span></tt></a>). <tt class="xref docutils literal"><span class="pre">None</span></tt> means it was disabled for security
reasons (mismatch between user or group id and effective id) or by an
administrator.</p>
</dd></dl>
<dl class="data">
<dt id="site.USER_SITE">
<tt class="descclassname">site.</tt><tt class="descname">USER_SITE</tt><a class="headerlink" href="#site.USER_SITE" title="Permalink to this definition">¶</a></dt>
<dd><p>Path to the user site-packages for the running Python. Can be <tt class="xref docutils literal"><span class="pre">None</span></tt> if
<a class="reference internal" href="#site.getusersitepackages" title="site.getusersitepackages"><tt class="xref py py-func docutils literal"><span class="pre">getusersitepackages()</span></tt></a> hasn’t been called yet. Default value is
<tt 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></tt> for UNIX and non-framework Mac
OS X builds, <tt 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></tt> for Mac
framework builds, and <tt 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></tt>
on Windows. This directory is a site directory, which means that
<tt class="file docutils literal"><span class="pre">.pth</span></tt> files in it will be processed.</p>
</dd></dl>
<dl class="data">
<dt id="site.USER_BASE">
<tt class="descclassname">site.</tt><tt class="descname">USER_BASE</tt><a class="headerlink" href="#site.USER_BASE" title="Permalink to this definition">¶</a></dt>
<dd><p>Path to the base directory for the user site-packages. Can be <tt class="xref docutils literal"><span class="pre">None</span></tt> if
<a class="reference internal" href="#site.getuserbase" title="site.getuserbase"><tt class="xref py py-func docutils literal"><span class="pre">getuserbase()</span></tt></a> hasn’t been called yet. Default value is
<tt class="file docutils literal"><span class="pre">~/.local</span></tt> for UNIX and Mac OS X non-framework builds,
<tt class="file docutils literal"><span class="pre">~/Library/Python/</span><em><span class="pre">X.Y</span></em></tt> for Mac framework builds, and
<tt class="file docutils literal"><em><span class="pre">%APPDATA%</span></em><span class="pre">\Python</span></tt> for Windows. This value is used by Distutils to
compute the installation directories for scripts, data files, Python modules,
etc. for the <a class="reference internal" href="../install/index.html#inst-alt-install-user"><em>user installation scheme</em></a>.
See also <span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONUSERBASE"><tt class="xref std std-envvar docutils literal"><span class="pre">PYTHONUSERBASE</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="site.main">
<tt class="descclassname">site.</tt><tt class="descname">main</tt><big>(</big><big>)</big><a class="headerlink" href="#site.main" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds all the standard site-specific directories to the module search
path. This function is called automatically when this module is imported,
unless the <strong class="program">python</strong> interpreter was started with the <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><em class="xref std std-option">-S</em></a>
flag.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.3:</span> This function used to be called unconditionnally.</p>
</dd></dl>
<dl class="function">
<dt id="site.addsitedir">
<tt class="descclassname">site.</tt><tt class="descname">addsitedir</tt><big>(</big><em>sitedir</em>, <em>known_paths=None</em><big>)</big><a class="headerlink" href="#site.addsitedir" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a directory to sys.path and process its <tt class="file docutils literal"><span class="pre">.pth</span></tt> files. Typically
used in <tt class="xref py py-mod docutils literal"><span class="pre">sitecustomize</span></tt> or <tt class="xref py py-mod docutils literal"><span class="pre">usercustomize</span></tt> (see above).</p>
</dd></dl>
<dl class="function">
<dt id="site.getsitepackages">
<tt class="descclassname">site.</tt><tt class="descname">getsitepackages</tt><big>(</big><big>)</big><a class="headerlink" href="#site.getsitepackages" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list containing all global site-packages directories (and possibly
site-python).</p>
<p class="versionadded">
<span class="versionmodified">New in version 3.2.</span> </p>
</dd></dl>
<dl class="function">
<dt id="site.getuserbase">
<tt class="descclassname">site.</tt><tt class="descname">getuserbase</tt><big>(</big><big>)</big><a class="headerlink" href="#site.getuserbase" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the path of the user base directory, <a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><tt class="xref py py-data docutils literal"><span class="pre">USER_BASE</span></tt></a>. If it is not
initialized yet, this function will also set it, respecting
<span class="target" id="index-7"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONUSERBASE"><tt class="xref std std-envvar docutils literal"><span class="pre">PYTHONUSERBASE</span></tt></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 3.2.</span> </p>
</dd></dl>
<dl class="function">
<dt id="site.getusersitepackages">
<tt class="descclassname">site.</tt><tt class="descname">getusersitepackages</tt><big>(</big><big>)</big><a class="headerlink" href="#site.getusersitepackages" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the path of the user-specific site-packages directory,
<a class="reference internal" href="#site.USER_SITE" title="site.USER_SITE"><tt class="xref py py-data docutils literal"><span class="pre">USER_SITE</span></tt></a>. If it is not initialized yet, this function will also set
it, respecting <span class="target" id="index-8"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNOUSERSITE"><tt class="xref std std-envvar docutils literal"><span class="pre">PYTHONNOUSERSITE</span></tt></a> and <a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><tt class="xref py py-data docutils literal"><span class="pre">USER_BASE</span></tt></a>.</p>
<p class="versionadded">
<span class="versionmodified">New in version 3.2.</span> </p>
</dd></dl>
<p>The <a class="reference internal" href="#module-site" title="site: Module responsible for site-specific configuration."><tt class="xref py py-mod docutils literal"><span class="pre">site</span></tt></a> module also provides a way to get the user directories from the
command line:</p>
<div class="highlight-sh"><div class="highlight"><pre><span class="nv">$ </span>python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages
</pre></div>
</div>
<p>If it is called without arguments, it will print the contents of
<a class="reference internal" href="sys.html#sys.path" title="sys.path"><tt class="xref py py-data docutils literal"><span class="pre">sys.path</span></tt></a> on the standard output, followed by the value of
<a class="reference internal" href="#site.USER_BASE" title="site.USER_BASE"><tt class="xref py py-data docutils literal"><span class="pre">USER_BASE</span></tt></a> and whether the directory exists, then the same thing for
<a class="reference internal" href="#site.USER_SITE" title="site.USER_SITE"><tt class="xref py py-data docutils literal"><span class="pre">USER_SITE</span></tt></a>, and finally the value of <a class="reference internal" href="#site.ENABLE_USER_SITE" title="site.ENABLE_USER_SITE"><tt class="xref py py-data docutils literal"><span class="pre">ENABLE_USER_SITE</span></tt></a>.</p>
<dl class="cmdoption">
<dt id="cmdoption-site--user-base">
<tt class="descname">--user-base</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-site--user-base" title="Permalink to this definition">¶</a></dt>
<dd><p>Print the path to the user base directory.</p>
</dd></dl>
<dl class="cmdoption">
<dt id="cmdoption-site--user-site">
<tt class="descname">--user-site</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-site--user-site" title="Permalink to this definition">¶</a></dt>
<dd><p>Print the path to the user site-packages directory.</p>
</dd></dl>
<p>If both options are given, user base and user site will be printed (always in
this order), separated by <a class="reference internal" href="os.html#os.pathsep" title="os.pathsep"><tt class="xref py py-data docutils literal"><span class="pre">os.pathsep</span></tt></a>.</p>
<p>If any option is given, the script will exit with one of these values: <tt class="docutils literal"><span class="pre">O</span></tt> if
the user site-packages directory is enabled, <tt class="docutils literal"><span class="pre">1</span></tt> if it was disabled by the
user, <tt class="docutils literal"><span class="pre">2</span></tt> if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><span class="target" id="index-9"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0370"><strong>PEP 370</strong></a> – Per user site-packages directory</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="inspect.html"
title="previous chapter">28.12. <tt class="docutils literal docutils literal docutils literal"><span class="pre">inspect</span></tt> — Inspect live objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="fpectl.html"
title="next chapter">28.14. <tt class="docutils literal docutils literal docutils literal"><span class="pre">fpectl</span></tt> — Floating point exception control</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/library/site.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="fpectl.html" title="28.14. fpectl — Floating point exception control"
>next</a> |</li>
<li class="right" >
<a href="inspect.html" title="28.12. inspect — Inspect live objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="http://www.python.org/">Python</a> »</li>
<li><a href="../index.html">3.3.0 Documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="python.html" >28. Python Runtime Services</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2012, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Sep 29, 2012.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Mageia
>
3
>
i586
>
media
>
core-updates
>
by-pkgid
>
50402eac2a16508b365658612a898528
>
files
>
804
