Sophie

Sophie

distrib > Mandriva > 2010.1 > x86_64 > media > contrib-backports > by-pkgid > 3ba3bd1608c672ba2129b098a48e9e4d > files > 791

python3-docs-3.2.2-3mdv2010.2.noarch.rpm



<!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>27.13. site — Site-specific configuration hook &mdash; Python v3.2.2 documentation</title>
    <link rel="stylesheet" href="../_static/default.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.2.2',
        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.2.2 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.2.2 documentation" href="../index.html" />
    <link rel="up" title="27. Python Runtime Services" href="python.html" />
    <link rel="next" title="27.14. fpectl — Floating point exception control" href="fpectl.html" />
    <link rel="prev" title="27.12. inspect — Inspect live objects" href="inspect.html" />
    <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
 

  </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="27.14. fpectl — Floating point exception control"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="inspect.html" title="27.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="../index.html">Python v3.2.2 documentation</a> &raquo;</li>

          <li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
          <li><a href="python.html" accesskey="U">27. Python Runtime Services</a> &raquo;</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>27.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> &#8212; 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.2/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&#8217;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.</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>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&#8217;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&#8217;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&#8217;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.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> &#8211; 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">27.12. <tt class="docutils literal docutils literal docutils literal"><span class="pre">inspect</span></tt> &#8212; Inspect live objects</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="fpectl.html"
                        title="next chapter">27.14. <tt class="docutils literal docutils literal docutils literal"><span class="pre">fpectl</span></tt> &#8212; 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="27.14. fpectl — Floating point exception control"
             >next</a> |</li>
        <li class="right" >
          <a href="inspect.html" title="27.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="../index.html">Python v3.2.2 documentation</a> &raquo;</li>

          <li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
          <li><a href="python.html" >27. Python Runtime Services</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
    &copy; <a href="../copyright.html">Copyright</a> 1990-2011, 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 04, 2011.
    <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>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional