diff --git a/docs/advanced_foreword.rst b/docs/advanced_foreword.rst deleted file mode 100644 index 9c36158a8d..0000000000 --- a/docs/advanced_foreword.rst +++ /dev/null @@ -1,46 +0,0 @@ -Foreword for Experienced Programmers -==================================== - -Thread-Locals in Flask ----------------------- - -One of the design decisions in 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, Flask has 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. -This approach is convenient, but requires a valid -request context for dependency injection or when attempting to reuse code which -uses a value pegged to the request. The Flask project is honest about -thread-locals, does not hide them, and calls out in the code and documentation -where they are used. - -Develop for the Web with Caution --------------------------------- - -Always keep security in mind when building web applications. - -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. - -Flask is no different from any other framework in that you the developer must -build with caution, watching for exploits when building to your requirements. diff --git a/docs/config.rst b/docs/config.rst index bc16e4bac1..bdcbdcd43c 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -394,13 +394,11 @@ The following configuration values are used internally by Flask: Configuring from Python Files ----------------------------- -Configuration becomes more useful if you can store it in a separate file, -ideally located outside the actual application package. This makes -packaging and distributing your application possible via various package -handling tools (:doc:`/patterns/distribute`) and finally modifying the -configuration file afterwards. +Configuration becomes more useful if you can store it in a separate file, ideally +located outside the actual application package. You can deploy your application, then +separately configure it for the specific deployment. -So a common pattern is this:: +A common pattern is this:: app = Flask(__name__) app.config.from_object('yourapplication.default_settings') @@ -692,10 +690,8 @@ your configuration files. However here a list of good recommendations: code at all. If you are working often on different projects you can even create your own script for sourcing that activates a virtualenv and exports the development configuration for you. -- Use a tool like `fabric`_ in production to push code and - configurations separately to the production server(s). For some - details about how to do that, head over to the - :doc:`/patterns/fabric` pattern. +- Use a tool like `fabric`_ to push code and configuration separately + to the production server(s). .. _fabric: https://www.fabfile.org/ diff --git a/docs/design.rst b/docs/design.rst index a5ef2568cd..066cf107c1 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -130,9 +130,25 @@ being present. You can easily use your own templating language, but an extension could still depend on Jinja itself. -Micro with Dependencies +What does "micro" mean? ----------------------- +“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. + +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 supports extensions to 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 it's ready for +production use on a variety of needs. + Why does Flask call itself a microframework and yet it depends on two libraries (namely Werkzeug and Jinja2). Why shouldn't it? If we look over to the Ruby side of web development there we have a protocol very @@ -201,5 +217,12 @@ requirements and Flask could not meet those if it would force any of this into the core. The majority of web applications will need a template engine in some sort. However not every application needs a SQL database. +As your codebase grows, you are free to make the design decisions appropriate +for your project. Flask will continue to provide a very simple glue layer to +the best that Python has to offer. You can implement advanced patterns in +SQLAlchemy or another database tool, introduce non-relational data persistence +as appropriate, and take advantage of framework-agnostic tools built for WSGI, +the Python web interface. + The idea of Flask is to build a good foundation for all applications. Everything else is up to you or extensions. diff --git a/docs/foreword.rst b/docs/foreword.rst deleted file mode 100644 index 28b272d716..0000000000 --- a/docs/foreword.rst +++ /dev/null @@ -1,53 +0,0 @@ -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. - -What does "micro" mean? ------------------------ - -“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. - -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 supports extensions to 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 it's ready for -production use on a variety of needs. - -Configuration and Conventions ------------------------------ - -Flask has many configuration values, with sensible defaults, and a few -conventions when getting started. By convention, templates and static -files are stored in subdirectories within the application's Python -source tree, with the names :file:`templates` and :file:`static` -respectively. While this can be changed, you usually don't have to, -especially when getting started. - -Growing with Flask ------------------- - -Once you have Flask up and running, you'll find a variety of extensions -available in the community to integrate your project for production. - -As your codebase grows, you are free to make the design decisions appropriate -for your project. Flask will continue to provide a very simple glue layer to -the best that Python has to offer. You can implement advanced patterns in -SQLAlchemy or another database tool, introduce non-relational data persistence -as appropriate, and take advantage of framework-agnostic tools built for WSGI, -the Python web interface. - -Flask includes many hooks to customize its behavior. Should you need -more customization, the Flask class is built for subclassing. If you are -curious about the Flask design principles, head over to the section -about :doc:`design`. diff --git a/docs/htmlfaq.rst b/docs/htmlfaq.rst deleted file mode 100644 index 4807c2662d..0000000000 --- a/docs/htmlfaq.rst +++ /dev/null @@ -1,206 +0,0 @@ -HTML/XHTML FAQ -============== - -The Flask documentation and example applications are using HTML5. You -may notice that in many situations, when end tags are optional they are -not used, so that the HTML is cleaner and faster to load. Because there -is much confusion about HTML and XHTML among developers, this document tries -to answer some of the major questions. - - -History of XHTML ----------------- - -For a while, it appeared that HTML was about to be replaced by XHTML. -However, barely any websites on the Internet are actual XHTML (which is -HTML processed using XML rules). There are a couple of major reasons -why this is the case. One of them is Internet Explorer's lack of proper -XHTML support. The XHTML spec states that XHTML must be served with the MIME -type :mimetype:`application/xhtml+xml`, but Internet Explorer refuses -to read files with that MIME type. -While it is relatively easy to configure Web servers to serve XHTML properly, -few people do. This is likely because properly using XHTML can be quite -painful. - -One of the most important causes of pain is XML's draconian (strict and -ruthless) error handling. When an XML parsing error is encountered, -the browser is supposed to show the user an ugly error message, instead -of attempting to recover from the error and display what it can. Most of -the (X)HTML generation on the web is based on non-XML template engines -(such as Jinja, the one used in Flask) which do not protect you from -accidentally creating invalid XHTML. There are XML based template engines, -such as Kid and the popular Genshi, but they often come with a larger -runtime overhead and are not as straightforward to use because they have -to obey XML rules. - -The majority of users, however, assumed they were properly using XHTML. -They wrote an XHTML doctype at the top of the document and self-closed all -the necessary tags (``
`` becomes ``
`` or ``

