Skip to content
Newer
Older
100644 110 lines (89 sloc) 5.26 KB
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
1 Foreword
2 ========
3
4 Read this before you get started with Flask. This hopefully answers some
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
5 questions about the purpose and goals of the project, and when you
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
6 should or should not be using it.
7
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
8 What does "micro" mean?
9 -----------------------
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
10
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
11 To me, the "micro" in microframework refers not only to the simplicity and
12 small size of the framework, but also to the typically limited complexity
56796f0 @mitsuhiko More doc changes regarding foreword
authored
13 and size of applications that are written with the framework. Also the
14 fact that you can have an entire application in a single Python file. To
15 be approachable and concise, a microframework sacrifices a few features
16 that may be necessary in larger or more complex applications.
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
17
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
18 For example, Flask uses thread-local objects internally so that you don't
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
19 have to pass objects around from function to function within a request in
20 order to stay threadsafe. While this is a really easy approach and saves
bca1acf @mitsuhiko Rewrote becoming big and foreword
authored
21 you a lot of time, it might also cause some troubles for very large
22 applications because changes on these thread-local objects can happen
23 anywhere in the same thread.
24
25 Flask provides some tools to deal with the downsides of this approach but
cd48332 @mitsuhiko Rewrote parts of the foreword and becoming big section
authored
26 it might be an issue for larger applications because in theory
27 modifications on these objects might happen anywhere in the same thread.
28
29 Flask is also based on convention over configuration, which means that
30 many things are preconfigured. For example, by convention, templates and
31 static files are in subdirectories within the Python source tree of the
32 application.
33
34 The main reason however why Flask is called a "microframework" is the idea
35 to keep the core simple but extensible. There is database abstraction
36 layer, no form validation or anything else where different libraries
37 already exist that can handle that. However Flask knows the concept of
38 extensions that can add this functionality into your application as if it
39 was implemented in Flask itself. There are currently extensions for
40 object relational mappers, form validation, upload handling, various open
41 authentication technologies and more.
bca1acf @mitsuhiko Rewrote becoming big and foreword
authored
42
43 However Flask is not much code and built in a very solid foundation and
44 with that very easy to adapt for large applications. If you are
45 interested in that, check out the :ref:`becomingbig` chapter.
3d719f3 @mitsuhiko Added docs, fixed some bugs I introduced last commit
authored
46
c0abdc4 @mitsuhiko Interlinked design docs better
authored
47 If you are curious about the Flask design principles, head over to the
48 section about :ref:`design`.
49
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
50 A Framework and an Example
05f36c7 @mitsuhiko Heavily improved documentation
authored
51 --------------------------
52
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
53 Flask is not only a microframework; it is also an example. Based on
05f36c7 @mitsuhiko Heavily improved documentation
authored
54 Flask, there will be a series of blog posts that explain how to create a
55 framework. Flask itself is just one way to implement a framework on top
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
56 of existing libraries. Unlike many other microframeworks, Flask does not
57 try to implement everything on its own; it reuses existing code.
05f36c7 @mitsuhiko Heavily improved documentation
authored
58
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
59 Web Development is Dangerous
60 ----------------------------
61
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
62 I'm not joking. Well, maybe a little. If you write a web
63 application, you are probably allowing users to register and leave their
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
64 data on your server. The users are entrusting you with data. And even if
65 you are the only user that might leave data in your application, you still
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
66 want that data to be stored securely.
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
67
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
68 Unfortunately, there are many ways the security of a web application can be
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
69 compromised. Flask protects you against one of the most common security
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
70 problems of modern web applications: cross-site scripting (XSS). Unless
71 you deliberately mark insecure HTML as secure, Flask and the underlying
72 Jinja2 template engine have you covered. But there are many more ways to
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
73 cause security problems.
74
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
75 The documentation will warn you about aspects of web development that
76 require attention to security. Some of these security concerns
77 are far more complex than one might think, and we all sometimes underestimate
78 the likelihood that a vulnerability will be exploited, until a clever
79 attacker figures out a way to exploit our applications. And don't think
80 that your application is not important enough to attract an attacker.
81 Depending on the kind of attack, chances are that automated bots are
82 probing for ways to fill your database with spam, links to malicious
83 software, and the like.
4671429 @mitsuhiko Added a security section to the foreword and a footnote to the g
authored
84
f3dd3da Copy edited and partially rewrote the foreword.
Matt Campbell authored
85 So always keep security in mind when doing web development.
9991cfa @mitsuhiko Added notes for Python 3
authored
86
87 The Status of Python 3
88 ----------------------
89
90 Currently the Python community is in the process of improving libraries to
91 support the new iteration of the Python programming language.
92 Unfortunately there are a few problems with Python 3, namely the missing
93 consent on what WSGI for Python 3 should look like. These problems are
94 partially caused by changes in the language that went unreviewed for too
95 long, also partially the ambitions of everyone involved to drive the WSGI
96 standard forward.
97
98 Because of that we strongly recommend against using Python 3 for web
99 development of any kind and wait until the WSGI situation is resolved.
100 You will find a couple of frameworks and web libraries on PyPI that claim
101 Python 3 support, but this support is based on the broken WSGI
102 implementation provided by Python 3.0 and 3.1 which will most likely
103 change in the near future.
104
105 Werkzeug and Flask will be ported to Python 3 as soon as a solution for
106 WSGI is found, and we will provide helpful tips how to upgrade existing
107 applications to Python 3. Until then, we strongly recommend using Python
108 2.6 and 2.7 with activated Python 3 warnings during development, as well
559d281 @mitsuhiko Expanded the security docs to mention unquoted attributes as dangerous
authored
109 as the unicode literals `__future__` feature.
Something went wrong with that request. Please try again.