/usr/share/doc/python-distribute/html/python3.html is in python-distribute-doc 0.6.24-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 | <!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>Supporting both Python 2 and Python 3 with Distribute — Distribute documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.6.24',
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>
<link rel="top" title="Distribute documentation" href="index.html" />
<link rel="next" title="Using Distribute in your project" href="using.html" />
<link rel="prev" title="Roadmap" href="roadmap.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="using.html" title="Using Distribute in your project"
accesskey="N">next</a></li>
<li class="right" >
<a href="roadmap.html" title="Roadmap"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Distribute</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="supporting-both-python-2-and-python-3-with-distribute">
<h1>Supporting both Python 2 and Python 3 with Distribute<a class="headerlink" href="#supporting-both-python-2-and-python-3-with-distribute" title="Permalink to this headline">¶</a></h1>
<p>Starting with version 0.6.2, Distribute supports Python 3. Installing and
using distribute for Python 3 code works exactly the same as for Python 2
code, but Distribute also helps you to support Python 2 and Python 3 from
the same source code by letting you run 2to3 on the code as a part of the
build process, by setting the keyword parameter <tt class="docutils literal"><span class="pre">use_2to3</span></tt> to True.</p>
<div class="section" id="distribute-as-help-during-porting">
<h2>Distribute as help during porting<a class="headerlink" href="#distribute-as-help-during-porting" title="Permalink to this headline">¶</a></h2>
<p>Distribute can make the porting process much easier by automatically running
2to3 as a part of the test running. To do this you need to configure the
setup.py so that you can run the unit tests with <tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">test</span></tt>.</p>
<p>See <a class="reference internal" href="setuptools.html#test"><em>test - Build package and run a unittest suite</em></a> for more information on this.</p>
<p>Once you have the tests running under Python 2, you can add the use_2to3
keyword parameters to setup(), and start running the tests under Python 3.
The test command will now first run the build command during which the code
will be converted with 2to3, and the tests will then be run from the build
directory, as opposed from the source directory as is normally done.</p>
<p>Distribute will convert all Python files, and also all doctests in Python
files. However, if you have doctests located in separate text files, these
will not automatically be converted. By adding them to the
<tt class="docutils literal"><span class="pre">convert_2to3_doctests</span></tt> keyword parameter Distrubute will convert them as
well.</p>
<p>By default, the conversion uses all fixers in the <tt class="docutils literal"><span class="pre">lib2to3.fixers</span></tt> package.
To use additional fixers, the parameter <tt class="docutils literal"><span class="pre">use_2to3_fixers</span></tt> can be set
to a list of names of packages containing fixers. To exclude fixers, the
parameter <tt class="docutils literal"><span class="pre">use_2to3_exclude_fixers</span></tt> can be set to fixer names to be
skipped.</p>
<p>A typical setup.py can look something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">'your.module'</span><span class="p">,</span>
<span class="n">version</span> <span class="o">=</span> <span class="s">'1.0'</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span><span class="s">'This is your awesome module'</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s">'You'</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s">'your@email'</span><span class="p">,</span>
<span class="n">package_dir</span> <span class="o">=</span> <span class="p">{</span><span class="s">''</span><span class="p">:</span> <span class="s">'src'</span><span class="p">},</span>
<span class="n">packages</span> <span class="o">=</span> <span class="p">[</span><span class="s">'your'</span><span class="p">,</span> <span class="s">'you.module'</span><span class="p">],</span>
<span class="n">test_suite</span> <span class="o">=</span> <span class="s">'your.module.tests'</span><span class="p">,</span>
<span class="n">use_2to3</span> <span class="o">=</span> <span class="bp">True</span><span class="p">,</span>
<span class="n">convert_2to3_doctests</span> <span class="o">=</span> <span class="p">[</span><span class="s">'src/your/module/README.txt'</span><span class="p">],</span>
<span class="n">use_2to3_fixers</span> <span class="o">=</span> <span class="p">[</span><span class="s">'your.fixers'</span><span class="p">],</span>
<span class="n">use_2to3_exclude_fixers</span> <span class="o">=</span> <span class="p">[</span><span class="s">'lib2to3.fixes.fix_import'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="section" id="differential-conversion">
<h3>Differential conversion<a class="headerlink" href="#differential-conversion" title="Permalink to this headline">¶</a></h3>
<p>Note that a file will only be copied and converted during the build process
if the source file has been changed. If you add a file to the doctests
that should be converted, it will not be converted the next time you run
the tests, since it hasn’t been modified. You need to remove it from the
build directory. Also if you run the build, install or test commands before
adding the use_2to3 parameter, you will have to remove the build directory
before you run the test command, as the files otherwise will seem updated,
and no conversion will happen.</p>
<p>In general, if code doesn’t seem to be converted, deleting the build directory
and trying again is a good saferguard against the build directory getting
“out of sync” with the source directory.</p>
</div>
</div>
<div class="section" id="distributing-python-3-modules">
<h2>Distributing Python 3 modules<a class="headerlink" href="#distributing-python-3-modules" title="Permalink to this headline">¶</a></h2>
<p>You can distribute your modules with Python 3 support in different ways. A
normal source distribution will work, but can be slow in installing, as the
2to3 process will be run during the install. But you can also distribute
the module in binary format, such as a binary egg. That egg will contain the
already converted code, and hence no 2to3 conversion is needed during install.</p>
</div>
<div class="section" id="advanced-features">
<h2>Advanced features<a class="headerlink" href="#advanced-features" title="Permalink to this headline">¶</a></h2>
<p>If you don’t want to run the 2to3 conversion on the doctests in Python files,
you can turn that off by setting <tt class="docutils literal"><span class="pre">setuptools.use_2to3_on_doctests</span> <span class="pre">=</span> <span class="pre">False</span></tt>.</p>
</div>
<div class="section" id="note-on-compatibility-with-setuptools">
<h2>Note on compatibility with setuptools<a class="headerlink" href="#note-on-compatibility-with-setuptools" title="Permalink to this headline">¶</a></h2>
<p>Setuptools do not know about the new keyword parameters to support Python 3.
As a result it will warn about the unknown keyword parameters if you use
setuptools instead of Distribute under Python 2. This is not an error, and
install process will continue as normal, but if you want to get rid of that
error this is easy. Simply conditionally add the new parameters into an extra
dict and pass that dict into setup():</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">import</span> <span class="n">setup</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="n">extra</span> <span class="o">=</span> <span class="p">{}</span>
<span class="k">if</span> <span class="n">sys</span><span class="o">.</span><span class="n">version_info</span> <span class="o">>=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,):</span>
<span class="n">extra</span><span class="p">[</span><span class="s">'use_2to3'</span><span class="p">]</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">extra</span><span class="p">[</span><span class="s">'convert_2to3_doctests'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s">'src/your/module/README.txt'</span><span class="p">]</span>
<span class="n">extra</span><span class="p">[</span><span class="s">'use_2to3_fixers'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s">'your.fixers'</span><span class="p">]</span>
<span class="n">setup</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">'your.module'</span><span class="p">,</span>
<span class="n">version</span> <span class="o">=</span> <span class="s">'1.0'</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span><span class="s">'This is your awesome module'</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s">'You'</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s">'your@email'</span><span class="p">,</span>
<span class="n">package_dir</span> <span class="o">=</span> <span class="p">{</span><span class="s">''</span><span class="p">:</span> <span class="s">'src'</span><span class="p">},</span>
<span class="n">packages</span> <span class="o">=</span> <span class="p">[</span><span class="s">'your'</span><span class="p">,</span> <span class="s">'you.module'</span><span class="p">],</span>
<span class="n">test_suite</span> <span class="o">=</span> <span class="s">'your.module.tests'</span><span class="p">,</span>
<span class="o">**</span><span class="n">extra</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This way the parameters will only be used under Python 3, where you have to
use Distribute.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Supporting both Python 2 and Python 3 with Distribute</a><ul>
<li><a class="reference internal" href="#distribute-as-help-during-porting">Distribute as help during porting</a><ul>
<li><a class="reference internal" href="#differential-conversion">Differential conversion</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distributing-python-3-modules">Distributing Python 3 modules</a></li>
<li><a class="reference internal" href="#advanced-features">Advanced features</a></li>
<li><a class="reference internal" href="#note-on-compatibility-with-setuptools">Note on compatibility with setuptools</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="roadmap.html"
title="previous chapter">Roadmap</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="using.html"
title="next chapter">Using Distribute in your project</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/python3.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" />
<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="using.html" title="Using Distribute in your project"
>next</a></li>
<li class="right" >
<a href="roadmap.html" title="Roadmap"
>previous</a> |</li>
<li><a href="index.html">Distribute</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2011, The fellowship of the packaging.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.
</div>
</body>
</html>
|