`` in XHTML). -However, even if the document properly validates as XHTML, what really -determines XHTML/HTML processing in browsers is the MIME type, which as -said before is often not set properly. So the valid XHTML was being treated -as invalid HTML. - -XHTML also changed the way JavaScript is used. To properly work with XHTML, -programmers have to use the namespaced DOM interface with the XHTML -namespace to query for HTML elements. - -History of HTML5 ----------------- - -Development of the HTML5 specification was started in 2004 under the name -"Web Applications 1.0" by the Web Hypertext Application Technology Working -Group, or WHATWG (which was formed by the major browser vendors Apple, -Mozilla, and Opera) with the goal of writing a new and improved HTML -specification, based on existing browser behavior instead of unrealistic -and backwards-incompatible specifications. - -For example, in HTML4 ``Hello``. However, since people were using -XHTML-like tags along the lines of ````, browser vendors implemented -the XHTML syntax over the syntax defined by the specification. - -In 2007, the specification was adopted as the basis of a new HTML -specification under the umbrella of the W3C, known as HTML5. Currently, -it appears that XHTML is losing traction, as the XHTML 2 working group has -been disbanded and HTML5 is being implemented by all major browser vendors. - -HTML versus XHTML ------------------ - -The following table gives you a quick overview of features available in -HTML 4.01, XHTML 1.1 and HTML5. (XHTML 1.0 is not included, as it was -superseded by XHTML 1.1 and the barely-used XHTML5.) - -.. tabularcolumns:: |p{9cm}|p{2cm}|p{2cm}|p{2cm}| - -+-----------------------------------------+----------+----------+----------+ -| | HTML4.01 | XHTML1.1 | HTML5 | -+=========================================+==========+==========+==========+ -| ``value`` | |Y| [1]_ | |N| | |N| | -+-----------------------------------------+----------+----------+----------+ -| ``
`` supported | |N| | |Y| | |Y| [2]_ | -+-----------------------------------------+----------+----------+----------+ -| ``