<commit_before>.. _quickstart-guide:

Quick-start guide
=================

You can use ``future`` to help to port your code from Python 2 to Python 3
today -- and still have it run on Python 2.

If you already have Python 3 code, you can instead use ``future`` to
offer Python 2 compatibility with almost no extra work.

Installation
------------

To install the latest stable version, type::

    pip install future

If you would prefer the latest development version, it is available `here <https://github.com/PythonCharmers/python-future>`_.


If you are writing code from scratch
------------------------------------

The easiest way is to start each new module with these lines::

    from __future__ import (absolute_import, division,
                            print_function, unicode_literals)
    from future.builtins import *

Then write standard Python 3 code. The :mod:`future` package will
provide support for running your code on Python 2.6 and 2.7 mostly unchanged.

- For more examples, see :ref:`overview`.
- For explicit import forms, see :ref:`imports`.
- For more details, see :ref:`what-else`.


To convert existing Python 3 code
---------------------------------

To offer backward compatibility with Python 2 from your Python 3 code,
you can use the ``pasteurize`` script. This adds these lines at the top of each
module::

    from __future__ import absolute_import
    from __future__ import division
    from __future__ import print_function
    from __future__ import unicode_literals

    from future.builtins import open
    from future.builtins import str
    # etc., as needed

    from future import standard_library
    standard_library.install_hooks()
    
and converts several Python 3-only constructs (like keyword-only arguments) to a
form compatible with both Py3 and Py2. Most remaining Python 3 code should
simply work on Python 2.

See :ref:`backwards-conversion` for more details.


To convert existing Python 2 code
---------------------------------

Start with the :ref:`automatic-conversion` page.

.. If you already know Python 3, start with the :ref:`automatic-conversion` page.
.. If you don't know Python 3 yet, start with :ref:`python3-essentials`.


.. _standard-library:

Standard library reorganization
-------------------------------

:mod:`future` supports the standard library reorganization (PEP 3108)
via import hooks, allowing almost all moved standard library modules to
be accessed under their Python 3 names and locations in Python 2::
    
    from future import standard_library
    with standard_library.hooks():
        import socketserver
        import queue
        import configparser
        import test.support
        import html.parser
        from collections import UserList
        from itertools import filterfalse, zip_longest
        from http.client import HttpConnection
        # and other moved modules and definitions

:mod:`future` also includes backports for these stdlib modules from Py3
that were heavily refactored versus Py2::
    
    import html
    import html.entities
    import html.parser

    import http
    import http.client
    import http.server
    import http.cookies
    import http.cookiejar

    import urllib
    import urllib.parse
    import urllib.request
    import urllib.error

    import xmlrpc.client
    import xmlrpc.server


The following modules are currently not supported, but we aim to support them in
the future::
    
If you need one of these, please open an issue `here
<https://github.com/PythonCharmers/python-future>`_.

For other forms of imports from the standard library, see
:ref:`standard-library-imports`.

For more information on interfaces that have changed in the standard library
between Python 2 and Python 3, see :ref:`stdlib-incompatibilities`.


.. _py2-dependencies:

Python 2-only dependencies
--------------------------

If you have dependencies that support only Python 2, you may be able to use the
``past`` module to automatically translate these Python 2 modules to Python 3
upon import. First, install the Python 2-only package into your Python 3
environment::

    $ pip3 install mypackagename --no-compile   # to ignore SyntaxErrors
    
(or use ``pip`` if this points to your Py3 environment.)

Then add the following code at the top of your (Py3 or Py2/3-compatible)
code::

    from past import autotranslate
    autotranslate(['mypackagename'])
    import mypackagename

This feature is experimental, and we would appreciate your feedback on
how well this works or doesn't work for you. Please file an issue `here
<https://github.com/PythonCharmers/python-future>`_ or post to the
`python-porting <https://mail.python.org/mailman/listinfo/python-porting>`_
mailing list.

For more information on the automatic translation feature, see :ref:`translation`.

Next steps
----------
For more information about writing Py3/2-compatible code, see :ref:`what-else`.
<commit_msg>Update docs/quickstart.rst on standard library imports<commit_after>.. _quickstart-guide:

