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

Copy edited and partially rewrote the foreword.

Browse source
This commit is contained in:
Matt Campbell 2010-06-26 13:27:59 +08:00 • committed by Armin Ronacher
parent 14fde07798
commit f3dd3da59e
2 changed files with 52 additions and 52 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/contents.rst.inc
View file

@ -1,9 +1,9 @@
User's Guide User's Guide
------------ ------------
This part of the documentation is written text and should give you an idea This part of the documentation, which is mostly prose, begins with some
how to work with Flask. It's a series of step-by-step instructions for background information about Flask, then focuses on step-by-step
web development. instructions for web development with Flask.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

98
docs/foreword.rst
View file

@ -2,90 +2,90 @@ Foreword
======== ========
Read this before you get started with Flask. This hopefully answers some Read this before you get started with Flask. This hopefully answers some
questions about the intention of the project, what it aims at and when you questions about the purpose and goals of the project, and when you
should or should not be using it. should or should not be using it.
What does Micro Mean? What does "micro" mean?
--------------------- -----------------------
The micro in microframework for me means on the one hand being small in To me, the "micro" in microframework refers not only to the simplicity and
size and complexity but on the other hand also that the complexity of the small size of the framework, but also to the typically limited complexity
applications that are written with these frameworks do not exceed a and size of applications that are written with the framework. To be
certain size. A microframework like Flask sacrifices a few things in approachable and concise, a microframework sacrifices a few features that
order to be approachable and to be as concise as possible. may be necessary in larger or more complex applications.
For example Flask uses thread local objects internally so that you don't For example, Flask uses thread-local objects internally so that you don't
have to pass objects around from function to function within a request in have to pass objects around from function to function within a request in
order to stay threadsafe. While this is a really easy approach and saves order to stay threadsafe. While this is a really easy approach and saves
you a lot of time, it also does not scale well to large applications. you a lot of time, it also does not scale well to large applications.
It's especially painful for more complex unittests and when you suddenly It's especially painful for more complex unittests, and when you suddenly
have to deal with code being executed outside of the context of a request have to deal with code being executed outside of the context of a request,
(for example if you have cronjobs). such as in cron jobs.
Flask provides some tools to deal with the downsides of this approach but Flask provides some tools to deal with the downsides of this approach, but
the core problem of this approach obviously stays. It is also based on the core problem remains. Flask is also based on convention over
convention over configuration which means that a lot of things are configuration, which means that many things are preconfigured and will
preconfigured in Flask and will work well for smaller applications but not work well for smaller applications but not so well for larger ones. For
so much for larger ones (where and how it looks for templates, static example, by convention, templates and static files are in subdirectories
files etc.) within the Python source tree of the application.
But don't worry if your application suddenly grows larger than it was But don't worry if your application suddenly grows larger
initially and you're afraid Flask might not grow with it. Even with and you're afraid Flask might not grow with it. Even with
larger frameworks you sooner or later will find out that you need larger frameworks, you'll eventually discover that you need
something the framework just cannot do for you without modification. something the framework just cannot do for you without modification.
If you are ever in that situation, check out the :ref:`becomingbig` If you are ever in that situation, check out the :ref:`becomingbig`
chapter. chapter.
A Framework and An Example A Framework and an Example
-------------------------- --------------------------
Flask is not only a microframework, it is also an example. Based on Flask is not only a microframework; it is also an example. Based on
Flask, there will be a series of blog posts that explain how to create a Flask, there will be a series of blog posts that explain how to create a
framework. Flask itself is just one way to implement a framework on top framework. Flask itself is just one way to implement a framework on top
of existing libraries. Unlike many other microframeworks Flask does not of existing libraries. Unlike many other microframeworks, Flask does not
try to implement anything on its own, it reuses existing code. try to implement everything on its own; it reuses existing code.
Web Development is Dangerous Web Development is Dangerous
---------------------------- ----------------------------
I'm not even joking. Well, maybe a little. If you write a web I'm not joking. Well, maybe a little. If you write a web
application you are probably allowing users to register and leave their application, you are probably allowing users to register and leave their
data on your server. The users are entrusting you with data. And even if data on your server. The users are entrusting you with data. And even if
you are the only user that might leave data in your application, you still you are the only user that might leave data in your application, you still
want that data to be stored in a secure manner. want that data to be stored securely.
Unfortunately there are many ways security of a web application can be Unfortunately, there are many ways the security of a web application can be
compromised. Flask protects you against one of the most common security compromised. Flask protects you against one of the most common security
problems of modern web applications: cross site scripting (XSS). Unless problems of modern web applications: cross-site scripting (XSS). Unless
you deliberately mark insecure HTML as secure Flask (and the underlying you deliberately mark insecure HTML as secure, Flask and the underlying
Jinja2 template engine) have you covered. But there are many more ways to Jinja2 template engine have you covered. But there are many more ways to
cause security problems. cause security problems.
Whenever something is dangerous where you have to watch out, the The documentation will warn you about aspects of web development that
documentation will tell you so. Some of the security concerns of web require attention to security. Some of these security concerns
development are far more complex than one might think and often we all end are far more complex than one might think, and we all sometimes underestimate
up in situations where we think "well, this is just far fetched, how could the likelihood that a vulnerability will be exploited, until a clever
that possibly be exploited" and then an intelligent guy comes along and attacker figures out a way to exploit our applications. And don't think
figures a way out to exploit that application. And don't think, your that your application is not important enough to attract an attacker.
application is not important enough for hackers to take notice. Depending Depending on the kind of attack, chances are that automated bots are
on the kind of attack, chances are there are automated botnets out there probing for ways to fill your database with spam, links to malicious
trying to figure out how to fill your database with viagra advertisements. software, and the like.
So always keep that in mind when doing web development. So always keep security in mind when doing web development.
Target Audience Target Audience
--------------- ---------------
Is Flask for you? If your application small-ish and does not depend on Is Flask for you? If your application is small-ish and does not depend on
too complex database structures, Flask is the Framework for you. It was very complex database structures, Flask is the Framework for you. It was
designed from the ground up to be easy to use, based on established designed from the ground up to be easy to use, and built on the firm
principles, good intentions and on top of two established libraries in foundation of established principles, good intentions, and mature, widely
widespread usage. Recent versions of Flask scale nicely within reasonable used libraries. Recent versions of Flask scale nicely within reasonable
bounds and if you grow larger, you won't have any troubles adjusting Flask bounds, and if you grow larger, you won't have any trouble adjusting Flask
for your new application size. for your new application size.
If you suddenly discover that your application grows larger than If you suddenly discover that your application grows larger than
originally intended, head over to the :ref:`becomingbig` section to see originally intended, head over to the :ref:`becomingbig` section to see
some possible solutions for larger applications. some possible solutions for larger applications.
Satisfied? Then head over to the :ref:`installation`. Satisfied? Then let's proceed with :ref:`installation`.