changelog.rst 38 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124
  1. .. _whats-old:
  2. Changes in previous versions
  3. ****************************
  4. Changes in the most recent major version are here: :ref:`whats-new`.
  5. .. _whats-new-0.14.x:
  6. Changes in version 0.14.3 (2014-12-15)
  7. ======================================
  8. This is a bug-fix release:
  9. - Expose contents of ``thread`` (not ``dummy_thread``) as ``_thread`` on Py2 (Issue #124)
  10. - Add signed support for ``newint.to_bytes()`` (Issue #128)
  11. - Fix ``OrderedDict.clear()`` on Py2.6 (Issue #125)
  12. - Improve ``newrange``: equality and slicing, start/stop/step properties, refactoring (Issues #129, #130)
  13. - Minor doc updates
  14. Changes in version 0.14.2 (2014-11-21)
  15. ======================================
  16. This is a bug-fix release:
  17. - Speed up importing of ``past.translation`` (Issue #117)
  18. - ``html.escape()``: replace function with the more robust one from Py3.4
  19. - ``futurize``: avoid displacing encoding comments by ``__future__`` imports (Issues #97, #10, #121)
  20. - ``futurize``: don't swallow exit code (Issue #119)
  21. - Packaging: don't forcibly remove the old build dir in ``setup.py`` (Issue #108)
  22. - Docs: update further docs and tests to refer to ``install_aliases()`` instead of
  23. ``install_hooks()``
  24. - Docs: fix ``iteritems`` import error in cheat sheet (Issue #120)
  25. - Tests: don't rely on presence of ``test.test_support`` on Py2 or ``test.support`` on Py3 (Issue #109)
  26. - Tests: don't override existing ``PYTHONPATH`` for tests (PR #111)
  27. Changes in version 0.14.1 (2014-10-02)
  28. ======================================
  29. This is a minor bug-fix release:
  30. - Docs: add a missing template file for building docs (Issue #108)
  31. - Tests: fix a bug in error handling while reporting failed script runs (Issue #109)
  32. - ``install_aliases()``: don't assume that the ``test.test_support`` module always
  33. exists on Py2 (Issue #109)
  34. Changes in version 0.14.0 (2014-10-02)
  35. ======================================
  36. This is a major new release that offers a cleaner interface for most imports in
  37. Python 2/3 compatible code.
  38. Instead of this interface::
  39. >>> from future.builtins import str, open, range, dict
  40. >>> from future.standard_library import hooks
  41. >>> with hooks():
  42. ... import queue
  43. ... import configparser
  44. ... import tkinter.dialog
  45. ... # etc.
  46. You can now use the following interface for much Python 2/3 compatible code::
  47. >>> # Alias for future.builtins on Py2:
  48. >>> from builtins import str, open, range, dict
  49. >>> # Alias for future.moves.* on Py2:
  50. >>> import queue
  51. >>> import configparser
  52. >>> import tkinter.dialog
  53. >>> etc.
  54. Notice that the above code will run on Python 3 even without the presence of the
  55. ``future`` package. Of the 44 standard library modules that were refactored with
  56. PEP 3108, 30 are supported with direct imports in this manner. (These are listed
  57. here: :ref:`direct-imports`.)
  58. The other 14 standard library modules that kept the same top-level names in
  59. Py3.x are not supported with this direct import interface on Py2. These include
  60. the 5 modules in the Py3 ``urllib`` package. These modules are accessible through
  61. the following interface (as well as the interfaces offered in previous versions
  62. of ``python-future``)::
  63. from future.standard_library import install_aliases
  64. install_aliases()
  65. from collections import UserDict, UserList, UserString
  66. import dbm.gnu
  67. from itertools import filterfalse, zip_longest
  68. from subprocess import getoutput, getstatusoutput
  69. from sys import intern
  70. import test.support
  71. from urllib.request import urlopen
  72. from urllib.parse import urlparse
  73. # etc.
  74. from collections import Counter, OrderedDict # backported to Py2.6
  75. The complete list of packages supported with this interface is here:
  76. :ref:`list-standard-library-refactored`.
  77. For more information on these and other interfaces to the standard library, see
  78. :ref:`standard-library-imports`.
  79. Bug fixes
  80. ---------
  81. - This release expands the ``future.moves`` package to include most of the remaining
  82. modules that were moved in the standard library reorganization (PEP 3108).
  83. (Issue #104)
  84. - This release also removes the broken ``--doctests_only`` option from the ``futurize``
  85. and ``pasteurize`` scripts for now. (Issue #103)
  86. Internal cleanups
  87. -----------------
  88. The project folder structure has changed. Top-level packages are now in a
  89. ``src`` folder and the tests have been moved into a project-level ``tests``
  90. folder.
  91. The following deprecated internal modules have been removed (Issue #80):
  92. - ``future.utils.encoding`` and ``future.utils.six``.
  93. Deprecations
  94. ------------
  95. The following internal functions have been deprecated and will be removed in a future release:
  96. - ``future.standard_library.scrub_py2_sys_modules``
  97. - ``future.standard_library.scrub_future_sys_modules``
  98. .. _whats-new-0.13.x:
  99. Changes in version 0.13.1 (2014-09-23)
  100. ======================================
  101. This is a bug-fix release:
  102. - Fix (multiple) inheritance of ``future.builtins.object`` with metaclasses (Issues #91, #96)
  103. - Fix ``futurize``'s refactoring of ``urllib`` imports (Issue #94)
  104. - Fix ``futurize --all-imports`` (Issue #101)
  105. - Fix ``futurize --output-dir`` logging (Issue #102)
  106. - Doc formatting fix (Issues #98, #100)
  107. Changes in version 0.13.0 (2014-08-13)
  108. ======================================
  109. This is mostly a clean-up release. It adds some small new compatibility features
  110. and fixes several bugs.
  111. Deprecations
  112. ------------
  113. The following unused internal modules are now deprecated. They will be removed in a
  114. future release:
  115. - ``future.utils.encoding`` and ``future.utils.six``.
  116. (Issue #80). See `here <http://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries>`_
  117. for the rationale for unbundling them.
  118. New features
  119. ------------
  120. - Docs: Add :ref:`compatible-idioms` from Ed Schofield's PyConAU 2014 talk.
  121. - Add ``newint.to_bytes()`` and ``newint.from_bytes()``. (Issue #85)
  122. - Add ``future.utils.raise_from`` as an equivalent to Py3's ``raise ... from
  123. ...`` syntax. (Issue #86)
  124. - Add ``past.builtins.oct()`` function.
  125. - Add backports for Python 2.6 of ``subprocess.check_output()``,
  126. ``itertools.combinations_with_replacement()``, and ``functools.cmp_to_key()``.
  127. Bug fixes
  128. ---------
  129. - Use a private logger instead of the global logger in
  130. ``future.standard_library`` (Issue #82). This restores compatibility of the
  131. standard library hooks with ``flask``. (Issue #79)
  132. - Stage 1 of ``futurize`` no longer renames ``next`` methods to ``__next__``
  133. (Issue #81). It still converts ``obj.next()`` method calls to
  134. ``next(obj)`` correctly.
  135. - Prevent introduction of a second set of parentheses in ``print()`` calls in
  136. some further cases.
  137. - Fix ``isinstance`` checks for subclasses of future types. (Issue #89)
  138. - Be explicit about encoding file contents as UTF-8 in unit tests. (Issue #63)
  139. Useful for building RPMs and in other environments where ``LANG=C``.
  140. - Fix for 3-argument ``pow(x, y, z)`` with ``newint`` arguments. (Thanks to @str4d.)
  141. (Issue #87)
  142. .. _whats-new-0.12.4:
  143. Changes in version 0.12.4 (2014-07-18)
  144. ======================================
  145. - Fix upcasting behaviour of ``newint``. (Issue #76)
  146. .. _whats-new-0.12.3:
  147. Changes in version 0.12.3 (2014-06-19)
  148. ======================================
  149. - Add "official Python 3.4 support": Py3.4 is now listed among the PyPI Trove
  150. classifiers and the tests now run successfully on Py3.4. (Issue #67)
  151. - Add backports of ``collections.OrderedDict`` and
  152. ``collections.Counter`` for Python 2.6. (Issue #52)
  153. - Add ``--version`` option for ``futurize`` and ``pasteurize`` scripts.
  154. (Issue #57)
  155. - Fix ``future.utils.ensure_new_type`` with ``long`` input. (Issue #65)
  156. - Remove some false alarms on checks for ambiguous fixer names with
  157. ``futurize -f ...``.
  158. - Testing fixes:
  159. - Don't hard-code Python interpreter command in tests. (Issue #62)
  160. - Fix deprecated ``unittest`` usage in Py3. (Issue #62)
  161. - Be explicit about encoding temporary file contents as UTF-8 for
  162. when ``LANG=C`` (e.g., when building an RPM). (Issue #63)
  163. - All undecorated tests are now passing again on Python 2.6, 2.7, 3.3,
  164. and 3.4 (thanks to Elliott Sales de Andrade).
  165. - Docs:
  166. - Add list of fixers used by ``futurize``. (Issue #58)
  167. - Add list of contributors to the Credits page.
  168. .. _whats-new-0.12.2:
  169. Changes in version 0.12.2 (2014-05-25)
  170. ======================================
  171. - Add ``bytes.maketrans()`` method. (Issue #51)
  172. - Add support for Python versions between 2.7.0 and 2.7.3 (inclusive).
  173. (Issue #53)
  174. - Bug fix for ``newlist(newlist([1, 2, 3]))``. (Issue #50)
  175. .. _whats-new-0.12.1:
  176. Changes in version 0.12.1 (2014-05-14)
  177. ======================================
  178. - Python 2.6 support: ``future.standard_library`` now isolates the ``importlib``
  179. dependency to one function (``import_``) so the ``importlib`` backport may
  180. not be needed.
  181. - Doc updates
  182. .. _whats-new-0.12:
  183. Changes in version 0.12.0 (2014-05-06)
  184. ======================================
  185. The major new feature in this version is improvements in the support for the
  186. reorganized standard library (PEP 3108) and compatibility of the import
  187. mechanism with 3rd-party modules.
  188. More robust standard-library import hooks
  189. -----------------------------------------
  190. **Note: backwards-incompatible change:** As previously announced (see
  191. :ref:`deprecated-auto-import-hooks`), the import hooks must now be enabled
  192. explicitly, as follows::
  193. from future import standard_library
  194. with standard_library.hooks():
  195. import html.parser
  196. import http.client
  197. ...
  198. This now causes these modules to be imported from ``future.moves``, a new
  199. package that provides wrappers over the native Python 2 standard library with
  200. the new Python 3 organization. As a consequence, the import hooks provided in
  201. ``future.standard_library`` are now fully compatible with the `Requests library
  202. <http://python-requests.org>`_.
  203. The functional interface with ``install_hooks()`` is still supported for
  204. backwards compatibility::
  205. from future import standard_library
  206. standard_library.install_hooks():
  207. import html.parser
  208. import http.client
  209. ...
  210. standard_library.remove_hooks()
  211. Explicit installation of import hooks allows finer-grained control
  212. over whether they are enabled for other imported modules that provide their own
  213. Python 2/3 compatibility layer. This also improves compatibility of ``future``
  214. with tools like ``py2exe``.
  215. ``newobject`` base object defines fallback Py2-compatible special methods
  216. -------------------------------------------------------------------------
  217. There is a new ``future.types.newobject`` base class (available as
  218. ``future.builtins.object``) that can streamline Py2/3 compatible code by
  219. providing fallback Py2-compatible special methods for its subclasses. It
  220. currently provides ``next()`` and ``__nonzero__()`` as fallback methods on Py2
  221. when its subclasses define the corresponding Py3-style ``__next__()`` and
  222. ``__bool__()`` methods.
  223. This obviates the need to add certain compatibility hacks or decorators to the
  224. code such as the ``@implements_iterator`` decorator for classes that define a
  225. Py3-style ``__next__`` method.
  226. In this example, the code defines a Py3-style iterator with a ``__next__``
  227. method. The ``object`` class defines a ``next`` method for Python 2 that maps
  228. to ``__next__``::
  229. from future.builtins import object
  230. class Upper(object):
  231. def __init__(self, iterable):
  232. self._iter = iter(iterable)
  233. def __next__(self): # note the Py3 interface
  234. return next(self._iter).upper()
  235. def __iter__(self):
  236. return self
  237. assert list(Upper('hello')) == list('HELLO')
  238. ``newobject`` defines other Py2-compatible special methods similarly:
  239. currently these include ``__nonzero__`` (mapped to ``__bool__``) and
  240. ``__long__`` (mapped to ``__int__``).
  241. Inheriting from ``newobject`` on Python 2 is safe even if your class defines
  242. its own Python 2-style ``__nonzero__`` and ``next`` and ``__long__`` methods.
  243. Your custom methods will simply override those on the base class.
  244. On Python 3, as usual, ``future.builtins.object`` simply refers to ``builtins.object``.
  245. ``past.builtins`` module improved
  246. ---------------------------------
  247. The ``past.builtins`` module is much more compatible with the corresponding
  248. builtins on Python 2; many more of the Py2 unit tests pass on Py3. For example,
  249. functions like ``map()`` and ``filter()`` now behave as they do on Py2 with with
  250. ``None`` as the first argument.
  251. The ``past.builtins`` module has also been extended to add Py3 support for
  252. additional Py2 constructs that are not adequately handled by ``lib2to3`` (see
  253. Issue #37). This includes new ``execfile()`` and ``cmp()`` functions.
  254. ``futurize`` now invokes imports of these functions from ``past.builtins``.
  255. ``surrogateescape`` error handler
  256. ---------------------------------
  257. The ``newstr`` type (``future.builtins.str``) now supports a backport of the
  258. Py3.x ``'surrogateescape'`` error handler for preserving high-bit
  259. characters when encoding and decoding strings with unknown encodings.
  260. ``newlist`` type
  261. ----------------
  262. There is a new ``list`` type in ``future.builtins`` that offers ``.copy()`` and
  263. ``.clear()`` methods like the ``list`` type in Python 3.
  264. ``listvalues`` and ``listitems``
  265. --------------------------------
  266. ``future.utils`` now contains helper functions ``listvalues`` and
  267. ``listitems``, which provide Python 2-style list snapshotting semantics for
  268. dictionaries in both Python 2 and Python 3.
  269. These came out of the discussion around Nick Coghlan's now-withdrawn PEP 469.
  270. There is no corresponding ``listkeys(d)`` function; use ``list(d)`` instead.
  271. Tests
  272. -----
  273. The number of unit tests has increased from 600 to over 800. Most of the new
  274. tests come from Python 3.3's test suite.
  275. Refactoring of ``future.standard_library.*`` -> ``future.backports``
  276. --------------------------------------------------------------------
  277. The backported standard library modules have been moved to ``future.backports``
  278. to make the distinction clearer between these and the new ``future.moves``
  279. package.
  280. Backported ``http.server`` and ``urllib`` modules
  281. -------------------------------------------------
  282. Alpha versions of backports of the ``http.server`` and ``urllib`` module from
  283. Python 3.3's standard library are now provided in ``future.backports``.
  284. Use them like this::
  285. from future.backports.urllib.request import Request # etc.
  286. from future.backports.http import server as http_server
  287. Or with this new interface::
  288. from future.standard_library import import_, from_import
  289. Request = from_import('urllib.request', 'Request', backport=True)
  290. http = import_('http.server', backport=True)
  291. .. from future.standard_library.email import message_from_bytes # etc.
  292. .. from future.standard_library.xmlrpc import client, server
  293. Internal refactoring
  294. --------------------
  295. The ``future.builtins.types`` module has been moved to ``future.types``.
  296. Likewise, ``past.builtins.types`` has been moved to ``past.types``. The only
  297. user-visible effect of this is to change ``repr(type(obj))`` for instances
  298. of these types. For example::
  299. >>> from future.builtins import bytes
  300. >>> bytes(b'abc')
  301. >>> type(b)
  302. future.types.newbytes.newbytes
  303. Instead of::
  304. >>> type(b) # prior to v0.12
  305. future.builtins.types.newbytes.newbytes
  306. Bug fixes
  307. ---------
  308. Many small improvements and fixes have been made across the project. Some highlights are:
  309. - Fixes and updates from Python 3.3.5 have been included in the backported
  310. standard library modules.
  311. - Scrubbing of the ``sys.modules`` cache performed by ``remove_hooks()`` (also
  312. called by the ``suspend_hooks`` and ``hooks`` context managers) is now more
  313. conservative.
  314. .. Is this still true?
  315. .. It now removes only modules with Py3 names (such as
  316. .. ``urllib.parse``) and not the corresponding ``future.standard_library.*``
  317. .. modules (such as ``future.standard_library.urllib.parse``.
  318. - The ``fix_next`` and ``fix_reduce`` fixers have been moved to stage 1 of
  319. ``futurize``.
  320. - ``futurize``: Shebang lines such as ``#!/usr/bin/env python`` and source code
  321. file encoding declarations like ``# -*- coding=utf-8 -*-`` are no longer occasionally
  322. displaced by ``from __future__ import ...`` statements. (Issue #10)
  323. - Improved compatibility with ``py2exe`` (`Issue #31 <https://github.com/PythonCharmers/python-future/issues/31>`_).
  324. - The ``future.utils.bytes_to_native_str`` function now returns a platform-native string
  325. object and ``future.utils.native_str_to_bytes`` returns a ``newbytes`` object on Py2.
  326. (`Issue #47 <https://github.com/PythonCharmers/python-future/issues/47>`_).
  327. - The backported ``http.client`` module and related modules use other new
  328. backported modules such as ``email``. As a result they are more compliant
  329. with the Python 3.3 equivalents.
  330. .. _whats-new-0.11.4:
  331. Changes in version 0.11.4 (2014-05-25)
  332. ======================================
  333. This release contains various small improvements and fixes:
  334. - This release restores Python 2.6 compatibility. (Issue #42)
  335. - The ``fix_absolute_import`` fixer now supports Cython ``.pyx`` modules. (Issue
  336. #35)
  337. - Right-division with ``newint`` objects is fixed. (Issue #38)
  338. - The ``fix_dict`` fixer has been moved to stage2 of ``futurize``.
  339. - Calls to ``bytes(string, encoding[, errors])`` now work with ``encoding`` and
  340. ``errors`` passed as positional arguments. Previously this only worked if
  341. ``encoding`` and ``errors`` were passed as keyword arguments.
  342. - The 0-argument ``super()`` function now works from inside static methods such
  343. as ``__new__``. (Issue #36)
  344. - ``future.utils.native(d)`` calls now work for ``future.builtins.dict`` objects.
  345. .. _whats-new-0.11.3:
  346. Changes in version 0.11.3 (2014-02-27)
  347. ======================================
  348. This release has improvements in the standard library import hooks mechanism and
  349. its compatibility with 3rd-party modules:
  350. Improved compatibility with ``requests``
  351. ----------------------------------------
  352. The ``__exit__`` function of the ``hooks`` context manager and the
  353. ``remove_hooks`` function both now remove submodules of
  354. ``future.standard_library`` from the ``sys.modules`` cache. Therefore this code
  355. is now possible on Python 2 and 3::
  356. from future import standard_library
  357. standard_library.install_hooks()
  358. import http.client
  359. standard_library.remove_hooks()
  360. import requests
  361. data = requests.get('http://www.google.com')
  362. Previously, this required manually removing ``http`` and ``http.client`` from
  363. ``sys.modules`` before importing ``requests`` on Python 2.x. (Issue #19)
  364. This change should also improve the compatibility of the standard library hooks
  365. with any other module that provides its own Python 2/3 compatibility code.
  366. Note that the situation will improve further in version 0.12; import hooks will
  367. require an explicit function call or the ``hooks`` context manager.
  368. Conversion scripts explicitly install import hooks
  369. --------------------------------------------------
  370. The ``futurize`` and ``pasteurize`` scripts now add an explicit call to
  371. ``install_hooks()`` to install the standard library import hooks. These scripts
  372. now add these two lines::
  373. from future import standard_library
  374. standard_library.install_hooks()
  375. instead of just the first one. The next major version of ``future`` (0.12) will
  376. require the explicit call or use of the ``hooks`` context manager. This will
  377. allow finer-grained control over whether import hooks are enabled for other
  378. imported modules, such as ``requests``, which provide their own Python 2/3
  379. compatibility code.
  380. ``futurize`` script no longer adds ``unicode_literals`` by default
  381. ------------------------------------------------------------------
  382. There is a new ``--unicode-literals`` flag to ``futurize`` that adds the
  383. import::
  384. from __future__ import unicode_literals
  385. to the top of each converted module. Without this flag, ``futurize`` now no
  386. longer adds this import. (Issue #22)
  387. The ``pasteurize`` script for converting from Py3 to Py2/3 still adds
  388. ``unicode_literals``. (See the comments in Issue #22 for an explanation.)
  389. .. _whats-new-0.11:
  390. Changes in version 0.11 (2014-01-28)
  391. ====================================
  392. There are several major new features in version 0.11.
  393. ``past`` package
  394. ----------------
  395. The python-future project now provides a ``past`` package in addition to the
  396. ``future`` package. Whereas ``future`` provides improved compatibility with
  397. Python 3 code to Python 2, ``past`` provides support for using and interacting
  398. with Python 2 code from Python 3. The structure reflects that of ``future``,
  399. with ``past.builtins`` and ``past.utils``. There is also a new
  400. ``past.translation`` package that provides transparent translation of Python 2
  401. code to Python 3. (See below.)
  402. One purpose of ``past`` is to ease module-by-module upgrades to
  403. codebases from Python 2. Another is to help with enabling Python 2 libraries to
  404. support Python 3 without breaking the API they currently provide. (For example,
  405. user code may expect these libraries to pass them Python 2's 8-bit strings,
  406. rather than Python 3's ``bytes`` object.) A third purpose is to help migrate
  407. projects to Python 3 even if one or more dependencies are still on Python 2.
  408. Currently ``past.builtins`` provides forward-ports of Python 2's ``str`` and
  409. ``dict`` objects, ``basestring``, and list-producing iterator functions. In
  410. later releases, ``past.builtins`` will be used internally by the
  411. ``past.translation`` package to help with importing and using old Python 2
  412. modules in a Python 3 environment.
  413. Auto-translation of Python 2 modules upon import
  414. ------------------------------------------------
  415. ``past`` provides an experimental ``translation`` package to help
  416. with importing and using old Python 2 modules in a Python 3 environment.
  417. This is implemented using import hooks that attempt to automatically
  418. translate Python 2 modules to Python 3 syntax and semantics upon import. Use
  419. it like this::
  420. $ pip3 install plotrique==0.2.5-7 --no-compile # to ignore SyntaxErrors
  421. $ python3
  422. Then pass in a whitelist of module name prefixes to the ``past.autotranslate()``
  423. function. Example::
  424. >>> from past import autotranslate
  425. >>> autotranslate(['plotrique'])
  426. >>> import plotrique
  427. This is intended to help you migrate to Python 3 without the need for all
  428. your code's dependencies to support Python 3 yet. It should be used as a
  429. last resort; ideally Python 2-only dependencies should be ported
  430. properly to a Python 2/3 compatible codebase using a tool like
  431. ``futurize`` and the changes should be pushed to the upstream project.
  432. For more information, see :ref:`translation`.
  433. Separate ``pasteurize`` script
  434. ------------------------------
  435. The functionality from ``futurize --from3`` is now in a separate script called
  436. ``pasteurize``. Use ``pasteurize`` when converting from Python 3 code to Python
  437. 2/3 compatible source. For more information, see :ref:`backwards-conversion`.
  438. ``pow()``
  439. ---------
  440. There is now a ``pow()`` function in ``future.builtins.misc`` that behaves like
  441. the Python 3 ``pow()`` function when raising a negative number to a fractional
  442. power (returning a complex number).
  443. ``input()`` no longer disabled globally on Py2
  444. ----------------------------------------------
  445. Previous versions of ``future`` deleted the ``input()`` function from
  446. ``__builtin__`` on Python 2 as a security measure. This was because
  447. Python 2's ``input()`` function allows arbitrary code execution and could
  448. present a security vulnerability on Python 2 if someone expects Python 3
  449. semantics but forgets to import ``input`` from ``future.builtins``. This
  450. behaviour has been reverted, in the interests of broadening the
  451. compatibility of ``future`` with other Python 2 modules.
  452. Please remember to import ``input`` from ``future.builtins`` if you use
  453. ``input()`` in a Python 2/3 compatible codebase.
  454. .. _deprecated-auto-import-hooks:
  455. Deprecated feature: auto-installation of standard-library import hooks
  456. ----------------------------------------------------------------------
  457. Previous versions of ``python-future`` installed import hooks automatically upon
  458. importing the ``standard_library`` module from ``future``. This has been
  459. deprecated in order to improve robustness and compatibility with modules like
  460. ``requests`` that already perform their own single-source Python 2/3
  461. compatibility.
  462. As of v0.12, importing ``future.standard_library``
  463. will no longer install import hooks by default. Instead, please install the
  464. import hooks explicitly as follows::
  465. from future import standard_library
  466. standard_library.install_hooks()
  467. And uninstall them after your import statements using::
  468. standard_library.remove_hooks()
  469. *Note*: This is a backward-incompatible change.
  470. Internal changes
  471. ----------------
  472. The internal ``future.builtins.backports`` module has been renamed to
  473. ``future.builtins.types``. This will change the ``repr`` of ``future``
  474. types but not their use.
  475. .. _whats-new-0.10.2:
  476. Changes in version 0.10.2 (2014-01-11)
  477. ======================================
  478. New context-manager interface to ``standard_library.hooks``
  479. -----------------------------------------------------------
  480. There is a new context manager ``future.standard_library.hooks``. Use it like
  481. this::
  482. from future import standard_library
  483. with standard_library.hooks():
  484. import queue
  485. import configserver
  486. from http.client import HTTPConnection
  487. # etc.
  488. If not using this context manager, it is now encouraged to add an explicit call to
  489. ``standard_library.install_hooks()`` as follows::
  490. from future import standard_library
  491. standard_library.install_hooks()
  492. import queue
  493. import html
  494. import http.client
  495. # etc.
  496. And to remove the hooks afterwards with::
  497. standard_library.remove_hooks()
  498. The functions ``install_hooks()`` and ``remove_hooks()`` were previously
  499. called ``enable_hooks()`` and ``disable_hooks()``. The old names are
  500. deprecated (but are still available as aliases).
  501. As usual, this feature has no effect on Python 3.
  502. .. _whats-new-0.10:
  503. Changes in version 0.10.0 (2013-12-02)
  504. ======================================
  505. Backported ``dict`` type
  506. ------------------------
  507. ``future.builtins`` now provides a Python 2 ``dict`` subclass whose
  508. :func:`keys`, :func:`values`, and :func:`items` methods produce
  509. memory-efficient iterators. On Python 2.7, these also have the same set-like
  510. view behaviour as on Python 3. This can streamline code needing to iterate
  511. over large dictionaries. For example::
  512. from __future__ import print_function
  513. from future.builtins import dict, range
  514. squares = dict({i: i**2 for i in range(10**7)})
  515. assert not isinstance(d.items(), list)
  516. # Because items() is memory-efficient, so is this:
  517. square_roots = dict((i_squared, i) for (i, i_squared) in squares.items())
  518. For more information, see :ref:`dict-object`.
  519. Utility functions ``raise_`` and ``exec_``
  520. ------------------------------------------
  521. The functions ``raise_with_traceback()`` and ``raise_()`` were
  522. added to ``future.utils`` to offer either the Python 3.x or Python 2.x
  523. behaviour for raising exceptions. Thanks to Joel Tratner for the
  524. contribution of these. ``future.utils.reraise()`` is now deprecated.
  525. A portable ``exec_()`` function has been added to ``future.utils`` from
  526. ``six``.
  527. Bugfixes
  528. --------
  529. - Fixed ``newint.__divmod__``
  530. - Improved robustness of installing and removing import hooks in :mod:`future.standard_library`
  531. - v0.10.1: Fixed broken ``pip install future`` on Py3
  532. .. _whats-new-0.9:
  533. Changes in version 0.9 (2013-11-06)
  534. ===================================
  535. ``isinstance`` checks are supported natively with backported types
  536. ------------------------------------------------------------------
  537. The ``isinstance`` function is no longer redefined in ``future.builtins``
  538. to operate with the backported ``int``, ``bytes`` and ``str``.
  539. ``isinstance`` checks with the backported types now work correctly by
  540. default; we achieve this through overriding the ``__instancecheck__``
  541. method of metaclasses of the backported types.
  542. For more information, see :ref:`isinstance-calls`.
  543. ``futurize``: minimal imports by default
  544. ----------------------------------------
  545. By default, the ``futurize`` script now only adds the minimal set of
  546. imports deemed necessary.
  547. There is now an ``--all-imports`` option to the ``futurize`` script which
  548. gives the previous behaviour, which is to add all ``__future__`` imports
  549. and ``from future.builtins import *`` imports to every module. (This even
  550. applies to an empty ``__init__.py`` file.)
  551. Looser type-checking for the backported ``str`` object
  552. ------------------------------------------------------
  553. Now the ``future.builtins.str`` object behaves more like the Python 2
  554. ``unicode`` object with regard to type-checking. This is to work around some
  555. bugs / sloppiness in the Python 2 standard library involving mixing of
  556. byte-strings and unicode strings, such as ``os.path.join`` in ``posixpath.py``.
  557. ``future.builtins.str`` still raises the expected ``TypeError`` exceptions from
  558. Python 3 when attempting to mix it with ``future.builtins.bytes``.
  559. ``suspend_hooks()`` context manager added to ``future.standard_library``
  560. ------------------------------------------------------------------------
  561. Pychecker (as of v0.6.1)'s ``checker.py`` attempts to import the ``builtins``
  562. module as a way of determining whether Python 3 is running. Since this
  563. succeeds when ``from future import standard_library`` is in effect, this
  564. check does not work and pychecker sets the wrong value for its internal ``PY2``
  565. flag is set.
  566. To work around this, ``future`` now provides a context manager called
  567. ``suspend_hooks`` that can be used as follows::
  568. from future import standard_library
  569. ...
  570. with standard_library.suspend_hooks():
  571. from pychecker.checker import Checker
  572. .. _whats-new-0.8:
  573. Changes in version 0.8 (2013-10-28)
  574. ===================================
  575. Python 2.6 support
  576. ------------------
  577. ``future`` now includes support for Python 2.6.
  578. To run the ``future`` test suite on Python 2.6, this additional package is needed::
  579. pip install unittest2
  580. ``http.server`` also requires the ``argparse`` package::
  581. pip install argparse
  582. Unused modules removed
  583. ----------------------
  584. The ``future.six`` module has been removed. ``future`` doesn't require ``six``
  585. (and hasn't since version 0.3). If you need support for Python versions before
  586. 2.6, ``six`` is the best option. ``future`` and ``six`` can be installed
  587. alongside each other easily if needed.
  588. The unused ``hacks`` module has also been removed from the source tree.
  589. ``isinstance()`` added to :mod:`future.builtins` (v0.8.2)
  590. ---------------------------------------------------------
  591. It is now possible to use ``isinstance()`` calls normally after importing ``isinstance`` from
  592. ``future.builtins``. On Python 2, this is specially defined to be compatible with
  593. ``future``'s backported ``int``, ``str``, and ``bytes`` types, as well as
  594. handling Python 2's ``int``/``long`` distinction.
  595. The result is that code that uses ``isinstance`` to perform type-checking of
  596. ints, strings, and bytes should now work identically on Python 2 as on Python 3.
  597. The utility functions ``isint``, ``istext``, and ``isbytes`` provided before for
  598. compatible type-checking across Python 2 and 3 in :mod:`future.utils` are now
  599. deprecated.
  600. .. _changelog:
  601. Summary of all changes
  602. ======================
  603. v0.15.0:
  604. * Full backports of ``urllib.parse`` and other ``urllib`` submodules are exposed by ``install_aliases()``.
  605. * ``tkinter.ttk`` support
  606. * Initial ``surrogateescape`` support
  607. * Additional backports: ``collections``, ``http`` constants, etc.
  608. * Bug fixes
  609. v0.14.3:
  610. * Bug fixes
  611. v0.14.2:
  612. * Bug fixes
  613. v0.14.1:
  614. * Bug fixes
  615. v0.14.0:
  616. * New top-level ``builtins`` package on Py2 for cleaner imports. Equivalent to
  617. ``future.builtins``
  618. * New top-level packages on Py2 with the same names as Py3 standard modules:
  619. ``configparser``, ``copyreg``, ``html``, ``http``, ``xmlrpc``, ``winreg``
  620. v0.13.1:
  621. * Bug fixes
  622. v0.13.0:
  623. * Cheat sheet for writing Python 2/3 compatible code
  624. * ``to_int`` and ``from_int`` methods for ``newbytes``
  625. * Bug fixes
  626. v0.12.0:
  627. * Add ``newobject`` and ``newlist`` types
  628. * Improve compatibility of import hooks with ``Requests``, ``py2exe``
  629. * No more auto-installation of import hooks by ``future.standard_library``
  630. * New ``future.moves`` package
  631. * ``past.builtins`` improved
  632. * ``newstr.encode(..., errors='surrogateescape')`` supported
  633. * Refactoring: ``future.standard_library`` submodules -> ``future.backports``
  634. * Refactoring: ``future.builtins.types`` -> ``future.types``
  635. * Refactoring: ``past.builtins.types`` -> ``past.types``
  636. * New ``listvalues`` and ``listitems`` functions in ``future.utils``
  637. * Many bug fixes to ``futurize``, ``future.builtins``, etc.
  638. v0.11.4:
  639. * Restore Py2.6 compatibility
  640. v0.11.3:
  641. * The ``futurize`` and ``pasteurize`` scripts add an explicit call to
  642. ``future.standard_library.install_hooks()`` whenever modules affected by
  643. PEP 3108 are imported.
  644. * The ``future.builtins.bytes`` constructor now accepts ``frozenset``
  645. objects as on Py3.
  646. v0.11.2:
  647. * The ``past.autotranslate`` feature now finds modules to import more
  648. robustly and works with Python eggs.
  649. v0.11.1:
  650. * Update to ``requirements_py26.txt`` for Python 2.6. Small updates to
  651. docs and tests.
  652. v0.11:
  653. * New ``past`` package with ``past.builtins`` and ``past.translation``
  654. modules.
  655. v0.10.2:
  656. * Improvements to stdlib hooks. New context manager:
  657. ``future.standard_library.hooks()``.
  658. * New ``raise_`` and ``raise_with_traceback`` functions in ``future.utils``.
  659. v0.10:
  660. * New backported ``dict`` object with set-like ``keys``, ``values``, ``items``
  661. v0.9:
  662. * :func:`isinstance` hack removed in favour of ``__instancecheck__`` on the
  663. metaclasses of the backported types
  664. * ``futurize`` now only adds necessary imports by default
  665. * Looser type-checking by ``future.builtins.str`` when combining with Py2
  666. native byte-strings.
  667. v0.8.3:
  668. * New ``--all-imports`` option to ``futurize``
  669. * Fix bug with ``str.encode()`` with encoding as a non-keyword arg
  670. v0.8.2:
  671. * New ``isinstance`` function in :mod:`future.builtins`. This obviates
  672. and deprecates the utility functions for type-checking in :mod:`future.utils`.
  673. v0.8.1:
  674. * Backported ``socketserver.py``. Fixes sporadic test failures with
  675. ``http.server`` (related to threading and old-style classes used in Py2.7's
  676. ``SocketServer.py``).
  677. * Move a few more safe ``futurize`` fixes from stage2 to stage1
  678. * Bug fixes to :mod:`future.utils`
  679. v0.8:
  680. * Added Python 2.6 support
  681. * Removed unused modules: :mod:`future.six` and :mod:`future.hacks`
  682. * Removed undocumented functions from :mod:`future.utils`
  683. v0.7:
  684. * Added a backported Py3-like ``int`` object (inherits from ``long``).
  685. * Added utility functions for type-checking and docs about
  686. ``isinstance`` uses/alternatives.
  687. * Fixes and stricter type-checking for ``bytes`` and ``str`` objects
  688. * Added many more tests for the ``futurize`` script
  689. * We no longer disable obsolete Py2 builtins by default with ``from
  690. future.builtins import *``. Use ``from future.builtins.disabled
  691. import *`` instead.
  692. v0.6:
  693. * Added a backported Py3-like ``str`` object (inherits from Py2's ``unicode``)
  694. * Removed support for the form ``from future import *``; use ``from future.builtins import *`` instead
  695. v0.5.3:
  696. * Doc improvements
  697. v0.5.2:
  698. * Add lots of docs and a Sphinx project
  699. v0.5.1:
  700. * Upgraded included ``six`` module (included as ``future.utils.six``) to v1.4.1
  701. * :mod:`http.server` module backported
  702. * ``bytes.split()`` and ``.rsplit()`` bugfixes
  703. v0.5.0:
  704. * Added backported Py3-like ``bytes`` object
  705. v0.4.2:
  706. * Various fixes
  707. v0.4.1:
  708. * Added :func:`open` (from :mod:`io` module on Py2)
  709. * Improved docs
  710. v0.4.0:
  711. * Added various useful compatibility functions to :mod:`future.utils`
  712. * Reorganized package: moved all builtins to :mod:`future.builtins`; moved
  713. all stdlib things to ``future.standard_library``
  714. * Renamed ``python-futurize`` console script to ``futurize``
  715. * Moved ``future.six`` to ``future.utils.six`` and pulled the most relevant
  716. definitions to :mod:`future.utils`.
  717. * More improvements to "Py3 to both" conversion (``futurize.py --from3``)
  718. v0.3.5:
  719. * Fixed broken package setup ("package directory 'libfuturize/tests' does not exist")
  720. v0.3.4:
  721. * Added ``itertools.zip_longest``
  722. * Updated ``2to3_backcompat`` tests to use ``futurize.py``
  723. * Improved ``libfuturize`` fixers: correct order of imports; add imports only when necessary (except ``absolute_import`` currently)
  724. v0.3.3:
  725. * Added ``python-futurize`` console script
  726. * Added ``itertools.filterfalse``
  727. * Removed docs about unfinished backports (``urllib`` etc.)
  728. * Removed old Py2 syntax in some files that breaks py3 ``setup.py install``
  729. v0.3.2:
  730. * Added ``test.support`` module
  731. * Added ``UserList``, ``UserString``, ``UserDict`` classes to ``collections`` module
  732. * Removed ``int`` -> ``long`` mapping
  733. * Added backported ``_markupbase.py`` etc. with new-style classes to fix travis-ci build problems
  734. * Added working ``html`` and ``http.client`` backported modules
  735. v0.3.0:
  736. * Generalized import hooks to allow dotted imports
  737. * Added backports of ``urllib``, ``html``, ``http`` modules from Py3.3 stdlib using ``future``
  738. * Added ``futurize`` script for automatically turning Py2 or Py3 modules into
  739. cross-platform Py3 modules
  740. * Renamed ``future.standard_library_renames`` to
  741. ``future.standard_library``. (No longer just renames, but backports too.)
  742. v0.2.2.1:
  743. * Small bug fixes to get tests passing on travis-ci.org
  744. v0.2.1:
  745. * Small bug fixes
  746. v0.2.0:
  747. * ``Features`` module renamed to ``modified_builtins``
  748. * New functions added: :func:`round`, :func:`input`
  749. * No more namespace pollution as a policy::
  750. from future import *
  751. should have no effect on Python 3. On Python 2, it only shadows the
  752. builtins; it doesn't introduce any new names.
  753. * End-to-end tests with Python 2 code and ``2to3`` now work
  754. v0.1.0:
  755. * first version with tests!
  756. * removed the inspect-module magic
  757. v0.0.x:
  758. * initial releases. Use at your peril.