quickstart.rst 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163
  1. .. _quickstart-guide:
  2. Quick-start guide
  3. =================
  4. You can use ``future`` to help to port your code from Python 2 to Python 3
  5. today -- and still have it run on Python 2.
  6. If you already have Python 3 code, you can instead use ``future`` to
  7. offer Python 2 compatibility with almost no extra work.
  8. Installation
  9. ------------
  10. To install the latest stable version, type::
  11. pip install future
  12. If you would prefer the latest development version, it is available `here
  13. <https://github.com/PythonCharmers/python-future>`_.
  14. On Python 2.6, three packages containing backports of standard library modules
  15. in Python 2.7+ are needed for small parts of the code::
  16. pip install importlib # for future.standard_library.import_ function only
  17. pip install unittest2 # to run the test suite
  18. pip install argparse # for the backported http.server module from Py3.3
  19. Unless these features are used on Python 2.6 (only), ``future`` has no
  20. dependencies.
  21. If you are writing code from scratch
  22. ------------------------------------
  23. The easiest way is to start each new module with these lines::
  24. from __future__ import (absolute_import, division,
  25. print_function, unicode_literals)
  26. from builtins import *
  27. Then write standard Python 3 code. The :mod:`future` package will
  28. provide support for running your code on Python 2.6, 2.7, and 3.3+ mostly
  29. unchanged.
  30. - For explicit import forms, see :ref:`explicit-imports`.
  31. - For more details, see :ref:`what-else`.
  32. - For a cheat sheet, see :ref:`compatible-idioms`.
  33. To convert existing Python 3 code
  34. ---------------------------------
  35. To offer backward compatibility with Python 2 from your Python 3 code,
  36. you can use the ``pasteurize`` script. This adds these lines at the top of each
  37. module::
  38. from __future__ import absolute_import
  39. from __future__ import division
  40. from __future__ import print_function
  41. from __future__ import unicode_literals
  42. from builtins import open
  43. from builtins import str
  44. # etc., as needed
  45. from future import standard_library
  46. standard_library.install_aliases()
  47. and converts several Python 3-only constructs (like keyword-only arguments) to a
  48. form compatible with both Py3 and Py2. Most remaining Python 3 code should
  49. simply work on Python 2.
  50. See :ref:`backwards-conversion` for more details.
  51. To convert existing Python 2 code
  52. ---------------------------------
  53. .. include:: futurize_overview.rst
  54. See :ref:`forwards-conversion-stage1` and :ref:`forwards-conversion-stage2` for more details.
  55. .. If you already know Python 3, start with the :ref:`automatic-conversion` page.
  56. .. If you don't know Python 3 yet, start with :ref:`python3-essentials`.
  57. .. _standard-library:
  58. Standard library reorganization
  59. -------------------------------
  60. :mod:`future` supports the standard library reorganization (PEP 3108) via
  61. one of several mechanisms, allowing most moved standard library modules
  62. to be accessed under their Python 3 names and locations in Python 2::
  63. from future import standard_library
  64. standard_library.install_aliases()
  65. # Then these Py3-style imports work on both Python 2 and Python 3:
  66. import socketserver
  67. import queue
  68. from collections import UserDict, UserList, UserString
  69. from collections import Counter, OrderedDict, ChainMap # even on Py2.6
  70. from itertools import filterfalse, zip_longest
  71. import html
  72. import html.entities
  73. import html.parser
  74. import http
  75. import http.client
  76. import http.server
  77. import http.cookies
  78. import http.cookiejar
  79. import urllib.request
  80. import urllib.parse
  81. import urllib.response
  82. import urllib.error
  83. import urllib.robotparser
  84. import xmlrpc.client
  85. import xmlrpc.server
  86. and others. For a complete list, see :ref:`direct-imports`.
  87. .. _py2-dependencies:
  88. Python 2-only dependencies
  89. --------------------------
  90. If you have dependencies that support only Python 2, you may be able to use the
  91. ``past`` module to automatically translate these Python 2 modules to Python 3
  92. upon import. First, install the Python 2-only package into your Python 3
  93. environment::
  94. $ pip3 install mypackagename --no-compile # to ignore SyntaxErrors
  95. (or use ``pip`` if this points to your Py3 environment.)
  96. Then add the following code at the top of your (Py3 or Py2/3-compatible)
  97. code::
  98. from past import autotranslate
  99. autotranslate(['mypackagename'])
  100. import mypackagename
  101. This feature is experimental, and we would appreciate your feedback on
  102. how well this works or doesn't work for you. Please file an issue `here
  103. <https://github.com/PythonCharmers/python-future>`_ or post to the
  104. `python-porting <https://mail.python.org/mailman/listinfo/python-porting>`_
  105. mailing list.
  106. For more information on the automatic translation feature, see :ref:`translation`.
  107. Next steps
  108. ----------
  109. For more information about writing Py2/3-compatible code, see:
  110. - :ref:`compatible-idioms`
  111. - :ref:`what-else`.