maya-chen/flask
1
0
Fork 0
forked from orbit-oss/flask
Code Pull requests Activity

Fixed linebreaks.

Browse source
This commit is contained in:
Max 2012-03-12 15:03:26 -07:00
parent 74a72e86ad
commit d8c2ec4cd8
1 changed files with 77 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

150
docs/foreword.rst
View file

@ -1,100 +1,104 @@
Foreword Foreword
======== ========
Read this before you get started with Flask. This hopefully answers some Read this before you get started with Flask. This hopefully answers
questions about the purpose and goals of the project, and when you some questions about the purpose and goals of the project, and when
should or should not be using it. you should or should not be using it.
What does "micro" mean? What does "micro" mean?
----------------------- -----------------------
As Flask considers it, the "micro" in microframework refers not only to the simplicity and As Flask considers it, the "micro" in microframework refers not only
small size of the framework, but also the fact that it does not make many to the simplicity and small size of the framework, but also the fact
decisions for you. While Flask does pick a templating engine for you, we that it does not make many decisions for you. While Flask does pick a
won't make such decisions for your datastore or other parts. templating engine for you, we won't make such decisions for your
datastore or other parts.
However, to us the term “micro” does not mean that the whole implementation However, to us the term “micro” does not mean that the whole
has to fit into a single Python file. implementation has to fit into a single Python file.
One of the design decisions with Flask was that simple tasks should be One of the design decisions with Flask was that simple tasks should be
simple; they should not take a lot of code and yet they should not limit you. simple; they should not take a lot of code and yet they should not
Because of that we made a few design choices that some people might find limit you. Because of that we made a few design choices that some
surprising or unorthodox. For example, Flask uses thread-local objects people might find surprising or unorthodox. For example, Flask uses
internally so that you don't have to pass objects around from function to thread-local objects internally so that you don't have to pass objects
function within a request in order to stay threadsafe. While this is a around from function to function within a request in order to stay
really easy approach and saves you a lot of time, it might also cause some threadsafe. While this is a really easy approach and saves you a lot
troubles for very large applications because changes on these thread-local of time, it might also cause some troubles for very large applications
objects can happen anywhere in the same thread. In order to solve these because changes on these thread-local objects can happen anywhere in
problems we don't hide the thread locals for you but instead embrace them the same thread. In order to solve these problems we don't hide the
and provide you with a lot of tools to make it as pleasant as possible to thread locals for you but instead embrace them and provide you with a
work with them. lot of tools to make it as pleasant as possible to work with them.
Flask is also based on convention over configuration, which means that Flask is also based on convention over configuration, which means that
many things are preconfigured. For example, by convention templates and many things are preconfigured. For example, by convention templates
static files are stored in subdirectories within the application's Python source tree. and static files are stored in subdirectories within the application's
While this can be changed you usually don't have to. Python source tree. While this can be changed you usually don't have
to.
The main reason Flask is called a "microframework" is the idea The main reason Flask is called a "microframework" is the idea to keep
to keep the core simple but extensible. There is no database abstraction the core simple but extensible. There is no database abstraction
layer, no form validation or anything else where different libraries layer, no form validation or anything else where different libraries
already exist that can handle that. However Flask supports already exist that can handle that. However Flask supports extensions
extensions to add such functionality to your application as if it to add such functionality to your application as if it was implemented
was implemented in Flask itself. There are currently extensions for in Flask itself. There are currently extensions for object-relational
object-relational mappers, form validation, upload handling, various open mappers, form validation, upload handling, various open authentication
authentication technologies and more. technologies and more.
Since Flask is based on a very solid foundation there is not a lot of code Since Flask is based on a very solid foundation there is not a lot of
in Flask itself. As such it's easy to adapt even for large applications code in Flask itself. As such it's easy to adapt even for large
and we are making sure that you can either configure it as much as applications and we are making sure that you can either configure it
possible by subclassing things or by forking the entire codebase. If you as much as possible by subclassing things or by forking the entire
are interested in that, check out the :ref:`becomingbig` chapter. codebase. If you are interested in that, check out the
:ref:`becomingbig` chapter.
If you are curious about the Flask design principles, head over to the If you are curious about the Flask design principles, head over to the
section about :ref:`design`. section about :ref:`design`.
Web Development is Dangerous Web Development is Dangerous ----------------------------
----------------------------
If you write a web If you write a web application, you are probably allowing users to
application, you are probably allowing users to register and leave their register and leave their data on your server. The users are
data on your server. The users are entrusting you with data. And even if entrusting you with data. And even if you are the only user that
you are the only user that might leave data in your application, you still might leave data in your application, you still want that data to be
want that data to be stored securely. stored securely.
Unfortunately, there are many ways the security of a web application can be Unfortunately, there are many ways the security of a web application
compromised. Flask protects you against one of the most common security can be compromised. Flask protects you against one of the most common
problems of modern web applications: cross-site scripting (XSS). Unless security problems of modern web applications: cross-site scripting
you deliberately mark insecure HTML as secure, Flask and the underlying (XSS). Unless you deliberately mark insecure HTML as secure, Flask
Jinja2 template engine have you covered. But there are many more ways to and the underlying Jinja2 template engine have you covered. But there
cause security problems. are many more ways to cause security problems.
The documentation will warn you about aspects of web development that The documentation will warn you about aspects of web development that
require attention to security. Some of these security concerns require attention to security. Some of these security concerns are
are far more complex than one might think, and we all sometimes underestimate far more complex than one might think, and we all sometimes
the likelihood that a vulnerability will be exploited - until a clever underestimate the likelihood that a vulnerability will be exploited -
attacker figures out a way to exploit our applications. And don't think until a clever attacker figures out a way to exploit our applications.
that your application is not important enough to attract an attacker. And don't think that your application is not important enough to
Depending on the kind of attack, chances are that automated bots are attract an attacker. Depending on the kind of attack, chances are that
probing for ways to fill your database with spam, links to malicious automated bots are probing for ways to fill your database with spam,
software, and the like. links to malicious software, and the like.
So always keep security in mind when doing web development. So always keep security in mind when doing web development.
The Status of Python 3 The Status of Python 3
---------------------- ----------------------
Currently the Python community is in the process of improving libraries to Currently the Python community is in the process of improving
support the new iteration of the Python programming language. While the libraries to support the new iteration of the Python programming
situation is greatly improving there are still some issues that make it language. While the situation is greatly improving there are still
hard for us to switch over to Python 3 just now. These problems are some issues that make it hard for us to switch over to Python 3 just
partially caused by changes in the language that went unreviewed for too now. These problems are partially caused by changes in the language
long, partially also because we have not quite worked out how the lower- that went unreviewed for too long, partially also because we have not
level API should change to account for the Unicode differences in Python 3. 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 Werkzeug and Flask will be ported to Python 3 as soon as a solution
the changes is found, and we will provide helpful tips how to upgrade for the changes is found, and we will provide helpful tips how to
existing applications to Python 3. Until then, we strongly recommend upgrade existing applications to Python 3. Until then, we strongly
using Python 2.6 and 2.7 with activated Python 3 warnings during recommend using Python 2.6 and 2.7 with activated Python 3 warnings
development. If you plan on upgrading to Python 3 in the near future we during development. If you plan on upgrading to Python 3 in the near
strongly recommend that you read `How to write forwards compatible future we strongly recommend that you read `How to write forwards
Python code <http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_. compatible Python code <http://lucumr.pocoo.org/2011/1/22/forwards-
compatible-python/>`_.