From 74a72e86addd80a060f1abf9fe51bfc3f5d5be8b Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 12 Mar 2012 14:58:26 -0700 Subject: [PATCH 1/4] Changed some things in the foreward to diminish its discouragement. --- docs/foreword.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/foreword.rst b/docs/foreword.rst index 7678d014..539f2897 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -8,7 +8,7 @@ should or should not be using it. What does "micro" mean? ----------------------- -To me, the "micro" in microframework refers not only to the simplicity and +As Flask considers it, the "micro" in microframework refers not only to the simplicity and small size of the framework, but also the fact that it does not make many decisions for you. While Flask does pick a templating engine for you, we won't make such decisions for your datastore or other parts. @@ -55,7 +55,7 @@ section about :ref:`design`. Web Development is Dangerous ---------------------------- -I'm not joking. Well, maybe a little. If you write a web +If you write a web 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 you are the only user that might leave data in your application, you still From d8c2ec4cd863112af4c55e1044c8d3024d58f21a Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 12 Mar 2012 15:03:26 -0700 Subject: [PATCH 2/4] Fixed linebreaks. --- docs/foreword.rst | 150 ++++++++++++++++++++++++---------------------- 1 file changed, 77 insertions(+), 73 deletions(-) diff --git a/docs/foreword.rst b/docs/foreword.rst index 539f2897..1fa214e6 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -1,100 +1,104 @@ -Foreword +Foreword ======== -Read this before you get started with Flask. This hopefully answers some -questions about the purpose and goals of the project, and when you -should or should not be using it. +Read this before you get started with Flask. This hopefully answers +some questions about the purpose and goals of the project, and when +you 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 to the simplicity and -small size of the framework, but also the fact that it does not make many -decisions for you. While Flask does pick a templating engine for you, we -won't make such decisions for your datastore or other parts. +As Flask considers it, the "micro" in microframework refers not only +to the simplicity and small size of the framework, but also the fact +that it does not make many decisions for you. While Flask does pick a +templating engine for you, we won't make such decisions for your +datastore or other parts. -However, to us the term “micro” does not mean that the whole implementation -has to fit into a single Python file. +However, to us the term “micro” does not mean that the whole +implementation has to fit into a single Python file. 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 limit you. -Because of that we made a few design choices that some people might find -surprising or unorthodox. 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 order to stay threadsafe. While this is a -really easy approach and saves you a lot of time, it might also cause some -troubles for very large applications because changes on these thread-local -objects can happen anywhere in the same thread. In order to solve these -problems we don't hide the thread locals for you but instead embrace them -and provide you with a lot of tools to make it as pleasant as possible to -work with them. +simple; they should not take a lot of code and yet they should not +limit you. Because of that we made a few design choices that some +people might find surprising or unorthodox. 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 order to stay +threadsafe. While this is a really easy approach and saves you a lot +of time, it might also cause some troubles for very large applications +because changes on these thread-local objects can happen anywhere in +the same thread. In order to solve these problems we don't hide the +thread locals for you but instead embrace them and provide you with a +lot of tools to make it as pleasant as possible to work with them. Flask is also based on convention over configuration, which means that -many things are preconfigured. For example, by convention templates and -static files are stored in subdirectories within the application's Python source tree. -While this can be changed you usually don't have to. +many things are preconfigured. For example, by convention templates +and static files are stored in subdirectories within the application's +Python source tree. While this can be changed you usually don't have +to. -The main reason Flask is called a "microframework" is the idea -to keep the core simple but extensible. There is no database abstraction +The main reason Flask is called a "microframework" is the idea to keep +the core simple but extensible. There is no database abstraction layer, no form validation or anything else where different libraries -already exist that can handle that. However Flask supports -extensions to add such functionality to 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. +already exist that can handle that. However Flask supports extensions +to add such functionality to 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. -Since Flask is based on a very solid foundation there is not a lot of code -in Flask itself. As such it's easy to adapt even for large applications -and we are making sure that you can either configure it as much as -possible by subclassing things or by forking the entire codebase. If you -are interested in that, check out the :ref:`becomingbig` chapter. +Since Flask is based on a very solid foundation there is not a lot of +code in Flask itself. As such it's easy to adapt even for large +applications and we are making sure that you can either configure it +as much as possible by subclassing things or by forking the entire +codebase. If you are interested in that, check out the +:ref:`becomingbig` chapter. If you are curious about the Flask design principles, head over to the section about :ref:`design`. -Web Development is Dangerous ----------------------------- +Web Development is Dangerous ---------------------------- -If you write a web -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 -you are the only user that might leave data in your application, you still -want that data to be stored securely. +If you write a web 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 you are the only user that +might leave data in your application, you still want that data to be +stored securely. -Unfortunately, there are many ways the security of a web application can be -compromised. Flask protects you against one of the most common security -problems of modern web applications: cross-site scripting (XSS). Unless -you deliberately mark insecure HTML as secure, Flask and the underlying -Jinja2 template engine have you covered. But there are many more ways to -cause security problems. +Unfortunately, there are many ways the security of a web application +can be compromised. Flask protects you against one of the most common +security problems of modern web applications: cross-site scripting +(XSS). Unless you deliberately mark insecure HTML as secure, Flask +and the underlying Jinja2 template engine have you covered. But there +are many more ways to cause security problems. The documentation will warn you about aspects of web development that -require attention to security. Some of these security concerns -are far more complex than one might think, and we all sometimes underestimate -the likelihood that a vulnerability will be exploited - until a clever -attacker figures out a way to exploit our applications. And don't think -that your application is not important enough to attract an attacker. -Depending on the kind of attack, chances are that automated bots are -probing for ways to fill your database with spam, links to malicious -software, and the like. +require attention to security. Some of these security concerns are +far more complex than one might think, and we all sometimes +underestimate the likelihood that a vulnerability will be exploited - +until a clever attacker figures out a way to exploit our applications. +And don't think that your application is not important enough to +attract an attacker. Depending on the kind of attack, chances are that +automated bots are 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. -The Status of Python 3 +The Status of Python 3 ---------------------- -Currently the Python community is in the process of improving libraries to -support the new iteration of the Python programming language. While the -situation is greatly improving there are still some issues that make it -hard for us to switch over to Python 3 just now. These problems are -partially caused by changes in the language that went unreviewed for too -long, partially also because we have not quite worked out how the lower- -level API should change to account for the Unicode differences in Python 3. +Currently the Python community is in the process of improving +libraries to support the new iteration of the Python programming +language. While the situation is greatly improving there are still +some issues that make it hard for us to switch over to Python 3 just +now. These problems are partially caused by changes in the language +that went unreviewed for too long, partially also because we have not +quite worked out how the lower- level API should change to account for +the Unicode differences in Python 3. -Werkzeug and Flask will be ported to Python 3 as soon as a solution for -the changes is found, and we will provide helpful tips how to upgrade -existing applications to Python 3. Until then, we strongly recommend -using Python 2.6 and 2.7 with activated Python 3 warnings during -development. If you plan on upgrading to Python 3 in the near future we -strongly recommend that you read `How to write forwards compatible -Python code `_. +Werkzeug and Flask will be ported to Python 3 as soon as a solution +for the changes is found, and we will provide helpful tips how to +upgrade existing applications to Python 3. Until then, we strongly +recommend using Python 2.6 and 2.7 with activated Python 3 warnings +during development. If you plan on upgrading to Python 3 in the near +future we strongly recommend that you read `How to write forwards +compatible Python code `_. From c78070d8623fb6f40bf4ef20a1109083ca79ef7a Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 12 Mar 2012 15:08:52 -0700 Subject: [PATCH 3/4] Wrapped paragraphs; changed some words. --- docs/foreword.rst | 149 ++++++++++++++++++++++------------------------ 1 file changed, 72 insertions(+), 77 deletions(-) diff --git a/docs/foreword.rst b/docs/foreword.rst index 1fa214e6..5751ccb7 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -1,104 +1,99 @@ -Foreword +Foreword ======== -Read this before you get started with Flask. This hopefully answers -some questions about the purpose and goals of the project, and when -you should or should not be using it. +Read this before you get started with Flask. This hopefully answers some +questions about the purpose and goals of the project, and when you +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 -to the simplicity and small size of the framework, but also the fact -that it does not make many decisions for you. While Flask does pick a -templating engine for you, we won't make such decisions for your -datastore or other parts. +Flask considers the "micro" in microframework to refer not only to the +simplicity and small size of the framework, but also to the fact that it does +not make many decisions for you. While Flask does pick a templating engine +for you, we won't make such decisions for your datastore or other parts. -However, to us the term “micro” does not mean that the whole -implementation has to fit into a single Python file. +However, to us the term “micro” does not mean that the whole implementation +has to fit into a single Python file. 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 -limit you. Because of that we made a few design choices that some -people might find surprising or unorthodox. 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 order to stay -threadsafe. While this is a really easy approach and saves you a lot -of time, it might also cause some troubles for very large applications -because changes on these thread-local objects can happen anywhere in -the same thread. In order to solve these problems we don't hide the -thread locals for you but instead embrace them and provide you with a -lot of tools to make it as pleasant as possible to work with them. +simple; they should not take a lot of code and yet they should not limit you. +Because of that we made a few design choices that some people might find +surprising or unorthodox. 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 order to stay threadsafe. While this is a +really easy approach and saves you a lot of time, it might also cause some +troubles for very large applications because changes on these thread-local +objects can happen anywhere in the same thread. In order to solve these +problems we don't hide the thread locals for you but instead embrace them +and provide you with a lot of tools to make it as pleasant as possible to +work with them. Flask is also based on convention over configuration, which means that -many things are preconfigured. For example, by convention templates -and static files are stored in subdirectories within the application's -Python source tree. While this can be changed you usually don't have -to. +many things are preconfigured. For example, by convention templates and +static files are stored in subdirectories within the application's Python source tree. +While this can be changed you usually don't have to. -The main reason Flask is called a "microframework" is the idea to keep -the core simple but extensible. There is no database abstraction +The main reason Flask is called a "microframework" is the idea +to keep the core simple but extensible. There is no database abstraction layer, no form validation or anything else where different libraries -already exist that can handle that. However Flask supports extensions -to add such functionality to 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. +already exist that can handle that. However Flask supports +extensions to add such functionality to 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. -Since Flask is based on a very solid foundation there is not a lot of -code in Flask itself. As such it's easy to adapt even for large -applications and we are making sure that you can either configure it -as much as possible by subclassing things or by forking the entire -codebase. If you are interested in that, check out the -:ref:`becomingbig` chapter. +Since Flask is based on a very solid foundation there is not a lot of code +in Flask itself. As such it's easy to adapt even for large applications +and we are making sure that you can either configure it as much as +possible by subclassing things or by forking the entire codebase. If you +are interested in that, check out the :ref:`becomingbig` chapter. If you are curious about the Flask design principles, head over to the section about :ref:`design`. -Web Development is Dangerous ---------------------------- +Web Development is Dangerous +---------------------------- -If you write a web 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 you are the only user that -might leave data in your application, you still want that data to be -stored securely. +If you write a web 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 you are the only user that might leave data in your application, +you still want that data to be stored securely. -Unfortunately, there are many ways the security of a web application -can be compromised. Flask protects you against one of the most common -security problems of modern web applications: cross-site scripting -(XSS). Unless you deliberately mark insecure HTML as secure, Flask -and the underlying Jinja2 template engine have you covered. But there -are many more ways to cause security problems. +Unfortunately, there are many ways the security of a web application can be +compromised. Flask protects you against one of the most common security +problems of modern web applications: cross-site scripting (XSS). Unless +you deliberately mark insecure HTML as secure, Flask and the underlying +Jinja2 template engine have you covered. But there are many more ways to +cause security problems. The documentation will warn you about aspects of web development that -require attention to security. Some of these security concerns are -far more complex than one might think, and we all sometimes -underestimate the likelihood that a vulnerability will be exploited - -until a clever attacker figures out a way to exploit our applications. -And don't think that your application is not important enough to -attract an attacker. Depending on the kind of attack, chances are that -automated bots are probing for ways to fill your database with spam, -links to malicious software, and the like. +require attention to security. Some of these security concerns +are far more complex than one might think, and we all sometimes underestimate +the likelihood that a vulnerability will be exploited - until a clever +attacker figures out a way to exploit our applications. And don't think +that your application is not important enough to attract an attacker. +Depending on the kind of attack, chances are that automated bots are +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. -The Status of Python 3 +The Status of Python 3 ---------------------- -Currently the Python community is in the process of improving -libraries to support the new iteration of the Python programming -language. While the situation is greatly improving there are still -some issues that make it hard for us to switch over to Python 3 just -now. These problems are partially caused by changes in the language -that went unreviewed for too long, partially also because we have not -quite worked out how the lower- level API should change to account for -the Unicode differences in Python 3. +Currently the Python community is in the process of improving libraries to +support the new iteration of the Python programming language. While the +situation is greatly improving there are still some issues that make it +hard for us to switch over to Python 3 just now. These problems are +partially caused by changes in the language that went unreviewed for too +long, partially also because we have not quite worked out how the lower- +level API should change to account for the Unicode differences in Python 3. -Werkzeug and Flask will be ported to Python 3 as soon as a solution -for the changes is found, and we will provide helpful tips how to -upgrade existing applications to Python 3. Until then, we strongly -recommend using Python 2.6 and 2.7 with activated Python 3 warnings -during development. If you plan on upgrading to Python 3 in the near -future we strongly recommend that you read `How to write forwards -compatible Python code `_. +Werkzeug and Flask will be ported to Python 3 as soon as a solution for +the changes is found, and we will provide helpful tips how to upgrade +existing applications to Python 3. Until then, we strongly recommend +using Python 2.6 and 2.7 with activated Python 3 warnings during +development. If you plan on upgrading to Python 3 in the near future we +strongly recommend that you read `How to write forwards compatible +Python code `_. From 8f568cfc19f5b5f2aa59b06d4e2b5b8d31423605 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 12 Mar 2012 17:12:55 -0700 Subject: [PATCH 4/4] Split foreword into two files; edited lots. --- docs/advanced_foreword.rst | 67 +++++++++++++++++++++ docs/foreword.rst | 118 ++++++++++++------------------------- 2 files changed, 104 insertions(+), 81 deletions(-) create mode 100644 docs/advanced_foreword.rst diff --git a/docs/advanced_foreword.rst b/docs/advanced_foreword.rst new file mode 100644 index 00000000..cc1a1843 --- /dev/null +++ b/docs/advanced_foreword.rst @@ -0,0 +1,67 @@ +Foreword for Experienced Programmers +==================================== + +This chapter is for programmers who have worked with other frameworks in the +past, and who may have more specific or esoteric concerns that the typical +user. + +Threads in Flask +---------------- + +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 limit you. Because +of that we made a few design choices that some people might find surprising or +unorthodox. 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 order to stay threadsafe. While this is a really easy approach and +saves you a lot of time, it might also cause some troubles for very large +applications because changes on these thread-local objects can happen anywhere +in the same thread. In order to solve these problems we don’t hide the thread +locals for you but instead embrace them and provide you with a lot of tools to +make it as pleasant as possible to work with them. + +Web Development is Dangerous +---------------------------- + +If you write a web 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 you are the only user that might leave data in your application, +you still want that data to be stored securely. + +Unfortunately, there are many ways the security of a web application can be +compromised. Flask protects you against one of the most common security +problems of modern web applications: cross-site scripting (XSS). Unless +you deliberately mark insecure HTML as secure, Flask and the underlying +Jinja2 template engine have you covered. But there are many more ways to +cause security problems. + +The documentation will warn you about aspects of web development that +require attention to security. Some of these security concerns +are far more complex than one might think, and we all sometimes underestimate +the likelihood that a vulnerability will be exploited - until a clever +attacker figures out a way to exploit our applications. And don't think +that your application is not important enough to attract an attacker. +Depending on the kind of attack, chances are that automated bots are +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. + +The Status of Python 3 +---------------------- + +Currently the Python community is in the process of improving libraries to +support the new iteration of the Python programming language. While the +situation is greatly improving there are still some issues that make it +hard for us to switch over to Python 3 just now. These problems are +partially caused by changes in the language that went unreviewed for too +long, partially also because we have not quite worked out how the lower- +level API should change to account for the Unicode differences in Python 3. + +Werkzeug and Flask will be ported to Python 3 as soon as a solution for +the changes is found, and we will provide helpful tips how to upgrade +existing applications to Python 3. Until then, we strongly recommend +using Python 2.6 and 2.7 with activated Python 3 warnings during +development. If you plan on upgrading to Python 3 in the near future we +strongly recommend that you read `How to write forwards compatible +Python code `_. diff --git a/docs/foreword.rst b/docs/foreword.rst index 5751ccb7..b186aba6 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -8,92 +8,48 @@ should or should not be using it. What does "micro" mean? ----------------------- -Flask considers the "micro" in microframework to refer not only to the -simplicity and small size of the framework, but also to the fact that it does -not make many decisions for you. While Flask does pick a templating engine -for you, we won't make such decisions for your datastore or other parts. +“Micro” does not mean that your whole web application has to fit into +a single Python file (although it certainly can). Nor does it mean +that Flask is lacking in functionality. The "micro" in microframework +means Flask aims to keep the core simple but extensible. Flask won't make +many decisions for you, such as what database to use. Those decisions that +it does make, such as what templating engine to use, are easy to change. +Everything else is up to you, so that Flask can be everything you need +and nothing you don't. -However, to us the term “micro” does not mean that the whole implementation -has to fit into a single Python file. +By default, Flask does not include a database abstraction layer, form +validation or anything else where different libraries already exist that can +handle that. Instead, FLask extensions add such functionality to your +application as if it was implemented in Flask itself. Numerous extensions +provide database integration, form validation, upload handling, various open +authentication technologies, and more. Flask may be "micro", but the +possibilities are endless. -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 limit you. -Because of that we made a few design choices that some people might find -surprising or unorthodox. 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 order to stay threadsafe. While this is a -really easy approach and saves you a lot of time, it might also cause some -troubles for very large applications because changes on these thread-local -objects can happen anywhere in the same thread. In order to solve these -problems we don't hide the thread locals for you but instead embrace them -and provide you with a lot of tools to make it as pleasant as possible to -work with them. +Convention over Configuration +----------------------------- -Flask is also based on convention over configuration, which means that -many things are preconfigured. For example, by convention templates and -static files are stored in subdirectories within the application's Python source tree. -While this can be changed you usually don't have to. +Flask is based on convention over configuration, which means that many things +are preconfigured. For example, by convention templates and static files are +stored in subdirectories within the application's Python source tree. While +this can be changed you usually don't have to. We want to minimize the time +you need to spend in order to get up and running, without assuming things +about your needs. -The main reason Flask is called a "microframework" is the idea -to keep the core simple but extensible. There is no database abstraction -layer, no form validation or anything else where different libraries -already exist that can handle that. However Flask supports -extensions to add such functionality to 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. +Growing Up +---------- -Since Flask is based on a very solid foundation there is not a lot of code -in Flask itself. As such it's easy to adapt even for large applications -and we are making sure that you can either configure it as much as -possible by subclassing things or by forking the entire codebase. If you -are interested in that, check out the :ref:`becomingbig` chapter. +Since Flask is based on a very solid foundation there is not a lot of code in +Flask itself. As such it's easy to adapt even for large applications and we +are making sure that you can either configure it as much as possible by +subclassing things or by forking the entire codebase. If you are interested +in that, check out the :ref:`becomingbig` chapter. -If you are curious about the Flask design principles, head over to the -section about :ref:`design`. +If you are curious about the Flask design principles, head over to the section +about :ref:`design`. -Web Development is Dangerous ----------------------------- +For the Stalwart and Wizened... +------------------------------- -If you write a web 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 you are the only user that might leave data in your application, -you still want that data to be stored securely. - -Unfortunately, there are many ways the security of a web application can be -compromised. Flask protects you against one of the most common security -problems of modern web applications: cross-site scripting (XSS). Unless -you deliberately mark insecure HTML as secure, Flask and the underlying -Jinja2 template engine have you covered. But there are many more ways to -cause security problems. - -The documentation will warn you about aspects of web development that -require attention to security. Some of these security concerns -are far more complex than one might think, and we all sometimes underestimate -the likelihood that a vulnerability will be exploited - until a clever -attacker figures out a way to exploit our applications. And don't think -that your application is not important enough to attract an attacker. -Depending on the kind of attack, chances are that automated bots are -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. - -The Status of Python 3 ----------------------- - -Currently the Python community is in the process of improving libraries to -support the new iteration of the Python programming language. While the -situation is greatly improving there are still some issues that make it -hard for us to switch over to Python 3 just now. These problems are -partially caused by changes in the language that went unreviewed for too -long, partially also because we have not quite worked out how the lower- -level API should change to account for the Unicode differences in Python 3. - -Werkzeug and Flask will be ported to Python 3 as soon as a solution for -the changes is found, and we will provide helpful tips how to upgrade -existing applications to Python 3. Until then, we strongly recommend -using Python 2.6 and 2.7 with activated Python 3 warnings during -development. If you plan on upgrading to Python 3 in the near future we -strongly recommend that you read `How to write forwards compatible -Python code `_. +If you're more curious about the minutiae of Flask's implementation, and +whether its structure is right for your needs, read the +:ref:`advanced_foreword`.