Skip to content

Commit 0ac9582

Browse files
mitsuhikomitsuhiko
committed
Added notes on Python 3
1 parent 2c9c269 commit 0ac9582

File tree

4 files changed

+64
-9
lines changed

4 files changed

+64
-9
lines changed

‎docs/advanced_foreword.rst

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,18 @@ The Status of Python 3
5252
Currently the Python community is in the process of improving libraries to
5353
support the new iteration of the Python programming language. While the
5454
situation is greatly improving there are still some issues that make it
55-
hard for us to switch over to Python 3 just now. These problems are
55+
hard for users to switch over to Python 3 just now. These problems are
5656
partially caused by changes in the language that went unreviewed for too
5757
long, partially also because we have not quite worked out how the lower-
5858
level API should change to account for the Unicode differences in Python 3.
5959

60-
Werkzeug and Flask will be ported to Python 3 as soon as a solution for
61-
the changes is found, and we will provide helpful tips how to upgrade
62-
existing applications to Python 3. Until then, we strongly recommend
63-
using Python 2.6 and 2.7 with activated Python 3 warnings during
64-
development. If you plan on upgrading to Python 3 in the near future we
65-
strongly recommend that you read `How to write forwards compatible
66-
Python code <http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
60+
We strongly recommend using Python 2.6 and 2.7 with activated Python 3
61+
warnings during development. If you plan on upgrading to Python 3 in the
62+
near future we strongly recommend that you read `How to write forwards
63+
compatible Python code
64+
<http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
65+
66+
If you do want to dive into Python 3 already have a look at the
67+
:ref:`python3_support` page.
6768

6869
Continue to :ref:`installation` or the :ref:`quickstart`.

‎docs/contents.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ Design notes, legal information and changelog are here for the interested.
5353
unicode
5454
extensiondev
5555
styleguide
56+
python3
5657
upgrading
5758
changelog
5859
license

‎docs/installation.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ could do that, but the most kick-ass method is virtualenv, so let's have a look
1414
at that first.
1515

1616
You will need Python 2.6 or higher to get started, so be sure to have an
17-
up-to-date Python 2.x installation. Python 3.x is not supported.
17+
up-to-date Python 2.x installation. For using Flask with Python 3 have a
18+
look at :ref:`python3-support`.
1819

1920
.. _virtualenv:
2021

‎docs/python3.rst

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _python3_support:
2+
3+
Python 3 Support
4+
================
5+
6+
Flask and all of its dependencies support Python 3 so you can in theory
7+
start working on it already. There are however a few things you should be
8+
aware of before you start using Python 3 for your next project.
9+
10+
API Stability
11+
-------------
12+
13+
Some of the decisions made in regards to unicode and byte untilization on
14+
Python 3 make it hard to write low level code. This mainly affects WSGI
15+
middlewares and interacting with the WSGI provided information. Werkzeug
16+
wraps all that information in high-level helpers but some of those were
17+
specifically added for the Python 3 support and are quite new.
18+
19+
A lot of the documentation out there on using WSGI leaves out those
20+
details as it was written before WSGI was updated to Python 3. While the
21+
API for Werkzeug and Flask on Python 2.x should not change much we cannot
22+
guarantee that this won't happen on Python 3.
23+
24+
Few Users
25+
---------
26+
27+
Python 3 currently has less than 1% of the users of Python 2 going by PyPI
28+
download stats. As a result many of the problems you will encounter are
29+
probably hard to search for on the internet if they are Python 3 specific.
30+
31+
Small Ecosystem
32+
---------------
33+
34+
The majority of the Flask extensions, all of the documentation and the
35+
vast majority of the PyPI provided libraries do not support Python 3 yet.
36+
Even if you start your project with knowing that all you will need is
37+
supported by Python 3 you don't know what happens six months from now. If
38+
you are adventurous you can start porting libraries on your own, but that
39+
is nothing for the faint of heart.
40+
41+
Recommendations
42+
---------------
43+
44+
Unless you are already familiar with the differences in the versions we
45+
recommend sticking to current versions of Python until the ecosystem
46+
caught up.
47+
48+
The majority of the upgrade pain is in the lower-level libararies like
49+
Flask and Werkzeug and not in the actual high-level application code. For
50+
instance all of the Flask examples that are in the Flask repository work
51+
out of the box on both 2.x and 3.x and did not require a single line of
52+
code changed.

0 commit comments

Comments
 (0)