Quick-start guide
=================

You can use ``future`` to help to port your code from Python 2 to Python 3
today -- and still have it run on Python 2.

If you already have Python 3 code, you can instead use ``future`` to
offer Python 2 compatibility with almost no extra work.

Installation
------------

To install the latest stable version, type::

    pip install future

If you would prefer the latest development version, it is available `here <https://github.com/PythonCharmers/python-future>`_.


If you are writing code from scratch
------------------------------------

The easiest way is to start each new module with these lines::

    from __future__ import (absolute_import, division,
                            print_function, unicode_literals)
    from future.builtins import *

Then write standard Python 3 code. The :mod:`future` package will
provide support for running your code on Python 2.6 and 2.7 mostly unchanged.

- For more examples, see :ref:`overview`.
- For explicit import forms, see :ref:`imports`.
- For more details, see :ref:`what-else`.


To convert existing Python 3 code
---------------------------------

To offer backward compatibility with Python 2 from your Python 3 code,
you can use the ``pasteurize`` script. This adds these lines at the top of each
module::

    from __future__ import absolute_import
    from __future__ import division
    from __future__ import print_function
    from __future__ import unicode_literals

    from future.builtins import open
    from future.builtins import str
    # etc., as needed

    from future import standard_library
    standard_library.install_hooks()
    
and converts several Python 3-only constructs (like keyword-only arguments) to a
form compatible with both Py3 and Py2. Most remaining Python 3 code should
simply work on Python 2.

See :ref:`backwards-conversion` for more details.


To convert existing Python 2 code
---------------------------------

Start with the :ref:`automatic-conversion` page.

.. If you already know Python 3, start with the :ref:`automatic-conversion` page.
.. If you don't know Python 3 yet, start with :ref:`python3-essentials`.


.. _standard-library:

Standard library reorganization
-------------------------------

:mod:`future` supports the standard library reorganization (PEP 3108)
via import hooks, allowing almost all moved standard library modules to
be accessed under their Python 3 names and locations in Python 2::
    
    from future import standard_library
    with standard_library.hooks():
        import socketserver
        import queue
        import configparser
        from collections import UserList
        from itertools import filterfalse, zip_longest

        import html
        import html.entities
        import html.parser

        import http
        import http.client
        import http.server
        import http.cookies
        import http.cookiejar

        import xmlrpc.client
        import xmlrpc.server

``urllib`` currently requires explicit imports because the name clashes with that on Python 2::

    from future.standard_library import import_
    urllib = import_('urllib')
    import_('urllib.parse')
    import_('urllib.request')
    import_('urllib.error')

For an explanation of these and other forms of imports from the standard
library, see :ref:`standard-library-imports`.


.. _py2-dependencies:

Python 2-only dependencies
--------------------------

If you have dependencies that support only Python 2, you may be able to use the
``past`` module to automatically translate these Python 2 modules to Python 3
upon import. First, install the Python 2-only package into your Python 3
environment::

    $ pip3 install mypackagename --no-compile   # to ignore SyntaxErrors
    
(or use ``pip`` if this points to your Py3 environment.)

Then add the following code at the top of your (Py3 or Py2/3-compatible)
code::

    from past import autotranslate
    autotranslate(['mypackagename'])
    import mypackagename

This feature is experimental, and we would appreciate your feedback on
how well this works or doesn't work for you. Please file an issue `here
<https://github.com/PythonCharmers/python-future>`_ or post to the
`python-porting <https://mail.python.org/mailman/listinfo/python-porting>`_
mailing list.

For more information on the automatic translation feature, see :ref:`translation`.


Next steps
----------
For more information about writing Py3/2-compatible code, see :ref:`what-else`.

{'fraction_non_alphanumeric': 0.10014712063892392, 'fraction_numerical': 0.009352669188734763, 'mean_word_length': 3.0636208368915456, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, 'https://': 7, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '724269', 'n_tokens_mistral': 2506, 'n_tokens_neox': 2336, 'n_words': 1119}