-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathPython3.html
218 lines (182 loc) · 14.2 KB
/
Python3.html
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
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Python 3</title>
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/custom.css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Development and Release Cycle" href="DevelopmentAndReleaseCycle.html" />
<link rel="prev" title="Doxygen Setup" href="DoxygenSetup.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head><body>
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org"><img src="_static/Mantid_Logo_Transparent.png">
</a>
<span class="navbar-text navbar-version pull-left"><b>master</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="index.html">Home</a></li>
<li><a href="http://download.mantidproject.org">Download</a></li>
<li><a href="http://www.mantidproject.org">Wiki</a></li>
<li><a href="http://docs.mantidproject.org">User Documentation</a></li>
<li><a href="http://www.mantidproject.org/Contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<div class="section" id="python-3">
<h1>Python 3<a class="headerlink" href="#python-3" title="Permalink to this headline">¶</a></h1>
<p>This is now the default configuration but we currently retain the ability to build against
Python 2.</p>
<p>Python 2 has an <a class="reference external" href="http://legacy.python.org/dev/peps/pep-0373/">end-of-life date set for 2020</a>
and now that most third-party packages support both 2 and 3 we are starting to think about a
migration strategy for Mantid.</p>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#building-against-python-3" id="id2">Building Against Python 3</a></li>
<li><a class="reference internal" href="#supporting-python-2-and-3" id="id3">Supporting Python 2 and 3</a></li>
<li><a class="reference internal" href="#migrating-from-python-2-to-3" id="id4">Migrating From Python 2 to 3</a></li>
</ul>
</div>
<div class="section" id="building-against-python-3">
<h2><a class="toc-backref" href="#id2">Building Against Python 3</a><a class="headerlink" href="#building-against-python-3" title="Permalink to this headline">¶</a></h2>
<p>For Linux/macOS ensure dependencies are update to date.
On Windows all of the required packages are in the third-party bundle that will be fetched for you.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do not install python packages via <code class="docutils literal notranslate"><span class="pre">pip</span></code>. Install packages only from the system repositories.</p>
</div>
<p>To build from the command line run cmake as standard but with the additional option <code class="docutils literal notranslate"><span class="pre">-DWITH_PYTHON3=ON</span></code>.</p>
<p>To build from the GUI set the source and build directories as usual
but before clicking configure click “Add Entry” and add an entry with the name <code class="docutils literal notranslate"><span class="pre">WITH_PYTHON3</span></code> of type <code class="docutils literal notranslate"><span class="pre">BOOL</span></code>
and ensure the Value is checked. Now proceed to configure and generate as usual.</p>
</div>
<div class="section" id="supporting-python-2-and-3">
<h2><a class="toc-backref" href="#id3">Supporting Python 2 and 3</a><a class="headerlink" href="#supporting-python-2-and-3" title="Permalink to this headline">¶</a></h2>
<p>Python 3 introduces many exciting new features. For a full description see the official Python 3
changes document. For a shorter overview see
<a class="reference external" href="https://asmeurer.github.io/python3-presentation/slides.html#1">here</a> or
<a class="reference external" href="http://python3porting.com/differences.html">here</a>.</p>
<p>Some features of Python 3 have been backported to Python 2.x within the
<a class="reference external" href="https://docs.python.org/2.7/library/__future__.html?highlight=future#module-__future__">__future__</a>
module. These make it easier to write code that is compatible with both versions.</p>
<p>This cheat sheet provides helpful examples of how to write code in a 2/3 compatible manner. Where an
option is given to use either the <a class="reference external" href="https://pythonhosted.org/six/">six</a> or
<a class="reference external" href="https://pypi.python.org/pypi/future">future</a> (not to be confused with <code class="docutils literal notranslate"><span class="pre">__future__</span></code>!) modules
then <code class="docutils literal notranslate"><span class="pre">six</span></code> is used.</p>
<p>All new code should be written to be compatible with Python 2 & 3 and as a minimum the first import
line of the module should be:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="p">(</span><span class="n">absolute_import</span><span class="p">,</span> <span class="n">division</span><span class="p">,</span> <span class="n">print_function</span><span class="p">)</span>
</pre></div>
</div>
<p>It is quite common to also see <code class="docutils literal notranslate"><span class="pre">unicode_literals</span></code> in the above import list, however, when running
under Python 2 <code class="docutils literal notranslate"><span class="pre">Boost.Python</span></code> will not automatically convert a Python <code class="docutils literal notranslate"><span class="pre">str</span></code> to C++ <code class="docutils literal notranslate"><span class="pre">std::string</span></code>
automatically if the string is unicode. When running with Python 3 <code class="docutils literal notranslate"><span class="pre">Boost.Python</span></code> will do this
conversion automatically for unicode strings so this is in fact not a huge issue going forward.</p>
</div>
<div class="section" id="migrating-from-python-2-to-3">
<h2><a class="toc-backref" href="#id4">Migrating From Python 2 to 3</a><a class="headerlink" href="#migrating-from-python-2-to-3" title="Permalink to this headline">¶</a></h2>
<p>One way to migrate a file from python 2 to 3 is as follows…</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<div class="last line-block">
<div class="line">To perform the following procedure on windows:</div>
<div class="line">1. Git Bash or similar will be required.</div>
<div class="line">2. To run the <code class="docutils literal notranslate"><span class="pre">2to3</span></code> script you will need to start the command-prompt.bat in the build directory and run <code class="docutils literal notranslate"><span class="pre">%PYTHONHOME%\Scripts\2to3</span></code></div>
</div>
</div>
<p>Run the following script to run the python 2 to 3 translation tool and rename the file to <code class="docutils literal notranslate"><span class="pre">filename.py.bak</span></code></p>
<div class="highlight-sh notranslate"><div class="highlight"><pre>2to3 --no-diffs -w filename.py
mv filename.py<span class="o">{</span>,.bak<span class="o">}</span><span class="p">;</span>
</pre></div>
</div>
<p>Run <strong>one</strong> of the following commands to append the import statement listed above.</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre>awk <span class="s1">'/(from|import)/ && !x {print "from __future__ import (absolute_import, division, print_function)\n"; x=1} 1'</span> <span class="se">\</span>
filename.py.bak > filename.py
</pre></div>
</div>
<p><strong>or</strong></p>
<div class="highlight-sh notranslate"><div class="highlight"><pre>sed -i <span class="s1">'0,/^import\|from.*/s/^import\|from.*/from __future__ import (absolute_import, division, print_function)\n&/'</span> filename.py
</pre></div>
</div>
<p>Check each changed block,</p>
<ul class="simple">
<li>If any change has replaced <code class="docutils literal notranslate"><span class="pre">xrange</span></code> with <code class="docutils literal notranslate"><span class="pre">range</span></code> then add <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">six.moves</span> <span class="pre">import</span> <span class="pre">range</span></code>
to the imports list</li>
<li>If any change has replaced <code class="docutils literal notranslate"><span class="pre">ifilterfalse</span></code> with <code class="docutils literal notranslate"><span class="pre">filterfalse</span></code> from <code class="docutils literal notranslate"><span class="pre">itertools</span></code> then replace a
statement like <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">itertools</span> <span class="pre">import</span> <span class="pre">filterfalse</span></code> with <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">six.moves</span> <span class="pre">import</span> <span class="pre">filterfalse</span></code> in the
imports list. There are more cases like this documented <a class="reference external" href="https://pythonhosted.org/six/#module-six.moves">here</a>.</li>
<li>If any change has replaced <code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">k,</span> <span class="pre">v</span> <span class="pre">in</span> <span class="pre">knights.iteritems()</span></code> with <code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">k,</span> <span class="pre">v</span> <span class="pre">in</span> <span class="pre">knights.items()</span></code>
then add <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">six</span> <span class="pre">import</span> <span class="pre">iteritems</span></code> to the import list and update the replacement to
<code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">k,</span> <span class="pre">v</span> <span class="pre">in</span> <span class="pre">iteritems(knights)</span></code>.</li>
</ul>
<p>In some cases like <code class="docutils literal notranslate"><span class="pre">range</span></code>, pylint will complain about <cite>Replacing builtin ‘range’</cite> or similar.
Make sure to put the proper ignore statement on that line using <code class="docutils literal notranslate"><span class="pre">#pylint:</span> <span class="pre">disable=redefined-builtin</span></code>.</p>
<p>Check the code still runs as expected in Python 2.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal notranslate"><span class="pre">2to3</span></code> will try to keep the type of the objects the same. So, for example <code class="docutils literal notranslate"><span class="pre">range(5)</span></code> will
become <code class="docutils literal notranslate"><span class="pre">list(range(5))</span></code>. This is not necessary if you use it just for iteration. Things like
<code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">i</span> <span class="pre">in</span> <span class="pre">range(5)</span></code> will work in both versions of Python, you don’t need to transform it into a
list.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li>
<a href="DoxygenSetup.html" title="Previous Chapter: Doxygen Setup"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Doxygen Setup</span>
</a>
</li>
<li>
<a href="DevelopmentAndReleaseCycle.html" title="Next Chapter: Development and Release Cycle"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Development a... »</span>
</a>
</li>
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>