##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Document that py3compat is deprecated...
Thomas Kluyver -
Show More
Show file before | Show file after | Hide comments
@@ -1,22 +1,21 b''
1 1 .. _developer_guide:
2 2
3 3 =====================================================
4 4 Developer's guide for third party tools and libraries
5 5 =====================================================
6 6
7 7 .. important::
8 8
9 9 This guide contains information for developers of third party tools and
10 10 libraries that use IPython. Alternatively, documentation for core
11 11 **IPython** development can be found in the :doc:`../coredev/index`.
12 12
13 13 .. toctree::
14 14 :maxdepth: 1
15 15
16 16 how_ipython_works
17 17 wrapperkernels
18 18 execution
19 19 lexer
20 pycompat
21 20 config
22 21 inputhook_app
Show file before | Show file after | Hide comments
@@ -1,233 +1,31 b''
1 :orphan:
2
1 3 Writing code for Python 2 and 3
2 4 ===============================
3 5
4 6 .. module:: IPython.utils.py3compat
5 7 :synopsis: Python 2 & 3 compatibility helpers
6 8
7 .. data:: PY3
8
9 Boolean indicating whether we're currently in Python 3.
10
11 Iterators
12 ---------
13
14 Many built in functions and methods in Python 2 come in pairs, one
15 returning a list, and one returning an iterator (e.g. :func:`range` and
16 :func:`python:xrange`). In Python 3, there is usually only the iterator form,
17 but it has the name which gives a list in Python 2 (e.g. :func:`range`).
18
19 The way to write compatible code depends on what you need:
20
21 * A list, e.g. for serialisation, or to test if something is in it.
22 * Iteration, but it will never be used for very many items, so efficiency
23 isn't especially important.
24 * Iteration over many items, where efficiency is important.
25
26 ================ ================= =======================
27 list iteration (small) iteration(large)
28 ================ ================= =======================
29 list(range(n)) range(n) py3compat.xrange(n)
30 list(map(f, it)) map(f, it) --
31 list(zip(a, b)) zip(a, b) --
32 list(d.items()) d.items() py3compat.iteritems(d)
33 list(d.values()) d.values() py3compat.itervalues(d)
34 ================ ================= =======================
35
36 Iterating over a dictionary yields its keys, so there is rarely a need
37 to use :meth:`dict.keys` or :meth:`dict.iterkeys`.
38
39 Avoid using :func:`map` to cause function side effects. This is more
40 clearly written with a simple for loop.
41
42 .. data:: xrange
43
44 A reference to ``range`` on Python 3, and :func:`python:xrange` on Python 2.
45
46 .. function:: iteritems(d)
47 itervalues(d)
48
49 Iterate over (key, value) pairs of a dictionary, or just over values.
50 ``iterkeys`` is not defined: iterating over the dictionary yields its keys.
51
52 Changed standard library locations
53 ----------------------------------
54
55 Several parts of the standard library have been renamed and moved. This
56 is a short list of things that we're using. A couple of them have names
57 in :mod:`IPython.utils.py3compat`, so you don't need both
58 imports in each module that uses them.
59
60 ================== ============ ===========
61 Python 2 Python 3 py3compat
62 ================== ============ ===========
63 :func:`raw_input` input input
64 :mod:`__builtin__` builtins builtin_mod
65 :mod:`StringIO` io
66 :mod:`Queue` queue
67 :mod:`cPickle` pickle
68 :mod:`thread` _thread
69 :mod:`copy_reg` copyreg
70 :mod:`urlparse` urllib.parse
71 :mod:`repr` reprlib
72 :mod:`Tkinter` tkinter
73 :mod:`Cookie` http.cookie
74 :mod:`_winreg` winreg
75 ================== ============ ===========
76
77 Be careful with StringIO: :class:`io.StringIO` is available in Python 2.7,
78 but it behaves differently from :class:`StringIO.StringIO`, and much of
79 our code assumes the use of the latter on Python 2. So a try/except on
80 the import may cause problems.
81
82 .. function:: input
83
84 Behaves like :func:`python:raw_input` on Python 2.
85
86 .. data:: builtin_mod
87 builtin_mod_name
88
89 A reference to the module containing builtins, and its name as a string.
90
91 Unicode
92 -------
93
94 Always be explicit about what is text (unicode) and what is bytes.
95 *Encoding* goes from unicode to bytes, and *decoding* goes from bytes
96 to unicode.
97
98 To open files for reading or writing text, use :func:`io.open`, which is
99 the Python 3 builtin ``open`` function, available on Python 2 as well.
100 We almost always need to specify the encoding parameter, because the
101 default is platform dependent.
102
103 We have several helper functions for converting between string types. They all
104 use the encoding from :func:`IPython.utils.encoding.getdefaultencoding` by default,
105 and the ``errors='replace'`` option to do best-effort conversions for the user's
106 system.
107
108 .. function:: unicode_to_str(u, encoding=None)
109 str_to_unicode(s, encoding=None)
110
111 Convert between unicode and the native str type. No-ops on Python 3.
112
113 .. function:: str_to_bytes(s, encoding=None)
114 bytes_to_str(u, encoding=None)
115
116 Convert between bytes and the native str type. No-ops on Python 2.
117
118 .. function:: cast_unicode(s, encoding=None)
119 cast_bytes(s, encoding=None)
120
121 Convert strings to unicode/bytes when they may be of either type.
122
123 .. function:: cast_unicode_py2(s, encoding=None)
124 cast_bytes_py2(s, encoding=None)
125
126 Convert strings to unicode/bytes when they may be of either type on Python 2,
127 but return them unaltered on Python 3 (where string types are more
128 predictable).
129
130 .. data:: unicode_type
131
132 A reference to ``str`` on Python 3, and to ``unicode`` on Python 2.
133
134 .. data:: string_types
135
136 A tuple for isinstance checks: ``(str,)`` on Python 3, ``(str, unicode)`` on
137 Python 2.
138
139 Relative imports
140 ----------------
141
142 ::
143
144 # This makes Python 2 behave like Python 3:
145 from __future__ import absolute_import
146
147 import io # Imports the standard library io module
148 from . import io # Import the io module from the package
149 # containing the current module
150 from .io import foo # foo from the io module next to this module
151 from IPython.utils import io # This still works
152
153 Print function
154 --------------
155
156 ::
157
158 # Support the print function on Python 2:
159 from __future__ import print_function
160
161 print(a, b)
162 print(foo, file=sys.stderr)
163 print(bar, baz, sep='\t', end='')
164
165 Metaclasses
166 -----------
167
168 The syntax for declaring a class with a metaclass is different in
169 Python 2 and 3. A helper function works for most cases:
170
171 .. function:: with_metaclass
172
173 Create a base class with a metaclass. Copied from the six library.
174
175 Used like this::
176
177 class FormatterABC(with_metaclass(abc.ABCMeta, object)):
178 ...
179
180 Combining inheritance between Qt and the traitlets system, however, does
181 not work with this. Instead, we do this::
182
183 class QtKernelClientMixin(MetaQObjectHasTraits('NewBase', (HasTraits, SuperQObject), {})):
184 ...
185
186 This gives the new class a metaclass of :class:`~IPython.qt.util.MetaQObjectHasTraits`,
187 and the parent classes :class:`~traitlets.HasTraits` and
188 :class:`~IPython.qt.util.SuperQObject`.
189
190
191 Doctests
192 --------
193
194 .. function:: doctest_refactor_print(func_or_str)
195
196 Refactors print statements in doctests in Python 3 only. Accepts a string
197 or a function, so it can be used as a decorator.
198
199 .. function:: u_format(func_or_str)
200
201 Handle doctests written with ``{u}'abcþ'``, replacing the ``{u}`` with ``u``
202 for Python 2, and removing it for Python 3.
203
204 Accepts a string or a function, so it can be used as a decorator.
205
206 Execfile
207 --------
208
209 .. function:: execfile(fname, glob, loc=None)
210
211 Equivalent to the Python 2 :func:`python:execfile` builtin. We redefine it in
212 Python 2 to better handle non-ascii filenames.
213
214 Miscellaneous
215 -------------
216
217 .. autofunction:: safe_unicode
218 9
219 .. function:: isidentifier(s, dotted=False)
10 IPython 6 requires Python 3, so our compatibility module
11 ``IPython.utils.py3compat`` is deprecated. In most cases, we recommend you use
12 the `six module <https://pythonhosted.org/six/>`__ to support compatible code.
13 This is widely used by other projects, so it is familiar to many developers and
14 thoroughly battle-tested.
220 15
221 Checks whether the string s is a valid identifier in this version of Python.
222 In Python 3, non-ascii characters are allowed. If ``dotted`` is True, it
223 allows dots (i.e. attribute access) in the string.
16 Our ``py3compat`` module provided some more specific unicode conversions than
17 those offered by ``six``. If you want to use these, copy them into your own code
18 from IPython 5.x. Do not rely on importing them from IPython, as the module may
19 be removed in the future.
224 20
225 .. function:: getcwd()
21 .. seealso::
226 22
227 Return the current working directory as unicode, like :func:`os.getcwdu` on
228 Python 2.
23 `Porting Python 2 code to Python 3 <https://docs.python.org/3/howto/pyporting.html>`_
24 Official information in the Python docs.
229 25
230 .. function:: MethodType
26 `Python-Modernize <http://python-modernize.readthedocs.io/en/latest/>`_
27 A tool which helps make code compatible with Python 3.
231 28
232 Constructor for :class:`types.MethodType` that takes two arguments, like
233 the real constructor on Python 3.
29 `Python-Future <http://python-future.org/>`_
30 Another compatibility tool, which focuses on writing code for Python 3 and
31 making it work on Python 2.
General Comments 0
You need to be logged in to leave comments. Login now