Added notes on Python 3

docs/advanced_foreword.rst

@@ -52,17 +52,18 @@ The Status of Python 3
 Currently the Python community is in the process of improving libraries to
 support the new iteration of the Python programming language.  While the
 situation is greatly improving there are still some issues that make it
-hard for us to switch over to Python 3 just now.  These problems are
+hard for users to switch over to Python 3 just now.  These problems are
 partially caused by changes in the language that went unreviewed for too
 long, partially also because we have not quite worked out how the lower-
 level API should change to account for the Unicode differences in Python 3.
 
-Werkzeug and Flask will be ported to Python 3 as soon as a solution for
+We strongly recommend using Python 2.6 and 2.7 with activated Python 3
-the changes is found, and we will provide helpful tips how to upgrade
+warnings during development.  If you plan on upgrading to Python 3 in the
-existing applications to Python 3.  Until then, we strongly recommend
+near future we strongly recommend that you read `How to write forwards
-using Python 2.6 and 2.7 with activated Python 3 warnings during
+compatible Python code
-development.  If you plan on upgrading to Python 3 in the near future we
+<http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
-strongly recommend that you read `How to write forwards compatible
+
-Python code <http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
+If you do want to dive into Python 3 already have a look at the
+:ref:`python3_support` page.
 
 Continue to :ref:`installation` or the :ref:`quickstart`.

docs/contents.rst.inc

@@ -53,6 +53,7 @@ Design notes, legal information and changelog are here for the interested.
    unicode
    extensiondev
    styleguide
+   python3
    upgrading
    changelog
    license

docs/installation.rst

@@ -14,7 +14,8 @@ could do that, but the most kick-ass method is virtualenv, so let's have a look
 at that first.
 
 You will need Python 2.6 or higher to get started, so be sure to have an
-up-to-date Python 2.x installation.  Python 3.x is not supported.
+up-to-date Python 2.x installation.  For using Flask with Python 3 have a
+look at :ref:`python3-support`.
 
 .. _virtualenv:
 

docs/python3.rst

@@ -0,0 +1,52 @@
+.. _python3_support:
+
+Python 3 Support
+================
+
+Flask and all of its dependencies support Python 3 so you can in theory
+start working on it already.  There are however a few things you should be
+aware of before you start using Python 3 for your next project.
+
+API Stability
+-------------
+
+Some of the decisions made in regards to unicode and byte untilization on
+Python 3 make it hard to write low level code.  This mainly affects WSGI
+middlewares and interacting with the WSGI provided information.  Werkzeug
+wraps all that information in high-level helpers but some of those were
+specifically added for the Python 3 support and are quite new.
+
+A lot of the documentation out there on using WSGI leaves out those
+details as it was written before WSGI was updated to Python 3.  While the
+API for Werkzeug and Flask on Python 2.x should not change much we cannot
+guarantee that this won't happen on Python 3.
+
+Few Users
+---------
+
+Python 3 currently has less than 1% of the users of Python 2 going by PyPI
+download stats.  As a result many of the problems you will encounter are
+probably hard to search for on the internet if they are Python 3 specific.
+
+Small Ecosystem
+---------------
+
+The majority of the Flask extensions, all of the documentation and the
+vast majority of the PyPI provided libraries do not support Python 3 yet.
+Even if you start your project with knowing that all you will need is
+supported by Python 3 you don't know what happens six months from now.  If
+you are adventurous you can start porting libraries on your own, but that
+is nothing for the faint of heart.
+
+Recommendations
+---------------
+
+Unless you are already familiar with the differences in the versions we
+recommend sticking to current versions of Python until the ecosystem
+caught up.
+
+The majority of the upgrade pain is in the lower-level libararies like
+Flask and Werkzeug and not in the actual high-level application code.  For
+instance all of the Flask examples that are in the Flask repository work
+out of the box on both 2.x and 3.x and did not require a single line of
+code changed.