From cd4833222eccf7e70380a42b69d5e766a84a6b63 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sun, 18 Jul 2010 20:57:02 +0200 Subject: [PATCH] Rewrote parts of the foreword and becoming big section --- docs/becomingbig.rst | 36 ++++++++++++++++++++++++------------ docs/foreword.rst | 38 ++++++++++++++++---------------------- 2 files changed, 40 insertions(+), 34 deletions(-) diff --git a/docs/becomingbig.rst b/docs/becomingbig.rst index 916aa324..6c95c6e2 100644 --- a/docs/becomingbig.rst +++ b/docs/becomingbig.rst @@ -18,12 +18,13 @@ expand on that. Flask is designed to be extended and modified in a couple of different ways: +- Flask extensions. For a lot of reusable functionality you can create + extensions. For extensions a number of hooks exist throughout Flask + with signals and callback functions. + - Subclassing. The majority of functionality can be changed by creating a new subclass of the :class:`~flask.Flask` class and overriding - some methods. - -- Flask extensions. For a lot of reusable functionality you can create - extensions. + methods provided for this exact purpose. - Forking. If nothing else works out you can just take the Flask codebase at a given point and copy/paste it into your application @@ -49,8 +50,10 @@ reflected in the license of Flask. You don't have to contribute any changes back if you decide to modify the framework. The downside of forking is of course that Flask extensions will most -likely break because the new framework has a different import name and -because of that forking should be the last resort. +likely break because the new framework has a different import name. +Furthermore integrating upstream changes can be a complex process, +depending on the number of changes. Because of that, forking should be +the very last resort. Scaling like a Pro ------------------ @@ -68,9 +71,18 @@ support a second server. There is only one limiting factor regarding scaling in Flask which are the context local proxies. They depend on context which in Flask is -defined as being either a thread or a greenlet. Separate processes are -fine as well. If your server uses some kind of concurrency that is not -based on threads or greenlets, Flask will no longer be able to support -these global proxies. However the majority of servers are using either -threads, greenlets or separate processes to achieve concurrency which are -all methods well supported by the underlying Werkzeug library. +defined as being either a thread, process or greenlet. If your server +uses some kind of concurrency that is not based on threads or greenlets, +Flask will no longer be able to support these global proxies. However the +majority of servers are using either threads, greenlets or separate +processes to achieve concurrency which are all methods well supported by +the underlying Werkzeug library. + +Dialogue with the Community +--------------------------- + +The Flask developers are very interested to keep everybody happy, so as +soon as you find an obstacle in your way, caused by Flask, don't hesitate +to contact the developers on the mailinglist or IRC channel. The best way +for the Flask and Flask-extension developers to improve it for larger +applications is getting feedback from users. diff --git a/docs/foreword.rst b/docs/foreword.rst index b43fe870..58d47a3b 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -23,11 +23,22 @@ applications because changes on these thread-local objects can happen anywhere in the same thread. Flask provides some tools to deal with the downsides of this approach but -it might be an issue for larger applications. Flask is also based on -convention over configuration, which means that many things are -preconfigured and will work well for smaller applications but not so well -for larger ones. For example, by convention, templates and static files -are in subdirectories within the Python source tree of the application. +it might be an issue for larger applications because in theory +modifications on these objects might happen anywhere in the same thread. + +Flask is also based on convention over configuration, which means that +many things are preconfigured. For example, by convention, templates and +static files are in subdirectories within the Python source tree of the +application. + +The main reason however why Flask is called a "microframework" is the idea +to keep the core simple but extensible. There is database abstraction +layer, no form validation or anything else where different libraries +already exist that can handle that. However Flask knows the concept of +extensions that can add this functionality into your application as if it +was implemented in Flask itself. There are currently extensions for +object relational mappers, form validation, upload handling, various open +authentication technologies and more. However Flask is not much code and built in a very solid foundation and with that very easy to adapt for large applications. If you are @@ -69,20 +80,3 @@ probing for ways to fill your database with spam, links to malicious software, and the like. So always keep security in mind when doing web development. - -Target Audience ---------------- - -Is Flask for you? If your application is small or medium sized and does -not depend on very complex database structures, Flask is the Framework for -you. It was designed from the ground up to be easy to use, and built on -the firm foundation of established principles, good intentions, and -mature, widely used libraries. Recent versions of Flask scale nicely -within reasonable bounds, and if you grow larger, you won't have any -trouble adjusting Flask for your new application size. - -If you suddenly discover that your application grows larger than -originally intended, head over to the :ref:`becomingbig` section to see -some possible solutions for larger applications. - -Satisfied? Then let's proceed with :ref:`installation`.