Revise foreword and Becoming Big docs, #484.
This commit is contained in:
Ron DuPlain
parent
ff5ee034b8
commit
7c79ce6e41
4 changed files with 118 additions and 102 deletions
|
|
@ -1,27 +1,26 @@
|
|||
.. _advanced_foreword:
|
||||
|
||||
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.
|
||||
Thread-Locals in Flask
|
||||
----------------------
|
||||
|
||||
Threads in Flask
|
||||
----------------
|
||||
|
||||
One of the design decisions with Flask was that simple tasks should be simple;
|
||||
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 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.
|
||||
of that, Flask has 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.
|
||||
|
||||
Web Development is Dangerous
|
||||
----------------------------
|
||||
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.
|
||||
|
|
@ -30,22 +29,22 @@ 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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
||||
The Status of Python 3
|
||||
----------------------
|
||||
|
|
@ -65,3 +64,5 @@ 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 <http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/>`_.
|
||||
|
||||
Continue to :ref:`installation` or the :ref:`quickstart`.
|
||||
|
|
|
|||
|
|
@ -3,45 +3,57 @@
|
|||
Becoming Big
|
||||
============
|
||||
|
||||
Your application is becoming more and more complex? If you suddenly
|
||||
realize that Flask does things in a way that does not work out for your
|
||||
application there are ways to deal with that.
|
||||
Here are your options when growing your codebase or scaling your application.
|
||||
|
||||
Flask is powered by Werkzeug and Jinja2, two libraries that are in use at
|
||||
a number of large websites out there and all Flask does is bring those
|
||||
two together. Being a microframework Flask does not do much more than
|
||||
combining existing libraries - there is not a lot of code involved.
|
||||
What that means for large applications is that it's very easy to take the
|
||||
code from Flask and put it into a new module within the applications and
|
||||
expand on that.
|
||||
Read the Source.
|
||||
----------------
|
||||
|
||||
Flask is designed to be extended and modified in a couple of different
|
||||
ways:
|
||||
Flask started in part to demonstrate how to build your own framework on top of
|
||||
existing well-used tools Werkzeug (WSGI) and Jinja (templating), and as it
|
||||
developed, it became useful to a wide audience. As you grow your codebase,
|
||||
don't just use Flask -- understand it. Read the source. Flask's code is
|
||||
written to be read; it's documentation published so you can use its internal
|
||||
APIs. Flask sticks to documented APIs in upstream libraries, and documents its
|
||||
internal utilities so that you can find the hook points needed for your
|
||||
project.
|
||||
|
||||
- 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.
|
||||
Hook. Extend.
|
||||
-------------
|
||||
|
||||
- Subclassing. The majority of functionality can be changed by creating
|
||||
a new subclass of the :class:`~flask.Flask` class and overriding
|
||||
methods provided for this exact purpose.
|
||||
The :ref:`api` docs are full of available overrides, hook points, and
|
||||
:ref:`signals`. You can provide custom classes for things like the request and
|
||||
response objects. Dig deeper on the APIs you use, and look for the
|
||||
customizations which are available out of the box in a Flask release. Look for
|
||||
ways in which your project can be refactored into a collection of utilities and
|
||||
Flask extensions. Explore the many extensions in the community, and look for
|
||||
patterns to build your own extensions if you do not find the tools you need.
|
||||
|
||||
- Forking. If nothing else works out you can just take the Flask
|
||||
codebase at a given point and copy/paste it into your application
|
||||
and change it. Flask is designed with that in mind and makes this
|
||||
incredible easy. You just have to take the package and copy it
|
||||
into your application's code and rename it (for example to
|
||||
`framework`). Then you can start modifying the code in there.
|
||||
Subclass.
|
||||
---------
|
||||
|
||||
Why consider Forking?
|
||||
The :class:`~flask.Flask` class has many methods designed for subclassing. You
|
||||
can quickly add or customize behavior by subclassing :class:`~flask.Flask` (see
|
||||
the linked method docs) and using that subclass wherever you instantiate an
|
||||
application class. This works well with :ref:`app-factories`.
|
||||
|
||||
Wrap with middleware.
|
||||
---------------------
|
||||
|
||||
The majority of code of Flask is within Werkzeug and Jinja2. These
|
||||
libraries do the majority of the work. Flask is just the paste that glues
|
||||
those together. For every project there is the point where the underlying
|
||||
framework gets in the way (due to assumptions the original developers
|
||||
had). This is natural because if this would not be the case, the
|
||||
framework would be a very complex system to begin with which causes a
|
||||
The :ref:`app-dispatch` chapter shows in detail how to apply middleware. You
|
||||
can introduce WSGI middleware to wrap your Flask instances and introduce fixes
|
||||
and changes at the layer between your Flask application and your HTTP
|
||||
server. Werkzeug includes several `middlewares
|
||||
<http://werkzeug.pocoo.org/docs/middlewares/>`_.
|
||||
|
||||
Fork.
|
||||
-----
|
||||
|
||||
If none of the above options work, fork Flask. The majority of code of Flask
|
||||
is within Werkzeug and Jinja2. These libraries do the majority of the work.
|
||||
Flask is just the paste that glues those together. For every project there is
|
||||
the point where the underlying framework gets in the way (due to assumptions
|
||||
the original developers had). This is natural because if this would not be the
|
||||
case, the framework would be a very complex system to begin with which causes a
|
||||
steep learning curve and a lot of user frustration.
|
||||
|
||||
This is not unique to Flask. Many people use patched and modified
|
||||
|
|
@ -55,8 +67,8 @@ 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
|
||||
------------------
|
||||
Scale like a pro.
|
||||
-----------------
|
||||
|
||||
For many web applications the complexity of the code is less an issue than
|
||||
the scaling for the number of users or data entries expected. Flask by
|
||||
|
|
@ -78,11 +90,11 @@ 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
|
||||
Discuss 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
|
||||
The Flask developers keep the framework accessible to users with codebases big
|
||||
and small. If 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 the tools for larger
|
||||
applications is getting feedback from users.
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ instructions for web development with Flask.
|
|||
:maxdepth: 2
|
||||
|
||||
foreword
|
||||
advanced_foreword
|
||||
installation
|
||||
quickstart
|
||||
tutorial/index
|
||||
|
|
|
|||
|
|
@ -8,48 +8,50 @@ 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.
|
||||
“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 extensions add such functionality to your
|
||||
application as if it was implemented in Flask itself. Numerous extensions
|
||||
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 the
|
||||
possibilities are endless.
|
||||
authentication technologies, and more. Flask may be "micro", but it's ready for
|
||||
production use on a variety of needs.
|
||||
|
||||
Convention over Configuration
|
||||
Configuration and Conventions
|
||||
-----------------------------
|
||||
|
||||
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.
|
||||
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 `templates` and `static` respectively. While this can be changed you
|
||||
usually don't have to, especially when getting started.
|
||||
|
||||
Growing Up
|
||||
----------
|
||||
Growing with Flask
|
||||
------------------
|
||||
|
||||
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.
|
||||
Once you have Flask up and running, you'll find a variety of extensions
|
||||
available in the community to integrate your project for production. The Flask
|
||||
core team reviews extensions and ensures approved extensions do not break with
|
||||
future releases.
|
||||
|
||||
If you are curious about the Flask design principles, head over to the section
|
||||
about :ref:`design`.
|
||||
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.
|
||||
|
||||
For the Stalwart and Wizened...
|
||||
-------------------------------
|
||||
Flask includes many hooks to customize its behavior. Should you need more
|
||||
customization, the Flask class is built for subclassing. 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're more curious about the minutiae of Flask's implementation, and
|
||||
whether its structure is right for your needs, read the
|
||||
Continue to :ref:`installation`, the :ref:`quickstart`, or the
|
||||
:ref:`advanced_foreword`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue