Skip to content
Newer
Older
100644 100 lines (82 sloc) 5.06 KB
c78070d Wrapped paragraphs; changed some words.
Max authored
1 Foreword
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
2 ========
3
c78070d Wrapped paragraphs; changed some words.
Max authored
4 Read this before you get started with Flask. This hopefully answers some
5 questions about the purpose and goals of the project, and when you
6 should or should not be using it.
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
7
c78070d Wrapped paragraphs; changed some words.
Max authored
8 What does "micro" mean?
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
9 -----------------------
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
10
c78070d Wrapped paragraphs; changed some words.
Max authored
11 Flask considers the "micro" in microframework to refer not only to the
12 simplicity and small size of the framework, but also to the fact that it does
13 not make many decisions for you. While Flask does pick a templating engine
14 for you, we won't make such decisions for your datastore or other parts.
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
15
c78070d Wrapped paragraphs; changed some words.
Max authored
16 However, to us the term “micro” does not mean that the whole implementation
17 has to fit into a single Python file.
bca1acf @mitsuhiko Rewrote becoming big and foreword
authored
18
dc05722 @mitsuhiko Made the foreword less defensive.
authored
19 One of the design decisions with Flask was that simple tasks should be
c78070d Wrapped paragraphs; changed some words.
Max authored
20 simple; they should not take a lot of code and yet they should not limit you.
21 Because of that we made a few design choices that some people might find
22 surprising or unorthodox. For example, Flask uses thread-local objects
23 internally so that you don't have to pass objects around from function to
24 function within a request in order to stay threadsafe. While this is a
25 really easy approach and saves you a lot of time, it might also cause some
26 troubles for very large applications because changes on these thread-local
27 objects can happen anywhere in the same thread. In order to solve these
28 problems we don't hide the thread locals for you but instead embrace them
29 and provide you with a lot of tools to make it as pleasant as possible to
30 work with them.
cd48332 @mitsuhiko Rewrote parts of the foreword and becoming big section
authored
31
32 Flask is also based on convention over configuration, which means that
c78070d Wrapped paragraphs; changed some words.
Max authored
33 many things are preconfigured. For example, by convention templates and
34 static files are stored in subdirectories within the application's Python source tree.
35 While this can be changed you usually don't have to.
cd48332 @mitsuhiko Rewrote parts of the foreword and becoming big section
authored
36
c78070d Wrapped paragraphs; changed some words.
Max authored
37 The main reason Flask is called a "microframework" is the idea
38 to keep the core simple but extensible. There is no database abstraction
cd48332 @mitsuhiko Rewrote parts of the foreword and becoming big section
authored
39 layer, no form validation or anything else where different libraries
c78070d Wrapped paragraphs; changed some words.
Max authored
40 already exist that can handle that. However Flask supports
41 extensions to add such functionality to your application as if it
42 was implemented in Flask itself. There are currently extensions for
43 object-relational mappers, form validation, upload handling, various open
44 authentication technologies and more.
45
46 Since Flask is based on a very solid foundation there is not a lot of code
47 in Flask itself. As such it's easy to adapt even for large applications
48 and we are making sure that you can either configure it as much as
49 possible by subclassing things or by forking the entire codebase. If you
50 are interested in that, check out the :ref:`becomingbig` chapter.
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
51
c0abdc4 @mitsuhiko Interlinked design docs better
authored
52 If you are curious about the Flask design principles, head over to the
53 section about :ref:`design`.
54
c78070d Wrapped paragraphs; changed some words.
Max authored
55 Web Development is Dangerous
56 ----------------------------
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
57
c78070d Wrapped paragraphs; changed some words.
Max authored
58 If you write a web application, you are probably allowing users to register
59 and leave their data on your server. The users are entrusting you with data.
60 And even if you are the only user that might leave data in your application,
61 you still want that data to be stored securely.
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
62
c78070d Wrapped paragraphs; changed some words.
Max authored
63 Unfortunately, there are many ways the security of a web application can be
64 compromised. Flask protects you against one of the most common security
65 problems of modern web applications: cross-site scripting (XSS). Unless
66 you deliberately mark insecure HTML as secure, Flask and the underlying
67 Jinja2 template engine have you covered. But there are many more ways to
68 cause security problems.
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
69
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
70 The documentation will warn you about aspects of web development that
c78070d Wrapped paragraphs; changed some words.
Max authored
71 require attention to security. Some of these security concerns
72 are far more complex than one might think, and we all sometimes underestimate
73 the likelihood that a vulnerability will be exploited - until a clever
74 attacker figures out a way to exploit our applications. And don't think
75 that your application is not important enough to attract an attacker.
76 Depending on the kind of attack, chances are that automated bots are
77 probing for ways to fill your database with spam, links to malicious
78 software, and the like.
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
79
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
80 So always keep security in mind when doing web development.
9991cfa @mitsuhiko Added notes for Python 3
authored
81
c78070d Wrapped paragraphs; changed some words.
Max authored
82 The Status of Python 3
9991cfa @mitsuhiko Added notes for Python 3
authored
83 ----------------------
84
c78070d Wrapped paragraphs; changed some words.
Max authored
85 Currently the Python community is in the process of improving libraries to
86 support the new iteration of the Python programming language. While the
87 situation is greatly improving there are still some issues that make it
88 hard for us to switch over to Python 3 just now. These problems are
89 partially caused by changes in the language that went unreviewed for too
90 long, partially also because we have not quite worked out how the lower-
91 level API should change to account for the Unicode differences in Python 3.
92
93 Werkzeug and Flask will be ported to Python 3 as soon as a solution for
94 the changes is found, and we will provide helpful tips how to upgrade
95 existing applications to Python 3. Until then, we strongly recommend
96 using Python 2.6 and 2.7 with activated Python 3 warnings during
97 development. If you plan on upgrading to Python 3 in the near future we
98 strongly recommend that you read `How to write forwards compatible
99 Python code <http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
Something went wrong with that request. Please try again.