playground
/
flask
mirror of https://github.com/mitsuhiko/flask.git
1
0
Fork 0
Code Issues Releases Activity
Browse Source

Wrapped paragraphs; changed some words.

pull/438/head
Max 13 years ago
parent
d8c2ec4cd8
commit
c78070d862
1 changed files with 74 additions and 79 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 147
      docs/foreword.rst

147
docs/foreword.rst
Unescape View File

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

Write Preview
Loading…
Cancel
Save